NBL API Docs: Game Odds, Player Props and History

Endpoints

Use the right NBL endpoint

The public API separates match discovery, match records, odds, and results. A stream sends changes after an initial snapshot.

Coverage

Find NBL coverage and bookmakers

Request GET /v1/coverage?sport=basketball&league=NBL to build your league and bookmaker filters. The coverage response contains bookmakers, leagues, and approximate markets with an as_of timestamp. Use the canonical keys returned by GET /v1/bookmakers when filtering odds.

curl -sS -G 'https://api.odds-api.net/v1/coverage' \
  --data-urlencode 'sport=basketball' \
  --data-urlencode 'league=NBL'

The bookmakers field on a NBL event shows which bookmakers are attached to that match. The odds snapshot shows their current selections. For bookmaker-specific context, see Sportsbet, TAB, Ladbrokes, and Bet365.

Events and results

Discover matches and read results

Page /v1/events with sport=basketball and league=NBL. Set start_from and start_to as Unix seconds when you need live matches as well as upcoming ones. Without start_from, the endpoint starts at the current time.

curl -sS -G 'https://api.odds-api.net/v1/events' \
  -H "X-API-Key: $ODDS_API_KEY" \
  --data-urlencode 'sport=basketball' \
  --data-urlencode 'league=NBL' \
  --data-urlencode 'limit=200'

Illustrative response. Use the returned IDs and times; these values are examples.

{
  "count": 1,
  "items": [
    {
      "away_team": "Sydney Kings",
      "bookmakers": {
        "sportsbet": null,
        "tab": null
      },
      "event_id": "nbl-example-001",
      "home_team": "Tasmania JackJumpers",
      "league": "NBL",
      "sport": "basketball",
      "start_time": 1788472800
    }
  ],
  "next_cursor": null
}

GET /v1/events/{event_id}

GET /v1/events/{event_id}/results

A match without a result record returns:

{
  "event_id": "nbl-example-001",
  "result": null,
  "status": "pending"
}

Odds snapshots

Request every available odds market

Leave bookmakers, types, market_keys, and periods out of the request. That returns all odds rows available to your account for the chosen match. price_fields=all includes the supported price fields; include_unavailable=true also returns suspended rows.

curl -sS -G "https://api.odds-api.net/v1/events/$EVENT_ID/odds/snapshot" \
  -H "X-API-Key: $ODDS_API_KEY" \
  --data-urlencode 'limit=10000' \
  --data-urlencode 'price_fields=all' \
  --data-urlencode 'include_unavailable=true' \
  --data-urlencode 'include_source=true'

Continue with the snapshot's next_cursor until it is null. Save the resume token from the first page before opening the stream, so changes during later pages can be replayed. Match stream changes by the odds-row id.

Illustrative snapshot with match odds and a player points prop. API prices are decimal.

{
  "as_of_ts_ms": 1788472500000,
  "event_id": "nbl-example-001",
  "items": [
    {
      "bet_type": "moneyline",
      "bookmaker": "sportsbet",
      "event_id": "nbl-example-001",
      "fair_odds": 1.95,
      "id": "line-example-001",
      "is_available": true,
      "market_key": "moneyline",
      "odds": 1.91,
      "odds_no_vig": 1.96,
      "period": "full game",
      "selection_key": "selection-example-home",
      "selection_name": "Tasmania JackJumpers",
      "side": "home"
    },
    {
      "bet_type": "player prop",
      "bookmaker": "sportsbet",
      "event_id": "nbl-example-001",
      "id": "line-example-002",
      "is_available": true,
      "line": "19.5",
      "market_key": "player points",
      "odds": 2.05,
      "period": "full game",
      "player_name": "Example Player",
      "selection_key": "selection-example-prop-over",
      "side": "over"
    }
  ],
  "next_cursor": null,
  "resume": "1788472500000-0",
  "ttl_seconds": 120
}

Markets

Read NBL market keys

market_key identifies the normalized market in an odds row. Use market_keys in a query only when your product needs a subset. Keep period, line, side, and player_name when comparing two prices.

Use handicap for line betting, total for combined points, and literal player points, player rebounds, player assists and player threes keys for props. Separate each game period and threshold. Keep the period, line, player, and side when comparing exact prop selections across bookmakers.

Basketball market matching

Separate NBL games, halves and quarters

