Glossary

Before working with our Sports API, we recommend that you familiarize yourself with the terminology used. This page gives an overview of general terminology, the meaning of the parameters that can be used for the API calls, and the attributes in the responses.

General terminology

Competition: A data object representing a group of related events, usually either a league (such as the UEFA Champions League) or a tournament (such as the ATP Masters 1000 in Rome).
Fixture: A data object representing a real-world event, for instance a football match or a Formula 1 race. Contains Markets to bet on with their Options and Prices.
Market: One kind of bet offered for a Fixture, for instance »Who will win?« or »Who will score the first goal?«.
Main Markets are markets flagged as important in the system (for instance »Who will win?«).
The Balanced Line Market is the market with 2 Options, where the odds for the options are most equal (closest together).
Option: One of the potential outcomes of a Market. Typical options for the market »Who will win?« in pair games would be: »Player A« and »Player B« (and in three-way bets also »Draw«).
Participant: A data object representing a person or a team participating in a real-world event.
Price: The odds for an Option. Available as Decimal Odds (»European Odds«), Fractional Odds (»British Odds«, only for football), and Moneyline Odds (»American Odds«).
Region: A geographical region (or sometimes a category such as »Internationals« or »Specials«) in which a Competition takes place. This can be a country or an even bigger area such as a continent or the whole world.
Scoreboard: The in-play information of a Fixture. Consists of the publication status of the fixture, the period the real-world event is currently in (for events with defined periods such as football or tennis matches), the elapsed time in minutes and seconds, the current score (for events with scores), and more details.

Parameters

competitionIDs: A list of unique IDs of competitions. Optional. Use it for limiting the response to certain competitions of which you know the ID.; If you use the competitionIDs filter together with the fixtureIds, the filters are combined with a logical AND. If none of the requested fixtures belongs to one of the requested competitions, no result is returned.
country: The country's Alpha-2 code, as defined in ISO 3166. Mandatory for retrieving all data except language codes. You can only retrieve data from one country at a time.
See the List of ISO 3166 country codes on Wikipedia for reference.
fixtureIds: A list of unique IDs of fixtures. Available for the endpoints fixture, fixtureIndex, and scoreboards. Optional. Use it for limiting the response to certain fixtures of which you know the ID.; If you use the competitionIDs filter together with the fixtureIds, the filters are combined with a logical AND. If none of the requested fixtures belongs to one of the requested competitions, no result is returned.
isInPlay: A filter for including only fixtures in pre-match (false) or in-play (true) state. Optional. If not specified, both are included.
language: The language code, taken from the list of supported language codes. Optional. If not specified, "en" is assumed. Use it to retrieve the data translated into the defined language.
participants: A filter for including the list of participants (teams/players) in a competition (true) or not (false). Optional. If not specified, the list is not included.
onlyMainMarkets: A filter for including only main markets and balanced line markets for a fixture (true). Optional. If not specified, only main markets are returned.
since: A timestamp in UTC time in the format yyyyMMddHHmmss. Optional for the first use of an endpoint; mandatory from the second use on. Only data with timestamps newer than the since date/time is returned. If undefined, all matching data is returned.
sportId: The unique ID of a sport. Mandatory. You can only retrieve data for one sport at a time.

Attributes

The Sports API is backwards-compatible and can retrieve both data from the current (V2) and the previous (V1) version. If an attribute affects only one of the versions, this is explained in the description.

