coverage

What we hold, per sport and league (the discovery catalogue)

The catalogue an agent reads to decide whether a dataset exists here, precomputed on a schedule and served from a snapshot. Every league we hold appears with its match counts, seasons, freshness and per-datatype coverage.

VOCABULARY. data_types is the stable default and does not change. ?v=2 adds data_types_v2 beside it, which answers questions about a GRAIN rather than a datatype: "do you have xG" is a v1 question, "do you have PER-PLAYER xG" is a v2 one. In v2 each measure carries its grains (subject x period, e.g. team.match or player.season), every grain declares the denominator its figures count, and not_applicable names measures that CANNOT apply to a league as distinct from ones we simply lack. data.vocabulary echoes which shape was served.

v2 is opt-in because the summary answers most questions and the nested shape is only needed for grain questions. An unrecognised ?v= serves v1 rather than failing: a catalogue call is discovery, and a query-string typo should not 400.

get/v1/coverage

Request

  • Base URL: https://api.bigballsdata.com
  • URL: https://api.bigballsdata.com/v1/coverage
  • Auth: one of:
    • API key in header x-api-key
    • HTTP bearer

Query parameters

sport'football' | 'basketball' | 'baseball' | 'ice_hockey' | 'cricket' | 'mma' | 'boxing' | 'formula1' | 'american_football'

Narrow to one sport or league; accepts any registry alias. Unknown values are a 400, never a silent empty.

v'2'

Set to 2 to include data_types_v2 (grains, denominators, not_applicable) alongside the unchanged data_types. Omit for the stable v1 shape.

Response

ok. { data, meta }. Declared no content until 2026-09-25, on the one endpoint whose entire job is discovery.

Example response

{
  "meta": {
    "date_window": {
      "timezone": "UTC",
      "start_utc": "2026-09-13T00:00:00.000Z",
      "end_utc": "2026-09-14T00:00:00.000Z"
    },
    "source": "official-league",
    "confidence": 0.95,
    "cache_age_ms": 4200,
    "request_id": "req_abc123",
    "note": "match_id is omitted on 380 of 380 rows in this response. The live feed behind them does not carry an id we can resolve to a stored match, so we return no id rather than one that will not work. For rows with ids you can call back into, use /v1/stored/matches with the same sport or league, for example /v1/stored/matches?league=epl."
  },
  "error": {
    "code": "NOT_FOUND"
  }
}

Changes

No recorded changes to this operation across all 2 revisions of this API.