Sports API

In short: ask which sports you can use, pick one, list its events, then ask for one event to get its odds. Keep asking for that event while you show it, to stay up to date.

Results are not a separate route. When a market is settled, its status on the event says so.

Sport keys are lowercase and must match exactly (cricket, not Cricket). The keys are cricket, football, tennis, horse-racing and greyhound-racing. You only get the ones enabled for your account.

sport

A key from GET /api/v1/sports, used in place of {sport}.

event ID

The event's gmid, a whole number, used in place of {eventId}.

odds

The odds list on the single-event answer. There is no separate odds address.

None of these routes take query parameters.

Odds are the odds list on GET /api/v1/{sport}/events/{eventId}. Each item is one market. Tell markets apart by gtype (the market type) and marketName.

Prices are decimal odds. size is how much can be staked at that price. New market types can appear, so handle ones you do not know without breaking.

marketName

The market's name to show.

marketId

The market's id.

gtype

The market type.

status

The market's state, including settled when the result is known.

runners[].selectionId

The selection's id. It can be text or a number.

runners[].runnerName

The selection's name.

runners[].status

The selection's state.

runners[].ex.availableToBack

Back prices, each { price, size }.

runners[].ex.availableToLay

Lay prices, each { price, size }.

Bookmaker (match1) prices can also have price1. Fancy markets use section instead of runners: each entry has a name (nat), a state (gstatus) and its own odds list.

There is no separate results route. Results appear on the same event: a settled market shows it in its status, and selections in theirs where available.

• Every answer is the latest data HZURA has when you ask. The API never makes you wait for a fresh update.
• There is no push or live stream. To stay current, ask again.
• Asking again can return the same data if nothing has changed.
• Ask for GET /api/v1/{sport}/events/{eventId} as often as your screen needs while the event is shown. Reuse your HTTP connections.

/api/v1/sports and both event routes count towards one limit for your account. Health has no limit. Your limit is set for your account; ask HZURA if you need more.

When you reach it you get 429 rate_limited with a Retry-After header: the number of seconds to wait. Requests sent while you are limited still count, so do wait.

• AuthenticationAPI keys and IP allow-lists.
• ErrorsThe error format and every sports error code.

1. Call GET /api/v1/sports and pick a key.
2. Call GET /api/v1/{sport}/events.
3. Pick an event and take its gmid.
4. Call GET /api/v1/{sport}/events/{eventId} and read odds.
5. Call it again regularly while the event is on screen.

const base = "https://api.hzura.com/api/v1";
const headers = {
  Authorization: "Bearer YOUR_API_KEY",
  Accept: "application/json",
};

const sports = await fetch(`${base}/sports`, { headers }).then((r) => r.json());
const sportKey = sports.sports[0].key;

const events = await fetch(`${base}/${sportKey}/events`, { headers }).then((r) => r.json());
const eventId = events[0].gmid;

const response = await fetch(`${base}/${sportKey}/events/${eventId}`, { headers });
const data = await response.json();

data.event is the event and data.odds its markets. You can try the same calls in the API playground. Run your own code on a server whose IP address is on your allow-list.