Use case: apps
Sports betting app API: odds, fixtures and results in one feed
Tipping comps, form guides, sports media sites, bet trackers and pick'em games all need the same base layer: who is playing when, what the bookmakers think, and how it ended. One schema covers all three across every code Australians follow.
Games and start times
Every event has its league, its home and away teams with keys and names, and a start time in UTC, taken from official fixtures.
What is happening now
One status per game: scheduled, live, final, postponed or cancelled, so your app can show the right state without guessing.
How it finished
Every outcome official results can settle comes back won, lost, void or dead heat, on the same outcome IDs as the prices, so grading a bet is a lookup rather than a mapping exercise.
Every book's view
Head to head, line, total, props and alternate lines from up to 37 Australian books, with Pinnacle and the Betfair Exchange beside them.
Reference data
/v1/teams and /v1/players return the keys, IDs and names for each league.
Already store ESPN IDs?
/v1/events/lookup finds our event from an official event ID, ESPN's or the AFL's and NRL's own, up to 100 at a time.
Architecture
Sync on the server, serve from your database
The pattern that works for apps of any size:
- A small job on your server calls the API about every five minutes for the leagues you cover.
- It writes events, odds and results into your own database, keyed by event ID and outcome ID.
- Your app and website read from your database, never from the API directly.
The key never ships inside a mobile app or web page, your users never wait on a third party, and a busy Saturday on your app does not turn into a busy Saturday on your quota. The same job picks up results from /v1/results after the final siren; a result can arrive in parts, marked partial until every market is settled.
// Settle stored bets from /v1/results. Each bet keeps the outcome ID it was
// placed on: the same ID the odds response gave its price.
const url = new URL("https://api.sockodds.com/v1/results");
url.searchParams.set("league", "afl");
url.searchParams.set("starts_after", "2027-03-12T00:00:00Z");
const res = await fetch(url, { headers: { Authorization: `Bearer ${process.env.SOCKODDS_KEY}` } });
const { data } = await res.json();
const graded = new Map(); // outcome ID -> { verdict, dead_heat_factor }
for (const result of data) {
for (const o of result.outcomes) graded.set(o.id, o);
}
function settle(bet) {
const o = graded.get(bet.outcomeId);
if (!o) return { state: "pending", returns: null }; // not settled by official results yet
if (o.verdict === "won") return { state: "won", returns: bet.stake * bet.price };
if (o.verdict === "void") return { state: "void", returns: bet.stake };
if (o.verdict === "dead_heat") return { state: "dead heat", returns: bet.stake * o.dead_heat_factor * bet.price };
return { state: "lost", returns: 0 };
}Freshness
What to promise your users
Prices are re-read about every five minutes and pre-match comes first. Live games show a live status, but in-play prices move on that same rhythm, so present them as recent rather than live. Every quote has a timestamp, which makes "updated 3 min ago" easy to show and honest to say.
Which plan? A tipping app on the AFL and NRL with the big three books can launch free. Once you need other codes or more books, Rookie covers every league and ten bookmakers. Apps that sync everything all day usually belong on Pro or Platform. Compare plans
Questions
Building an app on the feed
Can I call the API from my mobile app or website?
Not directly. Anyone can lift a key out of app or browser code. Call the API from your server and give your app your own endpoint or database.
Are team colours and logos included?
No. The teams data carries keys and names; colours and logos come from your own design.
How do I handle a postponed or cancelled game?
Watch status: it turns postponed or cancelled, and scheduled_start always holds the current start time. A price not seen for ten minutes is held back rather than served as current.
Can every market be graded from the results?
Not every one. /v1/results publishes only the outcomes official evidence settles, never a guess, so a missing verdict means wait or settle it another way. While some markets are still open, settlement says partial and pending_markets counts them.
Start now
Your first Australian price is one request away.
Free key, no card, AFL and NRL included. Keys are issued on sockodds.com.