Introduction

Getting started with Oddsgigant API.

requirement

You need a license key to use the API. This key must be sent with every request as the auth parameter.

A license can support up to two IP addresses. If you don't get data, check if your IP address is registered.

Using in-play data

To work with the in-play data you first need the event information for these events.

  1. Send a request to get the events list for your chosen sport and store the response. This data contains the events' IDs, country and division information, as well as the team names for all running events of your chosen sport.

  2. Loop through the events list and get the odds by sending an events odds request for each event ID. You can request up to 10 event IDs at a time.

You can now theoretically simply repeat this to show the in-play events on your page. But this is not recommended, as on peak hours there can over 250 simultaneously running events for soccer alone. If you request all events with all data as fast as you can you will quickly exhaust your limits.

tip

We recommend you request the events list every 1 or 2 minutes to keep up with newly starting games. The odds should be requested every 2 - 3 seconds for fast sports like tennis and a litle slower for other sports.

Very important: always store the odds together with the running game score you get them with.

Throttling odds requests like this will naturally delay your regular in-play data. For quicker access to up-to-date game information, use the fast access endpoint.

Updating in-play data in real time

It is extremely important to keep running game information like score, stage and playtime up to date. To make this possible, we offer the fast access endpoint. This only contains the most vital info needed to keep in-play events up-to-date. Similarly to the list endpoint, this combines all events from a single sport into one response.

tip

We recommend that you poll the fast access endpoint at 650 ms intervals.

Always use this request at the highest priority to update events. If you detect a score change, close all odds not valid for this score (remember to store this data together), and wait for the updated odds matching the new score.

Updating soccer playtime

To display the playtime correctly you need to calculate it from the kickoff time. This is the playtime field from the fast access request. The kickoff time is a UTC timestamp formated as ISO 8601. Use this to calculate the playtime in minutes and seconds and display it. An example function is given below:

function getSoccerTime(playtime: string) {
  const diff = Date.now() - Date.parse(playtime)
  const min = Math.floor(diff / 60_000)
    .toString()
    .padStart(2, '0')
  const sec = Math.floor((diff % 60_000) / 1000)
    .toString()
    .padStart(2, '0')

  return `${min}:${sec}`
}

This playtime will be recalculated on our side after a match interruption of this match and after the halftime. Make sure to update your page accordingly.

The event object also contains a field playtimeSeconds, which is the playtime in the moment we update the in-play data. But because we only update it on 3 sec intervals, the playtime will lag if you use this to display it. Hence it is only suitable if you plan a page without active inplay updates like a static score page.