Filtering matched odds

The endpoint

GET /v2/odds/{type} serves standard, 2up, dutching, each-way, extra-place and bog. There is no event filter; for one event use GET /v2/odds/event/{id}.

The filters and their caps

Values are comma-separated and lowercased. /v2/sports and /v2/bookmakers list the values.

• sports, at most 20: a sport key or a prefix of one (horse_racing, soccer), or a competition key. An event's competition_key, also listed on /v2/sports, returns every event of that competition, whatever its bookmakers call it. Any other key also returns the events a bookmaker files under a key starting with it, and, when all of that key's events belong to one competition, the rest of that competition.
• bookmakers, at most 40: keeps back offers from those bookmakers.
• exchanges, at most 4: keeps lay offers from those exchanges, each-way win and place included.
• markets, at most 20: keeps those markets.
• commenceTimeFrom and commenceTimeTo: the kick-off window, ISO-8601 UTC. The window is never priced.
• inPlay, on standard and dutching only: exclude, the default, leaves the events in play out, and only keeps them alone, each with in_play: true. It is never priced. In-play prices covers it.

The trimming rule

Filtering never changes a price: you get the full product with the rest removed. Events are cut by sport and kick-off, then markets, then back offers by bookmaker and lay offers by exchange. An outcome left without a back offer, or without a lay offer, goes; then empty markets, then empty events. Event order stays kick-off, then id.

On dutching a dutch is kept only when every one of its legs is at a bookmaker you named. A call that leaves nothing is an empty reply, and free.

Unknown and absent values

A value the catalogue doesn't know is a 400 (unknown_sport, unknown_market, unknown_bookmaker, unknown_exchange) listing the valid ones in valid. A known value with nothing on it today is an empty 200, free. A bookmaker outside the call's region is 403 bookmaker_not_in_region.

No per-price time stamp

Matched offers carry no time of their own. The reply's time is meta.processed_at, and meta.last_seen gives each bookmaker and sport's last read. The freshness guide covers both.

From the blog