| Parameter | Type | Required | Example | Notes |
|---|---|---|---|---|
api_key |
string | Only with query authentication | API_KEY |
Default authentication method in examples; omit it when using Bearer. |
lang |
string | No | en |
Localizes supported catalogue names. See Languages for available codes and scope. |
utc |
number | No | 2, 4.5, -3 |
UTC offset applied to supported date/time values; time.timezone reports it (UTC+4.5). Invalid values fall back to UTC. |
include |
string | No | events,stats |
Comma-separated datasets, with no spaces. Values and support depend on the operation. |
page |
integer | No | 1 |
Page number on paginated operations. Pages hold 100 items; the response reports meta.page, meta.pages, meta.count and meta.total. |
bookmaker_ids |
string | No | 9,2 |
Comma-separated bookmaker IDs, with no spaces. Filters include=odds_prematch and include=odds_inplay to these bookmakers and returns their odds in the requested order on supported livescores and fixture operations, including match detail (fixtures?t=info). A single ID such as 2 is also valid. |
Pagination
List operations return at most 100 items per page and cannot change the page
size: per_page and nopag are ignored. Read meta.pages and request the
following pages with page, starting at 1; a page beyond the last returns an
empty data array with the same meta.total. The paginated operations are the country, league,
team, player, coach, referee, venue and TV channel lists, every livescores feed,
fixtures?t=schedule and broadcast?t=schedule. Season fixtures, leaders,
match datasets and search results are returned in full; search reports
meta.count and meta.total as 0, so use the length of data.
Operation selector
t is required on every route. When it is omitted the route falls back to its
default list operation instead of returning an error, so always send it
explicitly and check the operations table of the route for the accepted values.
Dataset includes
The most common match datasets are:
| Include value | Returned property | Where | Plans |
|---|---|---|---|
events |
events |
Livescores and fixtures?t=schedule, season, round, info, sort. |
Standard, World Cup |
stats |
stats |
Livescores and fixtures?t=schedule, season, round, info, sort. |
Standard, World Cup |
odds_prematch |
odds_prematch |
Livescores and fixture operations where match coverage provides odds. | Standard, World Cup, Odds |
odds_inplay |
odds_inplay |
Livescores and fixtures?t=info for matches in play. |
Standard, World Cup, Odds |
broadcast |
broadcast |
fixtures?t=schedule, season, round, info and sort: TV channels showing the match. Not supported by livescores or last_next. |
Standard, World Cup, Broadcast |
tvs |
tvs |
broadcast?t=schedule: embeds the channel details in each match. |
Standard, World Cup, Broadcast |
Free plans carry the Standard datasets. An include outside the plan returns
403 with meta.msg = Include not available for your plan.; see
Plans and Data Access.
Use dataset names in include; do not use standalone operation values. For
example, include=events embeds the timeline, while t=match_events calls the
standalone timeline operation.
For included odds, bookmaker_ids=9,2 returns only bookmakers 9 and 2, in
that order. Use bookmaker_ids=9,3,1 for the order 9, 3, 1, or
bookmaker_ids=2 for one bookmaker. The filter applies to both odds datasets
when both are included. Match and bookmaker coverage still determine which
odds are available.
See Match Events and Dataset Includes for endpoint examples, event fields and live polling guidance.
odds_format is specific to /v2.2/fixtures/; see
Odds Formats for accepted values, aliases and examples.
Tip: Store times internally from the returned Unix
timestampwhere available. Useutconly when a projected local date/time string is useful for display or date grouping.