competition: The wrapper for the id and the name of a competition. The type of the competition is either prematch (before the scheduled start) or inplay (after the scheduled start).
competitionGroupId: The ID under which in V1 a pre-match and the corresponding in-play competition are grouped.
count: The total number of data objects returned in the response. Part of the response envelope.
cutoffDateUTC: The timestamp in UTC time until when bets can be placed on the markets of a fixture.
denominator: The second number in fractional (British) odds. Indicates the stake part of the potential payout.
entityId: The numeric ID of a fixture. The numeric ID is only unique within the data version, therefore V2 fixtures also get a full ID with a version prefix.
fixtureGroupId: The ID under which in V1 a pre-match and the corresponding in-play fixture are grouped.
fraction: The wrapper for the price of an option in fractional (British) odds. Contains the attributes numerator and denominator.
full: The full ID of a V2 fixture, consisting of the entityId and a prefix V2:. Example: :V2:12340. For V1 fixtures, the attribute is undefined.
happening: The trigger for a market. Examples: goal, penalty, yellow/red card, touchdown, or rebound.
id: The unique ID of a data object (Competition, Fixture, Market, Option, Participant, Region, Sport). For fixtures, the ID is a compound identifier, consisting of an entityID and a full ID, including a version prefix, for V2 IDs. For scoreboards, the ID of the fixture the scoreboard is for is needed.
isBalancedLine: The indicator whether a market is the balanced line market (true) or not (false).
isDisplayed: The indicator whether a fixture, market, or option is displayed on the Web front ends (true) or not (false).
isInPlay: The indicator whether a fixture has not started and is in pre-match state (false) or has started and is in in-play state (true).
isOpenForBetting: The indicator whether an option or market of a fixture accepts bets (true) or not (false).
isPlannedInPlay: The indicator whether a fixture in pre-match state will later also allow live betting (true) or not (false).
isRunning: The indicator whether the time in the Scoreboard timer is currently running (true) or stopped (false).
items: The wrapper for the data objects returned in the response. Part of the response envelope.
links: A list of "deep" links to the data objects in the response. Part of the response envelope.
markets: The wrapper for the list of markets within a fixture. For each market in the list, the available attributes are id, name, marketType, marketTemplateId, happening, period, subPeriod, value, isDisplayed, isOpenForBetting, isBalancedLine, and the list of options.
marketTemplateId: The unique ID of the market template from which the market was created as an instance. Only applicable for V1 markets.
marketType: The kind of market offered. Examples: 3-way, total over/under, number of medals, or nominated finalists.
minutes: The minutes value in the time info received from the Scoreboard timer.
name: The wrapper for the full name (text) and the short name (shortText) of a data object.
next: A predefined request syntax, included as node at the end of the response body. It contains the full settings for the follow-up call, including all parameters from the request and the correct since parameter.
numerator: The first number in fractional (British) odds. Indicates the winnings part of the potential payout.
odds: The price of an option in decimal (European) odds.
options: The wrapper for the list of options within a market. For each option in the list, the available attributes are id, name, price, isDisplayed, and isOpenForBetting.
participants: The wrapper for the list of participants. For each participant in the list, the available attributes are id, name, and participantTag.
participantTag: The attribute for special remarks on a participant. Example: Home team in football.
participantType: The type of participant. Examples: Team, Player, or Horse.
period: The period of an event, also defined in the fixture. Most events are officially divided into periods. Examples: halves in football, sets in tennis. Some markets are only available for certain periods.
price: The wrapper for the price of an option. Prices are available as odds (decimal or European odds) or fraction (fractional or British odds).
region: The wrapper for the id and the name of a region.
score: The score in the event, in the format home:away. Available for pairgame fixtures in sports where a score in this format is available.
seconds: The seconds value in the time info received from the Scoreboard timer.
shortText: The short name of a data object in the requested language.
state: The current state of the fixture, matching the state of the real-world event: not started, started, finished, suspended, resulted (all markets of this fixture have their results), or settled (all markets of this fixture have been settled and paid out).
startDateUTC: The timestamp in UTC time when an event is scheduled to start.
subPeriod: A part of a period. Example: »First 15 minutes«. Some markets are only for certain sub-periods.
text: The full name of a data object in the requested language.
time: The wrapper for the minutes, seconds, and isRunning time information from the Scoreboard.
type: The type of the response (full or delta), included as node at the end of the response body. A full response is a full snapshot of the betting offer matching the given parameters. A delta response is an update that only contains matching new and changed items. If an item within the response scope has been removed from the betting offer, the response is always full.; Do not mix with the type of a competition (prematch or inplay) or of a fixture (pairgame or tournament).
value: The boundary value of a market for over/under markets. Example: For the market over/under 1 goal, the boundary value is 1.
version: The version of the id of the data object. Possible values: V1, V2.