|Table of Content Zone
Understanding Market Navigation
Using the set of navigation operations, you can easily create a menu tree of markets in whatever hierarchy you want. You can listEventTypes to get the Sports as the top of your menu. Or, you could call "listCountries" and use markets in a country as the root of the tree.
Betfair Price Increments
Below is a list of price increments per price 'group'. Placing a bet outside of these increments will result in an INVALID_ODDS error.
Common Error Codes
Guide to available currencies and minimum bet sizes.
The locale specification determines the language returned for names of sports and markets. It is an optional parameter you can specify when you want to retrieve names in a language that differs from the language specified for the account. For example, if the account language is specified as English, you can use the locale parameter to retrieve non-English sports or market names.
The following languages are available, but please be aware not all markets in all languages are fully translated:
CompetitionId & Event Mapping Data
A collection of files showing the mapping relationship between an EventId and its Competition.
These files are available from 2018-2022 only for Soccer, Tennis, Cricket, Golf, and Other Sports.
CompetitionIds - Soccer Markets
The below spreadsheet contains a list of competitionId's for Soccer markets.
SelectionId's - Soccer Markets
The below spreadsheet includes all selection names and their selectionId's used on the Betfair Exchange since 2019.
MarketType & Market Name Mappings
The below spreadsheet shows the possible mapping relationship between market name and marketType across all sports.
Racecourse abbreviations lists for Horse Racing and Greyhounds are available via the spreadsheet below:
Runner Metadata Description
The RUNNER_METADATA returned by listMarketCatalogue for Horse Racing (when available) is described in the table below.
Time Zones & Time Format
All times are returned in GMT and are in ISO 8601 (http://en.wikipedia.org/wiki/ISO_8601) format. They can be converted to your local timezone using the timezone field returned by the getAccountDetails operation or into the local market timezone using the timezone returned for the event by listMarketCatalogue
To synchronize with the Betfair server time we recommend that you use the pool of NTP servers listed via http://www.pool.ntp.org/zone/europe
The following table lists the time zones returned by the API along with their meaning.
The Betfair Exchange tries to match bets against the bets placed by other users as well as equivalent bets where possible.
For example, if a customer backs Player A in a tennis match at odds of 2.0, the exchange matches any lay bet at odds of 2.0 or better on Player A. In addition, the Exchange also calculates all possible matches that are equivalent to a lay bet on Player A. So, if a customer backs Player B at odds of 2.0 or better, the Exchange matches it with the back bet on Player A. The Betfair Exchange uses a 'cross matching' algorithm to display the best possible prices (bets) available by taking into account the back and lay offers (unmatched bets) across all selections.
One of the easiest ways to understand how we generate virtual bets for cross-matching is to work through a couple of examples.
Consider the following market and what would happen if we placed a very large back bet at 1.01 on The Draw:
Without cross matching, this bet would be matched in three portions;
1) £150 at 5.0,
With cross matching we can do better.
We have a back bet on Newcastle for £120 at 2.0 and a back bet on Chelsea for £150 at 3.0 (shown in pink on the available to lay side of the market).
These two bets can be matched against a back bet on The Draw at a price of 6.0, since 2.0, 3.0, and 6.0 form a 100% book. To ensure that the book is balanced, we choose the stakes to be inversely proportional to the prices.
This means that we take the full £120 at 2.0 on Newcastle, only £80 at 3.0 on Chelsea, and £40 at 6.0 on The Draw, which is the first virtual bet
We now have a back bet on Newcastle for £75 at 2.5 and a back bet on Chelsea for £70 at 3.0 (again shown in pink on the available to lay side of the market).
These two bets can be matched against a back bet on The Draw at a price of 3.75, since 2.5, 3.0, and 3.75 also form a 100% book.
Balancing the stakes means that we need to take the full £75 at 2.5 on Newcastle, only £62.50 at 3.0 on Chelsea, and £50 at 3.75 on The Draw, which is the second virtual bet. Since 3.75 is less than 5.0, the £150 at 5.0 would be matched first followed by £50 at 3.75. If we continued this process we would get further matching at 1.50 and 1.05, but for the purposes of displaying the market view we have the best 3 prices for the available to back bets on The Draw, and so we can stop calculating the virtual bets. The virtual bets are just the bets that would have been matched had we received a sufficiently large back bet at 1.01; in this example, £40 at 6.0 and £50 at 3.75. We take these virtual bets and merge them with the existing bets on the market to generate the following market view (with the virtual bets shown in green)
The process is repeated to obtain the virtual lay bets (available to back bets) for Newcastle and Chelsea.
Here we have a slightly different market (as before, chosen to make the numbers nice) and consider what would happen if we placed a very large lay bet at 1000 on The Draw.
Without cross-matching, this bet would be matched in three portions; 1) £100 at 10.0, 2) £50 at 50.0, and £2 at 1000 with anything remaining being left unmatched. With cross-matching we can do better. We have a lay bet on Newcastle for £300 at 2.0 and a lay bet on Chelsea for £150 at 3.0 (shown in blue on the available to back side of the market). These two bets can be matched against a lay bet on The Draw at a price of 6.0, since 2.0, 3.0, and 6.0 form a 100% book. To ensure that the book is balanced, we choose the stakes to be inversely proportional to the prices. This means that we take only £225 at 2.0 on Newcastle, the full £150 at 3.0 on Chelsea, and £75 at 6.0 on The Draw, which is the first virtual bet.
Assuming these bets got matched, the market would look like this:
We now have a lay bet on Newcastle for £75 at 2.0 and a lay bet on Chelsea for £250 at 2.4 (again shown in blue on the available to back side of the market). These two bets can be matched against a lay bet on The Draw at a price of 12.0, since 2.0, 2.4, and 12.0 also form a 100% book. Balancing the stakes means that we need to take the full £75 at 2.0 on Newcastle, only £62.50 at 2.4 on Chelsea, and £12.50 at 12.0 on The Draw, which is the second virtual bet.
This leaves the following market:
This time we can't continue the process since there is no valid price for a virtual bet on The Draw that would result in a 100% book, so we can stop calculating the virtual bets. Again, the virtual bets are just the bets that would have been matched had we received a sufficiently large lay bet at 1000; in this example, £75 at 6.0 and £12.50 at 12.0. We take these virtual bets and merge them with the existing bets on the market to generate the following market view (with the virtual bets shown in orange):
Account Statement - Resettlement Lifecycle
The below demonstrates the resettlement lifecycle and how this is represented via the getAccountStatement output.
In the first file, the back bet on Landskrona was settled as winner, and so we see two entries for that bet:
- The initial debit (RESULT_NOT_APPLICABLE)
- The profit from winning the bet (RESULT)
In the second example, the market was unsettled, and we see four entries:
- The two entries described above are still present but tagged with RESULT_ERR
- An entry to revert the commission payed (tagged with COMMISSION_REVERSAL and RESULT_FIX)
- An entry to undo the payout from the winning bet (tagged with RESULT_FIX)
In the third example, we resettle the market with the back bet on Landskrona as a loser, and we see 5 entries:
- The four entries described above
- An entry describing the losing bet (RESULT_LOST)
The below regulator codes are used in the reglulators field provided in the listMarketCatalogue Market Description and the Exchange Stream API marketDefinition.
The below file contains a complete list of EventTypeIds