Insights

Cricket odds API guide

A cricket odds API is the feed a sportsbook, a trading desk, or a media product uses to show cricket events and the prices on them. Cricket asks more of that feed than a simple two-way match price. A single game can run for an afternoon or for five days, markets suspend between balls, and players expect a scorecard next to the odds. This guide explains the pieces operators actually integrate: the event list, the market types, the scorecard, and the refresh rhythm that keeps an in-play screen honest. HZURA delivers cricket as part of the Sports Data API. The field-level reference is the Sports API, linked from the developer documentation.

Published
Updated
Author
HZURA Team

What you are integrating

Treat the API as three reads, in this order. First, ask which sports the account can use. Second, ask for the events of one sport. Third, ask for one event when you need its markets. On the HZURA Sports API those calls are GET /api/v1/sports, GET /api/v1/{sport}/events, and GET /api/v1/{sport}/events/{eventId}. The cricket key is cricket, in lower case. The other keys in the published reference are football, tennis, horse-racing, and greyhound-racing. An account only receives the sports that are enabled for it.

The events call returns the current events without the odds. Each event has a numeric id, gmid, and a name. You pass that gmid back as the event id when you want markets. The single-event call returns the event plus an odds list. There is no separate odds URL. If the event has no odds yet, the API returns odds_not_found. If you ask for an event id that is not in that sport, it returns event_not_found. The API playground is a way to try the same reads in the browser. Production calls come from a server whose IP address is on the account allow-list.

The Sports API is a fixed monthly service. Pricing is shared on request through the contact page. Sandbox and staging access uses IP whitelisting. Extra cricket markets, beyond the types described below, are available on request. Examples HZURA already names are meter and khado. Ask for them in the same request as access, so the account is enabled for the markets the product will show.

Events, formats, and what to show first

Cricket products usually group matches by format: Test matches, one-day matches, and T20. The API does not ask you to invent that grouping. It gives you events under the cricket key, each with a name and a status. Your client decides how to label a competition and how to sort the lobby. A practical lobby is a list of events that are open, with the name the API sent, rather than a hand-maintained spreadsheet of fixtures.

Status matters more than a decorative badge. An event that is open can still have individual markets that are suspended. Read the market status as well as the event status before you enable the bet slip. When a market is settled, the same event payload says so in that market's status. There is no separate results endpoint. A results job is a client that notices the settled status and then settles the bets in the operator's own wallet.

Do not assume every cricket competition is on every account. Coverage is whatever the account is enabled for. During integration, dump the events list for cricket and compare it with the competitions you promised the business. Gaps are a commercial question, handled on the contact page, not a parsing bug. The Sports Data API product page is the place to start that conversation, and the sports betting odds API page states the fixed monthly service in product language.

Markets the feed actually carries

Each item in the odds list is one market. Tell markets apart with gtype and marketName. Prices in the published reference are decimal odds. Size is how much can be staked at that price. New market types can appear, so a client should display an unknown type as a named market, or hide it, without crashing the page.

Three shapes are documented today. gtype match is the match-odds style market. It has runners, and each runner can have availableToBack and availableToLay prices. gtype match1 is the bookmaker shape, again with runners and back and lay prices. Bookmaker prices can also include price1. gtype fancy and fancy1 are session markets. They use a section list instead of runners. Each section has a name, a state, and its own odds list. That is the usual shape of a cricket session or fancy market, where the line is a number of runs in a phase of the innings rather than a team name.

Back and lay on the same runner is an exchange-style display. A fixed-odds sportsbook may only offer one side to the player and keep the other for trading. That is a product decision. The API still sends the prices it has. Map them in one place in your code so the slip, the trading screen, and the settlement record use the same selection id. Selection ids can be text or a number. Store them as strings.

  • Match odds: runners with back and lay prices, gtype match.
  • Bookmaker: runners with back and lay prices, gtype match1.
  • Fancy and session: a section list, gtype fancy or fancy1.
  • Meter and khado: available on request, not by guessing field names.