A game line, first-half line and first-quarter line are three different bets. Keep the market's period alongside its team, line and side.

Build a first-quarter view

Load the selected NBL game's snapshot without a periods filter. Follow every next_cursor, then use the returned period labels to separate game, half and quarter markets.

curl -sS -G "https://api.odds-api.net/v1/events/$EVENT_ID/odds/snapshot" \
  -H "X-API-Key: $ODDS_API_KEY" \
  --data-urlencode 'bookmakers=sportsbet,tab,ladbrokes' \
  --data-urlencode 'price_fields=all'

# rows contains items collected from every snapshot page.
def period_label(row):
    return str(row.get("period_str") or row.get("period") or "").strip().lower()

first_quarter = [row for row in rows if period_label(row) == "1st quarter"]
first_half = [row for row in rows if period_label(row) == "1st half"]

Use period_str when present; compact responses put the display label in period. Keep the label with the market key, team, line and side when matching prices. A numeric period alone can be shared by a half and a quarter. The server's periods filter matches the stored period value, so do not substitute a display label for a numeric value.

Keep two-way and three-way results separate

moneyline is a two-way market. moneyline 3w includes a draw selection. Match the period and market rules before comparing prices; a regulation-time result and an overtime-inclusive game winner are different bets.

Load NBL player markets

Points, rebounds, assists and made threes use distinct market keys. Group by player_name, then keep the period label, line and side on every row.

curl -sS -G "https://api.odds-api.net/v1/events/$EVENT_ID/odds/snapshot" \
  -H "X-API-Key: $ODDS_API_KEY" \
  --data-urlencode 'market_keys=player points,player rebounds,player assists,player threes' \
  --data-urlencode 'price_fields=all' \
  --data-urlencode 'include_unavailable=true'

A player points line of 19.5 is a betting threshold. Use the returned odds and availability state to display the offered bet; do not interpret the line as the player's recorded score.

Compare freshness by bookmaker

Read bookmaker_as_of_ts_ms for the bookmaker being displayed. The top-level snapshot timestamp can advance when a different bookmaker updates, so it does not establish the age of every quote.

Historical data

Track NBL selection prices over time

Build a price chart for one NBL game line, total or player selection. Keep the game period and exact threshold fixed as you compare timestamped bookmaker quotes.

History access is required. History Lite includes 30 days of odds history; your account's history access determines the query window.

Choose the match and selection

Keep the event_id and selection_key from a match odds snapshot. Copy the selection key exactly. Set FROM_TS and TO_TS to ISO 8601 UTC timestamps within your history window, then run:

curl -sS -G "https://api.odds-api.net/v1/events/$EVENT_ID/odds/history" \
  -H "X-API-Key: $ODDS_API_KEY" \
  --data-urlencode "selection_key=$SELECTION_KEY" \
  --data-urlencode "from_ts=$FROM_TS" \
  --data-urlencode "to_ts=$TO_TS" \
  --data-urlencode 'bookmakers=sportsbet,tab' \
  --data-urlencode 'price_type=odds' \
  --data-urlencode 'price_fields=all' \
  --data-urlencode 'include_unavailable=true' \
  --data-urlencode 'limit_points_per_bookmaker=2000' \
  --output nbl-history.json

Read a bookmaker's price series

series contains one entry per bookmaker. Each point carries tick_ts, is_available and its price fields. Use the timestamp for the chart's horizontal axis and the price for its vertical axis.

{
  "bookmaker_name": "sportsbet",
  "points": [
    {"tick_ts": "2026-10-01T06:00:00Z", "is_available": true, "odds": 2.2},
    {"tick_ts": "2026-10-01T06:15:00Z", "is_available": true, "odds": 2.1},
    {"tick_ts": "2026-10-01T06:30:00Z", "is_available": true, "odds": 2.0}
  ]
}

Opening, latest and pre-match closing prices

The first and last points describe your requested time window. For a pre-match closing price, use the last available point at or before tip-off time. A sample limit can shorten a series; narrow the time window when a bookmaker reaches limit_points_per_bookmaker.

Continue a line-movement chart

After loading historical points, follow that selection through the history SSE stream. Save each stream resume token and pass it as since when reconnecting.

