One fixture. Independent viewing context.
Choose a broadcast market separately from the timezone used to display a fixture. V2 is the only API version; the v1 read endpoints were retired on 14 October 2026.
Markets and timezones
Ask /api/v2/markets which markets are publicly supported. On 14 October 2026 it lists GB and IE, both marked supported. A country in the sporting catalogue does not establish broadcast coverage there. No additional country is promised by this contract. A market code is two capital letters, optionally followed by a hyphen and up to three capital letters or digits. A market that is not publicly supported answers 404.
timezone is an IANA name such as Europe/London; an unknown name is rejected. The market decides which listings you receive; the timezone only decides how times are displayed. Choosing market=GB with timezone=America/New_York returns GB listings with New York display times.
GET /api/v2/matches?start_date=2026-10-05&end_date=2026-10-05&market=GB&timezone=America%2FNew_York
x-api-key: YOUR_API_KEYCivil-date queries require a timezone, with an inclusive end date and a maximum of 31 calendar days. Alternatively supply offset-bearing from and to instants, at most 32 days apart; the upper bound is excluded. Do not combine the two forms. Display timezone defaults to UTC only for instant queries. Fixture detail (/matches/{id}) requires timezone.
GET /api/v2/matches?from=2026-10-05T00%3A00%3A00Z&to=2026-10-06T00%3A00%3A00Z&market=IE&broadcasts_only=true
x-api-key: YOUR_API_KEYResponse and pagination
{
"context": {
"market": "GB",
"timezone": "America/New_York",
"start_date": "2026-10-05",
"end_date": "2026-10-05",
"from": null,
"to": null,
"tzdata_version": "2026a"
},
"items": [
{
"id": 123,
"sport_id": 1,
"tags": [],
"competition": {
"id": 18,
"name": "Premier League"
},
"stage": null,
"home_team": {
"id": 1001,
"name": "Home Team"
},
"away_team": {
"id": 1002,
"name": "Away Team"
},
"venue": null,
"starts_at": "2026-10-05T23:30:00Z",
"time_precision": "exact",
"schedule_status": "scheduled",
"schedule_under_review": false,
"event_timezone": null,
"display": {
"date": "2026-10-05",
"time": "19:30:00",
"utc_offset": "-04:00"
},
"schedule": {
"basis": "instant",
"local_date": null,
"local_time": null,
"timezone": null
},
"broadcasts": [],
"availability_states": []
}
],
"date_only_items": [],
"next_cursor": null,
"next_date_only_cursor": null
}Use limit (1–200, default 100) and return next_cursor as cursor with the same query. Cursors are bound to the filters, market, timezone and page size. Live reschedules can move an item between pages; deduplicate by fixture ID and restart the query when refreshing.
Unknown starts never become midnight. Opt into include_date_only=true to receive separately labelled source-calendar candidates whose possible day overlaps your interval. Page those with date_only_cursor. Their appearance does not establish a kickoff or a particular viewer-local date.
Availability and filters
Omit market for fixture-only queries; those responses omit broadcasts. Empty broadcast arrays mean no listing known. broadcasts_only=true requires market and limits results to known eligible listings. Channel, broadcaster and airing-kind filters apply to the same listing. Regional restrictions take precedence, and qualified national listings are labelled as varying by region.
Filters are sport_ids, competition_ids, team_country_ids, venue_country_ids, competition_country_ids, channel_id, broadcaster_ids and broadcast_kind (live, delayed, replay or highlights). Repeat list parameters, up to 100 IDs each. Market is independent of all sporting geography filters.
Related GET endpoints: /matches/next (starting date and timezone), /matches/:id (timezone and optional market), /channels, /broadcasters, /coverage and /matches/source-status (market required; the two coverage paths are aliases). Coverage reports its declared calendar window and capture time; a successful fetch does not imply complete coverage outside that window. Import health is a separate endpoint, /source-health.
Programme listings, availability and schedule evidence
/broadcasts lists airings by programme start rather than by fixture. It requires market and offset-bearing from and to (at most 32 elapsed days). It also takes channel_id, broadcaster_ids, competition_ids, sport_ids, broadcast_kind, limit (1–200) and cursor. Civil dates, timezone and broadcasts_only answer 422. Each item carries programme_starts_at and the fixture it belongs to.
GET /api/v2/broadcasts?market=GB&from=2026-10-20T00%3A00%3A00Z&to=2026-10-22T00%3A00%3A00Z&limit=50
x-api-key: YOUR_API_KEY{
"items": [
{
"id": 14,
"fixture_id": 101,
"market": "GB",
"broadcast_kind": "live",
"programme_starts_at": "2026-10-20T18:45:00Z",
"programme_ends_at": null,
"fixture_starts_at": "2026-10-20T18:45:00Z",
"fixture_date": "2026-10-20",
"fixture_time_precision": "exact",
"fixture_schedule_status": "scheduled",
"fixture_schedule_under_review": false,
"channel": {
"id": 7012,
"name": "Sky Sports Main Event"
},
"broadcaster": {
"id": 40,
"name": "Sky"
},
"evidence_level": "observed"
}
],
"next_cursor": null,
"time_basis": "programme_start"
}/matches/{id}/availability requires market and reports what is known about where the fixture can be watched: state and any assertions (statements with a window and a reason). /matches/{id}/schedule-evidence takes no market and reports how certain the schedule is: certainty, any published date window, season, round and leg. Neither takes timezone. A merged ID answers 410, as above.
GET /api/v2/matches/101/availability?market=GB
x-api-key: YOUR_API_KEY{
"fixture_id": 101,
"market": "GB",
"state": "unknown",
"assertions": [],
"schedule_status": "scheduled",
"schedule_under_review": false
}GET /api/v2/matches/101/schedule-evidence
x-api-key: YOUR_API_KEY{
"certainty": "unknown",
"published_date_window": null,
"season": null,
"round": null,
"leg": null,
"time_precision": "exact",
"starts_at": "2026-10-20T18:45:00Z",
"scheduled_local_date": "2026-10-20",
"schedule_status": "scheduled",
"schedule_under_review": false
}Three parameters are opt-in, each exactly true or false. include_unscheduled adds postponed and cancelled fixtures; it works on /matches, /matches/{id}, /broadcasts, /availability and /schedule-evidence. include_unknown_time adds, to /matches, an unknown_time_items list of fixtures with no known kickoff time, listed by their source calendar date; page it with next_unknown_time_cursor, passed back as unknown_time_cursor, which requires it. Without these options the fixtures are not returned.
GET /api/v2/matches?start_date=2026-10-20&end_date=2026-10-31&timezone=Europe%2FLondon&include_unscheduled=true&include_unknown_time=true
x-api-key: YOUR_API_KEYschedule_under_review is true while a reported change to a fixture's kick-off is being checked, and false otherwise. starts_at stays the last confirmed kick-off until the change is accepted, so show it with a note rather than hiding the fixture. It does not replace schedule_status: a postponed or cancelled fixture keeps its status. Airings carry the same flag as fixture_schedule_under_review.
All of these are live. watch_options on fixtures stays gated by a feature switch, as described under watch facts.
Reference catalogues
/sports, /countries and /competitions need no market. Each returns a plain list ordered by name, then id, with no paging. Only /competitions takes filters: sport_ids and country_ids, up to 100 positive IDs each. IDs within one filter combine with OR, the two filters with AND. Any other parameter answers 422. Store IDs, not names or slugs.
| Endpoint | Fields |
|---|---|
| /sports | id, name, slug (lower-case, hyphenated; follows a rename) |
| /countries | id, name (countries, home nations and regions such as Europe or World), iso_code (ISO 3166-1 alpha-2 or null; not unique), fifa_code (unique, or null) |
| /competitions | id, name, slug (set at creation; kept on rename), sport_id, country_id, gender (men, women, mixed or unknown) |
[
{
"id": 18,
"name": "Premier League",
"slug": "football-england-premier-league",
"sport_id": 1,
"country_id": 2,
"gender": "men"
}
]An ID that disappears from a catalogue simply stops being listed; only fixtures have a redirect (below).
Placeholders in the channel and broadcaster catalogues
/channels and /broadcasters need market and hide placeholder rows (is_placeholder is true, for example TBC) unless you add include_placeholders=true. The value must be exactly true or false; anything else answers 422. Only these two catalogues change. Listings in /matches keep their broadcasts on placeholder channels, and a placeholder ID remains a valid channel_id filter.
GET /api/v2/channels?market=GB&include_placeholders=true
x-api-key: YOUR_API_KEYWatch facts
When watch facts are enabled and you pass market, fixture lists, next fixtures and fixture details include watch_options. Each option carriesprovider and optional channel (catalogue IDs and names),offer, access, optional available_from andavailable_until instants, and an optional requires plan or device condition. Options contain no URLs. Keep your own service links keyed by market and catalogue ID.
An empty array means no watch fact is known. Access can be inferred from reviewed rights rules; it is not a new verification by the broadcaster. Current facts cover Irish Formula 1 listings on Sky and NOW; NOW is a channel under provider Sky. The UHD option records the Sky Sports UHD pack and compatible-equipment requirement.
On fixture lists and next-fixture reads, watch_access filters tofree, free_with_account, subscription,pay_per_view or unknown; it requires market. While the feature is off, watch_options is absent and this filter is rejected. Consumers must tolerate additional optional fields.
Removed: watch_url and access_label
watch_url and access_label are removed from public fixture listings and OpenAPI. Read neutral watch_options (above) and keep your own service links keyed by viewing market and provider/channel catalogue ID. Preserve access and plan/device requirements, including UHD conditions.
Merged fixtures and change feeds
A fixture ID is stable until the fixture is merged into another. A merged ID answers 410 Gone instead of 404, on /matches/{id} and its /availability and /schedule-evidence reads. Request the fixture named in superseded_by instead. A Link header with rel="successor-version" names it too. superseded_by is always the current survivor: if that fixture is merged later, the answer follows. Hidden and unknown IDs still answer 404, and a merged fixture never appears in list results.
{
"error": "fixture_merged",
"detail": "Fixture 45 was merged into fixture 123",
"superseded_by": 123,
"merged_at": "2026-10-07T21:27:03.066505+00:00"
}/fixtures/merges lists merges oldest first so you can update stored IDs. since is required: it is a feed position, not a time. Start with since=0 and pass next_since back until it is null; poll later with the last id you saw. limit is 1–1000 (default 500). Positions follow commit order, so a merge is never skipped. Any other parameter answers 422.
GET /api/v2/fixtures/merges?since=0&limit=500
x-api-key: YOUR_API_KEY{
"since": 0,
"merges": [
{
"id": 1,
"old_id": 45,
"superseded_by": 123,
"merged_at": "2026-10-07T21:27:03.066505Z"
},
{
"id": 2,
"old_id": 67,
"superseded_by": 123,
"merged_at": "2026-10-08T08:02:11.502318Z"
}
],
"next_since": null
}/channels/changes lists changes to the channel catalogue, oldest first: split (a regional twin was created for a market), merged, renamed, market_moved, market_retired and scope_changed (the service became shared across its markets). since is required, an ISO 8601 instant with an explicit offset; changes strictly after it are returned. Re-key anything you stored by channel ID for the change’s market. limit is 1–1000 (default 500), and next_since is the last changed_at when more changes remain, else null.
Because since is a time, changes made at the same instant can straddle a page boundary. When you page, step since back by one second and deduplicate by id.
GET /api/v2/channels/changes?since=2026-10-01T00%3A00%3A00Z&limit=500
x-api-key: YOUR_API_KEY{
"since": "2026-10-01T00:00:00Z",
"changes": [
{
"id": 7,
"changed_at": "2026-10-20T09:00:00Z",
"kind": "split",
"channel_id": 2301,
"market": "IE",
"split_from": 301,
"merged_into": null,
"name": "Example Sports 1",
"stable_key": null,
"brand_key": "example-sports-1",
"details": {}
}
],
"next_since": null
}Keys, allowances and errors
Your customer key, allowed origins and quotas apply unchanged. Viewing timezone does not change your UTC billing month. Unsupported markets and unknown or hidden fixtures return 404; merged fixtures return 410; invalid or contradictory queries return 400 or 422. See limits and errors.
Explore the endpoints