Live scores and scorecards

The scorecard is the live match state a player reads beside the odds: runs, wickets, and overs, and on a fuller card the batsmen, the bowlers, and the extras. A sportsbook that shows prices without that context is hard to bet on, because cricket markets often refer to a phase of the innings. A session line only makes sense if the player can see where the innings is.

HZURA includes multiple scorecard styles with the Sports API. A style is the layout of that match state. Operators do not all want the same density. A compact line fits a mobile slip. A fuller card fits an event page. Ask which styles are enabled for the account when you request access, and design the event page so the style can change without a new odds parser. The odds list and the scorecard are different jobs. The odds list is the markets. The scorecard is how the match is shown.

Latency: how fresh the price is

In-play cricket changes on a ball. A price that was fair before the ball can be wrong after it. Latency here is the gap between the match and the price on the slip, and it is mostly an integration choice. The published Sports API is request and response. Each GET returns the latest data HZURA has at that moment. The reference does not describe a push stream. To stay current, ask again.

Ask for the single event while that event is on screen, and stop when it is not. Asking for the event keeps its odds refreshed more often. Asking again can return the same body if nothing changed, which is a normal outcome, not an error. Reuse HTTP connections so the refresh loop is not paying a new handshake every time. Health, GET /api/v1/health, is the check that the API is up, and it does not need a key.

The account has a rate limit on the sports list and both event routes. Health is not counted. When the limit is hit, the API returns 429 rate_limited and a Retry-After header with the number of seconds to wait. Requests you send during that wait still count, so honour the header. The numeric limit is set per account. If the product needs a faster loop than the account allows, ask HZURA. Do not solve a 429 by opening more connections.

Judge freshness on your own screen during a live match. If the slip still offers a price after the market status is no longer open, the client is ignoring status. If the screen waits many balls between requests, the product looks late even when the feed is fine.

Client behaviour that avoids bad bets

Accept a bet against a price you just displayed, and re-read the event if the player hesitates. Cricket slips that cache a price for a long animation will take bets the market has already left. A clear rule is enough: if the price or the size changed, show the new price and ask the player to confirm. If the market is suspended, say so and do not queue the bet.

Handle the error document. invalid_sport, sport_not_allowed, invalid_event_id, and the availability errors are documented on the Sports API page and on the errors page. sport_not_allowed means the account is not enabled for that sport. That is fixed by a request, not by retrying. ip_not_allowed means the server address is not on the allow-list. Add the address of the server that will call the API, including the staging server.

API only, or a full sportsbook

Use the Sports API when you already have, or are building, the wallet, the slip, and the risk tools, and you need cricket odds and scorecards inside that product. The integration is the three reads above, plus your own bet storage. A white-label sportsbook is the other product: a branded book that includes odds, trading, player accounts, and the back office. That sportsbook can be ready in about 7 days, meaning HZURA's platform setup. Work outside HZURA, such as payment onboarding and DNS, can move the player-facing date.

The how to launch an online sportsbook guide lists those components. Read it if the API feels like it is missing a cashier. The API is not missing it. The cashier was never part of the feed. Pricing for either product is shared on request.

Integration checklist

You can start from the public docs today and request access when the client shape is clear. Read developers, then the Sports API. Confirm the account's sports list includes cricket. Pull events, pick a gmid, and render odds by gtype. Put a scorecard on the same event id, using one of the styles included with the API. Poll only while the event is visible. Settle from market status. Send bets to your own wallet with an idempotency key.

When you contact HZURA, say that you need the Sports API for cricket, which scorecard styles you want, and whether meter or khado should be enabled. Mention if you also want the White Label Sportsbook. Pricing is shared on request. The Sports Data API page is the product summary to attach to that request.

Talk to HZURA

Pricing is shared on request. Tell us which product you are evaluating and what you already have in place.

Contact HZURA