curl -N -G "https://api.odds-api.net/v1/events/$EVENT_ID/odds/history/stream" \
  -H "X-API-Key: $ODDS_API_KEY" \
  --data-urlencode "selection_key=$SELECTION_KEY" \
  --data-urlencode 'bookmakers=sportsbet,tab' \
  --data-urlencode 'price_fields=all' \
  --data-urlencode 'include_unavailable=true'

Use /v1/events/{event_id}/odds/history/ws for WebSockets with the same filters. A resync message means reload the bounded history query before continuing the chart.

Price analysis

Measure NBL margin and price movement

Calculate implied probabilities and bookmaker overround for NBL game markets, then measure how a selected line or player price changes before tip-off.

The API returns odds, odds_no_vig and fair_odds with price_fields=all. Calculate the statistics below in your app from snapshot rows or historical points.

A two-outcome head-to-head example

With 1.75 on Tasmania and 2.25 on Sydney in a two-way market, implied probabilities are 57.14% and 44.44%. The overround is 1.59%; proportional no-vig probabilities are 56.25% and 43.75%.

prices = [1.75, 2.25]
implied = [1 / price for price in prices]
book = sum(implied)
overround_pct = (book - 1) * 100
no_vig_pct = [probability / book * 100 for probability in implied]

Use all outcomes from the same bookmaker, market, line and period. A three-way market includes the draw. Do not mix opposing prices from different bookmakers when measuring one bookmaker's margin.

Summarise historical prices with Python

Download nbl_odds_analysis.py. It reads the history JSON saved above and reports each bookmaker's first, last, minimum and maximum price, sample count, price change and probability change. It sorts by timestamp and excludes suspended or invalid prices.

python nbl_odds_analysis.py nbl-history.json

# Add a market calculation using your own matched prices.
python nbl_odds_analysis.py nbl-history.json --home-odds 1.75 --away-odds 2.25

A player-points price moving from 2.20 to 2.00 shortens by 9.09%. Its implied probability moves from 45.45% to 50.00%, a change of 4.55 percentage points.

Match results and player markets

The game result endpoint returns pending or available with its source result record. Player points, rebounds and assists odds describe bookmaker selections, not recorded player box scores or play-by-play.

Combine the result record with your stored match and price observations to analyse completed matches. Keep the event ID, selection identity, bookmaker and observation time alongside each calculation.

SSE and WebSocket

Follow NBL odds updates

Open one odds stream for each NBL match you are tracking. Pass the snapshot's resume token as since, with the same price and availability options used for the snapshot. The stream returns changes, not another full odds list.

curl -N -G "https://api.odds-api.net/v1/events/$EVENT_ID/odds/stream" \
  -H "X-API-Key: $ODDS_API_KEY" \
  --data-urlencode "since=$RESUME" \
  --data-urlencode 'catchup=true' \
  --data-urlencode 'price_fields=all' \
  --data-urlencode 'include_unavailable=true' \
  --data-urlencode 'include_source=true'

Illustrative payload for an SSE delta event. The odd.id identifies the row to replace.

{
  "changes": [
    {
      "odd": {
        "bet_type": "moneyline",
        "bookmaker": "sportsbet",
        "event_id": "nbl-example-001",
        "fair_odds": 1.95,
        "id": "line-example-001",
        "is_available": true,
        "market_key": "moneyline",
        "odds": 1.95,
        "odds_no_vig": 1.96,
        "period": "full game",
        "selection_key": "selection-example-home",
        "selection_name": "Tasmania JackJumpers",
        "side": "home"
      },
      "op": "upsert"
    }
  ],
  "event_id": "nbl-example-001",
  "resume": "1788472515000-0"
}

1. delta: apply each change to the local odds row keyed by odd.id. Save the latest resume token.
2. heartbeat: keep the connection open. It has no odds changes.
3. resync: discard the local odds view, reload every snapshot page, then reopen the stream with the new token.
4. Disconnect: reconnect with since=<last_resume> and catchup=true. Back off after errors.

The WebSocket route is /v1/events/{event_id}/odds/ws. It accepts the same query filters and sends JSON envelopes shaped as {"event":"delta","data":{...}}. Keep API keys on your server. Match discovery and results still use their REST endpoints.

For a line chart or audit, request /v1/events/{event_id}/odds/history with a selection_key from the snapshot and bounded ISO 8601 from_ts and to_ts values. The history stream follows one selection. Both history routes require history access; use the match snapshot and odds stream for current state.

Field dictionary

Understand the NBL data

