All updates
API v2By World Sports API

API v2: broadcast markets and viewer timezones

Build sports schedules around your viewer. V2 separates where a fixture is broadcast from the timezone used to display its start, while keeping one canonical fixture ID.

Update, 14 October 2026. API v1 has been retired, so v2 is now the only API version. This note is kept as published on 5 October. Read the 14 October release note and the migration guide. Your existing API key works with v2.
V2 was live at launch with the United Kingdom (GB) as the first supported broadcast market.

Broadcast markets and viewer timezones are independent

A broadcast market tells you which country’s listings to request. A viewer timezone tells you how to display the fixture’s start. Choosing market=GB and timezone=America/New_York returns UK listings with New York display times. It does not imply that those channels are available in the United States.

Fixture IDs stay the same across markets and timezones. Sporting geography, such as a team’s country or a competition’s location, is separate from broadcast availability. Check /api/v2/markets for supported markets as coverage grows.

UK listings on a New York calendar date
curl --get 'https://worldsportsapi.com/api/v2/matches' \
  -H "x-api-key: $SPORT_API_KEY" \
  --data-urlencode 'market=GB' \
  --data-urlencode 'timezone=America/New_York' \
  --data-urlencode 'start_date=2026-10-06' \
  --data-urlencode 'end_date=2026-10-06'

Example date: 6 October 2026. Replace it with the day you want to query. Keep your API key on your server.

A UTC instant, with honest time precision

V2 adds starts_at for a known UTC start instant and a display object containing the viewer’s local date, time and UTC offset. For example, 2026-10-06T19:00:00Z displays as 20:00 in London and 15:00 in New York on that date.

Use time_precision, schedule_status and the schedule object to handle incomplete times. Date-only or unresolved starts do not acquire an invented midnight kickoff. An ambiguous daylight-saving time is left unresolved until there is enough evidence to choose the correct instant; its existing v1 UK representation is preserved.

Date queries and pagination with explicit context

  • Local calendar dates. Supply start_date, end_date and an IANA timezone. The end date is inclusive.
  • Exact intervals. Alternatively, supply offset-bearing from and to timestamps. The upper bound is excluded. Do not mix the two query styles.
  • Broadcast filters. Use broadcasts_only=true with a market for fixtures with known listings. Without a market, responses omit broadcast listings.
  • Cursor pagination. Read fixtures from items and pass next_cursor back as cursor with the same query. Start a new query when changing filters, market, timezone or page size.
  • Date-only candidates. Opt into include_date_only=true for a separate date_only_items collection. These are source-calendar candidates, not confirmed kickoff times or viewer-local dates.

The /api/v2/coverage endpoint describes the known coverage window for a market. An empty broadcast list means no listing is known; it is not proof that a fixture is unavailable everywhere.

Moving to v2

At launch, v1 stayed available alongside v2 and no migration was required; that period ended when v1 was retired on 14 October 2026. v1’s UK channels and London date/time fields had their own meaning, and adding UTC timestamps did not reinterpret them. v2 uses the UTC and viewer-timezone fields described here.

What changes when you opt into v2
Your integrationV1 (retired)V2
Endpoint prefix/api/v1/api/v2
Broadcast listingsExisting UK channelsExplicit market; GB at launch
Fixture timeLondon date and timeUTC start and viewer-local display
Match listExisting v1 responseContext, items and pagination cursors
AuthenticationThe same API key, origin restrictions and shared account quotas

Moving a request involves updating its parameters and response handling, as well as the endpoint prefix. V2 schedule responses use Cache-Control: no-store.