Quickstart

Odds API quickstart: real Australian prices in five minutes

Four steps from no key to a list of bookmaker prices on your screen, then the handful of habits that keep responses small and your code calm when something goes wrong. The full reference lives in the SockOdds documentation.

Get a free key

Sign up on sockodds.com with an email address and a mobile number for a text code (Australian, US, Canadian, UK and New Zealand numbers work). The key is shown once, so copy it straight away. No card is needed for the Developer plan.

Get a free key
Keep it on your server

Put the key in an environment variable such as SOCKODDS_KEY and send it as Authorization: Bearer followed by the key. Do not ship it in browser or app code: route calls through your own server, or copy the data into a database you control and serve the front end from there.
Ask for a league

One call to /v1/odds with a league returns its live and upcoming games with every market and every bookmaker your plan covers. The free plan includes the AFL, NRL, NFL and MLB.
Read the prices

Each event lists its bookmakers, each bookmaker its markets, and each market its outcomes with a decimal price. The examples below print every book's head to head price for every game.

export SOCKODDS_KEY="paste-your-key-here"

curl -G https://api.sockodds.com/v1/odds \
  -d league=afl \
  -d markets=winner \
  -H "Authorization: Bearer $SOCKODDS_KEY"

import os
import requests

resp = requests.get(
    "https://api.sockodds.com/v1/odds",
    params={"league": "afl", "markets": "winner"},
    headers={"Authorization": f"Bearer {os.environ['SOCKODDS_KEY']}"},
    timeout=20,
)
resp.raise_for_status()

for event in resp.json()["data"]:
    prices = {}  # outcome name -> {bookmaker: decimal price}
    for book in event["bookmakers"]:
        for market in book["markets"]:
            for o in market["outcomes"]:
                if o.get("available"):
                    prices.setdefault(o["name"], {})[book["key"]] = o["decimal_odds"]
    print(event["name"], prices)

// Node 18 or later (built-in fetch), run as an ES module
const url = new URL("https://api.sockodds.com/v1/odds");
url.searchParams.set("league", "afl");
url.searchParams.set("markets", "winner");

const res = await fetch(url, { headers: { Authorization: `Bearer ${process.env.SOCKODDS_KEY}` } });
if (!res.ok) throw new Error(`HTTP ${res.status}`);
const { data } = await res.json();

for (const event of data) {
  const prices = {}; // outcome name -> { bookmaker: decimal price }
  for (const book of event.bookmakers) {
    for (const market of book.markets) {
      for (const o of market.outcomes) {
        if (o.available) (prices[o.name] ??= {})[book.key] = o.decimal_odds;
      }
    }
  }
  console.log(event.name, prices);
}

Field guide

Reading an event

id: The game's ID, such as ev_t03024es3aee. The same game keeps it in prices, results and history.
name, league: A display name such as "Carlton v Richmond", and the league's key and name.
participants: Each team, or each player in tennis and the UFC, with its role (home and away, or competitor_1 and competitor_2), a key and a name.
scheduled_start, status: The start time in UTC, and one of scheduled, live, final, postponed or cancelled.
bookmakers: One entry per book on your plan that is pricing the game, each with its markets.
markets: An ID, a key such as winner, a period, a subject (the player, for props) and the outcomes.
outcomes: The side, the line for lines and totals, decimal_odds, implied_probability, available, alternate and observed_at. An outcome's ID is the same at every bookmaker.
results: A separate call: /v1/results grades finished games outcome by outcome, on the same IDs.

Markets

A key, a period and a side

Every market has a plain key that means the same thing in every sport, a period, and for props a subject. Every outcome has a side:

key: winner head to head, result with the draw, handicap the line, total_points (or total_goals, total_runs) the total, and props such as player_disposals_over_under.
period: full, half_1, quarter_2, innings_1_to_5, set_1 and so on, as each league allows.
side: home or away, competitor_1 or competitor_2 in tennis and the UFC, draw, over or under, and yes for scorer markets.

So the over on the match total is side over of total_points for period full, and the home side's first-half line is side home of handicap for half_1. /v1/markets?league=afl lists every market a league can carry.

Keep it quick

Ask for less, get it sooner

One league per call, with league.
Only the markets you show, with markets: up to 20 market keys, such as winner,handicap,player_disposals_over_under. A prop key covers every player.
Only the books you show, with bookmakers, or a whole region with regions=au.
Leave alternate lines off unless you need them: alternates=true makes responses much larger.
Poll about every five minutes. Prices refresh about that often, so polling faster spends quota for nothing. Compare each outcome's observed_at with your last copy to see what moved.

paging.py

# Big leagues come back in pages. links.next is the full
# address of the next page, filters included; stop at null.
url = "https://api.sockodds.com/v1/odds?league=nfl&limit=50"
events = []
while url:
    page = requests.get(url, headers=HEADERS, timeout=20).json()
    events += page["data"]
    url = page["links"]["next"]

When it goes wrong

Errors and what to do

400: A parameter is wrong, and the detail names it. Fix the request rather than retrying.
401: The key is missing, mistyped or has stray whitespace. Send it exactly as Authorization: Bearer YOUR_KEY.
403: The key works, but your plan does not include what you asked for, such as an event in a league outside the free plan, or the Pro history. Email [email protected] if that is a surprise.
429: Over your per-minute limit: wait for the seconds in retry-after, then carry on. The same status titled "Monthly allowance reached" means the month's objects are used.
5xx: Retry once after a short, slightly random pause.

Every error is application/problem+json with a title, the status and a detail that says what went wrong.

Going further

The full reference

Fast Odds API keys are SockOdds keys, so the SockOdds documentation is the complete manual:

API documentation, every endpoint and field
OpenAPI 3.1 specification

Then pick a job: arbitrage, +EV, odds comparison or alert bots.

Start now

Your first Australian price is one request away.

Free key, no card, AFL and NRL included. Keys are issued on sockodds.com.

Get a free key See the quickstart

Odds API quickstart: real Australian prices in five minutes

Get a free key

Keep it on your server

Ask for a league

Read the prices