These fields are the pieces an NBL product needs to join matches, compare the same bet, show current prices, and recover a live connection. Optional fields can be absent or null.

Match identity and timing

Markets and selections

Prices and state

NBL player props are betting markets. The public contract does not expose a separate player box-score or play-by-play endpoint.

Production

Handle normal production states

Keep ODDS_API_KEY on your server. Use the API reference for current response codes and parameter limits, and status and support when an endpoint is unavailable.

Python example

Run the complete NBL example

The Python example pages a rolling NBL schedule, requests match records and results, loads every odds snapshot page, and opens a stream for each match. It writes JSON Lines, so another process can consume the complete records. Set a suitable discovery window and connection budget for your product.

python -m pip install httpx
export ODDS_API_KEY='your_api_key'
python nbl_full_feed.py

Save nbl_full_feed.py and run it from your server. Set NBL_PAST_HOURS and NBL_FUTURE_HOURS to change the rolling match window. Set ODDS_API_BASE_URL for a different API environment.

"""Discover NBL games, load every available odds row, and follow each game.

Install: python -m pip install httpx
Run:     ODDS_API_KEY=your_key python nbl_full_feed.py

The program writes JSON Lines to stdout. Set NBL_PAST_HOURS and
NBL_FUTURE_HOURS to change the rolling discovery window.
"""

from __future__ import annotations

import asyncio
import json
import os
import random
import sys
import time
from typing import Any, AsyncIterator

import httpx


BASE_URL = os.getenv("ODDS_API_BASE_URL", "https://api.odds-api.net/v1").rstrip("/") + "/"
API_KEY = os.getenv("ODDS_API_KEY", "").strip()
PAST_HOURS = int(os.getenv("NBL_PAST_HOURS", "8"))
FUTURE_HOURS = int(os.getenv("NBL_FUTURE_HOURS", "48"))
DISCOVERY_SECONDS = int(os.getenv("NBL_DISCOVERY_SECONDS", "300"))
ODDS_SHAPE = {
    "price_fields": "all",
    "include_unavailable": "true",
    "include_source": "true",
}


def emit(kind: str, **payload: Any) -> None:
    print(json.dumps({"kind": kind, **payload}, separators=(",", ":")), flush=True)


async def get_json(client: httpx.AsyncClient, path: str, params: dict | None = None) -> dict:
    response = await client.get(path, params=params)
    response.raise_for_status()
    return response.json()


async def nbl_events(client: httpx.AsyncClient) -> list[dict]:
    now = int(time.time())
    params = {
        "sport": "basketball",
        "league": "NBL",
        "start_from": now - PAST_HOURS * 3600,
        "start_to": now + FUTURE_HOURS * 3600,
        "limit": 1000,
    }
    events: list[dict] = []
    while True:
        page = await get_json(client, "events", params)
        events.extend(page.get("items") or [])
        cursor = page.get("next_cursor")
        if not cursor:
            return events
        params["cursor"] = cursor


async def complete_snapshot(client: httpx.AsyncClient, event_id: str) -> tuple[dict, dict[str, dict]]:
    params = {"limit": 10000, **ODDS_SHAPE}
    rows: dict[str, dict] = {}
    first_page: dict | None = None
    while True:
        page = await get_json(client, f"events/{event_id}/odds/snapshot", params)
        if first_page is None:
            first_page = page
        for odd in page.get("items") or []:
            if odd.get("id"):
                rows[str(odd["id"])] = odd
        cursor = page.get("next_cursor")
        if not cursor:
            break
        params["cursor"] = cursor

    # Start the stream at the first page's resume token. Changes that arrive
    # while later snapshot pages load can then be replayed by the stream.
    return first_page or {}, rows


async def sse_messages(response: httpx.Response) -> AsyncIterator[tuple[str, dict]]:
    event = "message"
    data: list[str] = []
    async for line in response.aiter_lines():
        if line == "":
            if data:
                yield event, json.loads("\n".join(data))
            event, data = "message", []
        elif line.startswith("event:"):
            event = line[6:].strip()
        elif line.startswith("data:"):
            data.append(line[5:].lstrip())
    if data:
        yield event, json.loads("\n".join(data))


def apply_delta(rows: dict[str, dict], payload: dict) -> None:
    for change in payload.get("changes") or []:
        odd = change.get("odd") or {}
        row_id = str(odd.get("id") or "")
        if not row_id:
            continue
        if change.get("op") in {"remove", "delete"}:
            rows.pop(row_id, None)
        elif change.get("op") == "upsert":
            # Keep is_available=false rows so the product can show suspensions.
            rows[row_id] = odd


