Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

...

Panel
bgColor#FFFFFF
titleBGColor#C8D0E4
titlelistMarketBook
List< MarketBook > listMarketBook ( List<String>marketIds , PriceProjection priceProjection, OrderProjection orderProjection, MatchProjection matchProjection, boolean includeOverallPosition, boolean partitionMatchedByStrategyRef, Set<String> customerStrategyRefs, StringcurrencyCode,Stringlocale, Date matchedSince, Set<BetId> betIds) throws APINGException

Returns a list of dynamic data about markets. Dynamic data includes prices, the status of the market, the status of selections, the traded volume, and the status of any orders you have placed in the market.

Please note: Separate requests should be made for OPEN & CLOSED markets. Request that include both OPEN & CLOSED markets will only return those markets that are OPEN.

Info

Market Data Request Limits apply to requests made to listMarketBook that include price or order projections.

Calls to listMarketBook should be made up to a maximum of 5 times per second to a single marketId.

Info
titleBest Practice

Customers seeking to use listMarketBook to obtain price, volume, unmatched (EXECUTABLE) orders and matched position in a single operation should provide an OrderProjectionof “EXECUTABLE” in their listMarketBook request and receive all unmatched (EXECUTABLE) orders and the aggregated matched volume from all orders irrespective of whether they are partially or fully matched. The level of matched volume aggregation (MatchProjection) requested should be ROLLED_UP_BY_AVG_PRICE or ROLLED_UP_BY_PRICE, the former being preferred. This provides a single call in which you can track prices, traded volume, unmatched orders and your evolving matched position with a reasonably fixed, minimally sized response.

Parameter name

Type

Required

Description

marketIds

List<String>

(tick)

One or more market ids. The number of markets returned depends on the amount of data you request via the price projection.

priceProjection

PriceProjection

 

The projection of price data you want to receive in the response.

orderProjection

OrderProjection

 

The orders you want to receive in the response.

matchProjection

MatchProjection

 

If you ask for orders, specifies the representation of matches.

includeOverallPosition

boolean

 

If you ask for orders, returns matches for each selection. Defaults to true if unspecified.

partitionMatchedByStrategyRef

boolean

 

If you ask for orders, returns the breakdown of matches by strategy for each selection. Defaults to false if unspecified.

customerStrategyRefs

Set<String>

 

If you ask for orders, restricts the results to orders matching any of the specified set of customer defined strategies. 
Also filters which matches by strategy for selections are returned, if partitionMatchedByStrategyRef is true. 
An empty set will be treated as if the parameter has been omitted (or null passed).

currencyCode

String

 

A Betfair standard currency code. If not specified, the default currency code is used.

locale

String

 

The language used for the response. If not specified, the default is returned.

matchedSince

Date

 

If you ask for orders, restricts the results to orders that have at least one fragment matched since 
the specified date (all matched fragments of such an order will be returned even if some were matched before the specified date). 
All EXECUTABLE orders will be returned regardless of matched date.

betIds

Set<BetId>

 

If you ask for orders, restricts the results to orders with the specified bet IDs.

Return type

Description

List< MarketBook >

output data

Throws

Description

APINGException

Generic exception that is thrown if this operation fails for any reason.

Since 1.0.0

Virtual Bets

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.

Info

You can return virtual bets in the response when using API-NG by including the virtualise":"true" in the listMarketBook request e.g. [{"jsonrpc": "2.0", "method": "SportsAPING/v1.0/listMarketBook", "params": {"marketIds":["1.114101556"],"priceProjection":{"priceData":["EX_BEST_OFFERS"],"virtualise":"true"}}, "id": 1}] 

 

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:

Image Removed

Without cross matching, this bet would be matched in three portions;

1) £150 at 5.0,
2) £250 at 3.0, 
and £999 at 1.01 with anything remaining being left unmatched.

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).

Image Removed

 

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)

Image Removed

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.

Image Removed

 

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:

Image Removed

 

 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:

Image Removed

 

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, and 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):

Image Removed