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

Bestseller API

The upstream service that returns, per Market, the option-level betting weights used to compute Betting Insights.

Betting Insights

Aggregated popularity data describing how bets are distributed across the Options of a Market. Sourced from the upstream Bestseller service and attached to a fixture's markets on request (see the isBettingInsightsEnabled parameter).

BuildBet (BetBuilder)

A combination bet where several selections (Legs) from the same Fixture are combined into a single bet. Also referred to as a Same Game Parlay (SGP).

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.

Leg (LegOption)

One selection inside a BuildBet. A BuildBet with three legs combines three selections from the same fixture. The totalLegs filter is applied against the number of legs available on a market.

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.

Percentage of bets

For a single Market, the share of bets placed on one Option relative to the total bets across all options of that market. Values are normalized to sum to 1 (100%) per market and rounded to two decimals. Exposed as percentageBets within Betting Insights.

Pre-Created BuildBet

A BuildBet that has been pre-assembled and published ahead of time, so clients can present ready-made multi-leg suggestions without the punter building the combination manually. Surfaced through the preCreatedBuildBets endpoint.

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.

isBettingInsightsEnabled

A filter for the fixtures endpoint. When true, eligible fixtures are enriched with a bettingInsights object describing how bets are distributed across market options. Optional. If not specified (false), no insights are added. Enrichment is subject to server-side eligibility (supported login domain, supported trading partition, supported sport/competition, pre-match only) and is computed for main markets only.

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.

marketsFilterCriteria

A filter for selecting which markets to include in the response. Optional.If not specified, the existing workflow None is used backward compatible.None Applies the existing behavior with no additional filtering.All Includes all markets, regardless of visibility.Visible Includes only markets where isDisplayed is (true)

totalLegs

A filter for the preCreatedBuildBets endpoint. Returns only BuildBet markets whose number of available legs is greater than or equal to the provided value. Optional. Default 0.

visibleOnBetBuilderTabEnabled

A filter for the preCreatedBuildBets endpoint. Filters the legs included in a fixture by their BuildBet-tab visibility. When true (default), only legs flagged as visible on the BuildBet tab are returned; when false, only legs not flagged visible are returned.

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.

Refer to the Swagger page to see the attributes in the structure as they appear in the response.

bettingInsights

The container for per-market betting distribution, attached to a fixture when requested via isBettingInsightsEnabled. Present only for eligible fixtures. Contains marketOptions.

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.

legOptions

The selectable legs (options) that make up a BuildBet, returned by the preCreatedBuildBets endpoint. Only legs matching the requested visibleOnBetBuilderTabEnabled state are included, and a market is returned only when its remaining leg count is at least totalLegs. Each leg carries visibleOnBetBuilderTabEnabled.

links

A list of "deep" links to the data objects in the response. Part of the response envelope.

mainFixtureId

The identifier of the fixture a BuildBet belongs to, in compound (full) format. Returned by the preCreatedBuildBets endpoint.

marketId

Within bettingInsights, the identifier of the market a distribution refers to.

marketOptions

The list within bettingInsights, with one entry per market that qualified for insights. Each entry carries a marketId and its per-option distribution in options.

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.

optionId

Within bettingInsights, the identifier of the option (selection) a percentageBets value refers to.

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. Within bettingInsights.marketOptions, options instead carries the per-option distribution (optionId and percentageBets).

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.

percentageBets

Within bettingInsights, the share of bets placed on an option relative to the market total, in the range 0–1, rounded to two decimals. Values across a market's options sum to 1.

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.