async def follow_event(client: httpx.AsyncClient, event_id: str) -> None:
    resume = ""
    rows: dict[str, dict] = {}
    needs_snapshot = True
    retry_seconds = 1.0

    while True:
        try:
            if needs_snapshot:
                snapshot, rows = await complete_snapshot(client, event_id)
                resume = str(snapshot.get("resume") or "$")
                emit(
                    "odds_snapshot",
                    event_id=event_id,
                    as_of_ts_ms=snapshot.get("as_of_ts_ms"),
                    ttl_seconds=snapshot.get("ttl_seconds"),
                    resume=resume,
                    items=list(rows.values()),
                )
                needs_snapshot = False

            params = {"since": resume, "catchup": "true", "max_batch": 2000, **ODDS_SHAPE}
            async with client.stream(
                "GET", f"events/{event_id}/odds/stream", params=params,
                headers={"Accept": "text/event-stream"},
            ) as response:
                response.raise_for_status()
                retry_seconds = 1.0
                async for event, payload in sse_messages(response):
                    if event == "delta":
                        apply_delta(rows, payload)
                        resume = str(payload.get("resume") or resume)
                        emit("odds_delta", event_id=event_id, resume=resume, changes=payload.get("changes") or [])
                    elif event == "resync":
                        emit("odds_resync", event_id=event_id, reason=payload.get("reason"))
                        needs_snapshot = True
                        break
                    # A heartbeat contains no price change.

        except asyncio.CancelledError:
            raise
        except (httpx.HTTPError, ValueError, json.JSONDecodeError) as exc:
            emit("stream_error", event_id=event_id, error=str(exc))

        if needs_snapshot:
            continue
        await asyncio.sleep(retry_seconds + random.uniform(0, 0.5))
        retry_seconds = min(retry_seconds * 2, 30.0)


async def game_record(client: httpx.AsyncClient, event_id: str) -> None:
    try:
        detail, result = await asyncio.gather(
            get_json(client, f"events/{event_id}"),
            get_json(client, f"events/{event_id}/results"),
        )
        emit("event", event_id=event_id, data=detail)
        emit("result", event_id=event_id, data=result)
    except httpx.HTTPError as exc:
        emit("record_error", event_id=event_id, error=str(exc))


async def bounded_game_record(client: httpx.AsyncClient, semaphore: asyncio.Semaphore, event_id: str) -> None:
    async with semaphore:
        await game_record(client, event_id)


async def main() -> None:
    if not API_KEY:
        raise SystemExit("Set ODDS_API_KEY before running this example.")
    timeout = httpx.Timeout(connect=10.0, read=None, write=10.0, pool=10.0)
    tasks: dict[str, asyncio.Task] = {}
    record_limit = asyncio.Semaphore(6)
    async with httpx.AsyncClient(
        base_url=BASE_URL,
        headers={"X-API-Key": API_KEY, "Accept": "application/json"},
        timeout=timeout,
    ) as client:
        try:
            while True:
                try:
                    events = await nbl_events(client)
                    ids = {str(item["event_id"]) for item in events if item.get("event_id")}
                    emit("event_list", count=len(events), items=events)

                    for event_id in ids:
                        if event_id not in tasks or tasks[event_id].done():
                            tasks[event_id] = asyncio.create_task(follow_event(client, event_id))
                    for event_id in set(tasks) - ids:
                        tasks.pop(event_id).cancel()

                    await asyncio.gather(
                        *(bounded_game_record(client, record_limit, event_id) for event_id in ids)
                    )
                except httpx.HTTPError as exc:
                    emit("discovery_error", error=str(exc))
                await asyncio.sleep(DISCOVERY_SECONDS)
        finally:
            for task in tasks.values():
                task.cancel()
            await asyncio.gather(*tasks.values(), return_exceptions=True)


if __name__ == "__main__":
    try:
        asyncio.run(main())
    except KeyboardInterrupt:
        print("Stopped.", file=sys.stderr)

Reference

NBL endpoint parameters

The parameter lists come from the current public OpenAPI document. The full API reference contains response schemas and other sports routes.

For a narrower build, start with the NBL product overview or the player market key list.