API v2: broadcast markets and viewer timezones

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.

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.

Adopt v2 at your own pace

There is no required migration for an existing v1 integration. UK channels and London date/time fields keep their existing meaning. Adding UTC timestamps has not reinterpreted those fields.

Keep your working v1 calls and add v2 requests where you need the new schedule contract. Moving a request involves updating its parameters and response handling, as well as the endpoint prefix. V2 schedule responses use Cache-Control: no-store; v1 keeps its existing cache behaviour.