/
Odds Feed Ingestion API old

Odds Feed Ingestion API old

Owned by Raiko Pajur
Last updated: Feb 12, 2025 by Iryna Antonova
7 min read

Overview

Odds Feed Ingestion API is a push API allowing customers to integrate Fixtures and Odds Feed data with Genius Sports. Inserting data into our system allows us to match the equivalent data of both parties.

URLs

Use Cases

Authorization

For authorization customer need to obtain a valid API token using Auth0 clientId, client secret and an API key. To acquire Auth0 clientId, client secret and an API key please contact apikey@geniussports.com.

To obtain a valid token POST call needs to be made to the endpoint https://genius-sports.eu.auth0.com/oauth/token, with the below payload:

{ "client_id": "YOUR_AUTH0_CLIENT_ID", "client_secret": "YOUR_AUTH0_CLIENT_SECRET", "audience": "https://api.geniussports.com", "grant_type": "client_credentials" }

Response contains the token in the access_token field.

The Odds Feed Ingestion API includes an endpoint for heartbeats (https://explorer.api.geniussports.com/OddsFeed-Ingestion/v1/Production/public/index.html#tag/SourceHeartbeat ). While it is not obligatory to use, it is a useful feature to have. The absence of heartbeats will not automatically invalidate markets, even if heartbeats are integrated. If you also have our Betvision product integrated this feature will ensure that BetVision displays accurate prices and markets that are not suspended.
Please consult Swagger for more information on this.

Source Fixtures

Sending new fixtures

A new fixture is created using the ‘SourceFixtures’ POST endpoint.

The endpoint expects three mandatory parameters:

  • SourceId - provided by Genius Sports

  • SourceFixtureId - Customer fixture ID

  • Body of the request, with the following mandatory fields:

    • name - the name of the event. E.g. ‘Barcelona vs. Real Madrid’

    • sportId - Genius Sports sport ID, this can be obtain from the Fixture API.

    • startTime - the start date and time of an event

    • hasInPlay - indicates if the event and its markets/prices are offered In-Play

    • hasPreMatch - indicates if the event and its markets/prices are offered Pre-Match

SourceFixtureId must be unique across one source.

 

{ "name":"Young Africans vs Marumo Gallants FC", "sportId":10, "startTime":"2023-05-11T13:00:00Z", "hasInPlay":"Unspecified", "hasPreMatch":"Unspecified", "venue":null, "competition": { "id":"1958", "name":"CAF Confederation Cup" }, "season": { "id":"115417", "name":"2022/2023 CAF Confederation Cup" }, "round": { "id":"1037502", "name":"Marumo Gallants FC v Young Africans" }, "competitors": [ { "id":"471464", "name":"Young Africans", "isHome":true, "lineup":null }, { "id":"1002214", "name":"Marumo Gallants FC", "isHome":false, "lineup":null } ] }

 

Updating an existing fixture

Updating an existing fixture must happen in cases where there has been a significant change to it. For instance:

  • start time has changed

  • competitors have changed

  • sportId was wrong and the correct one is sent

  • etc.

Making an update is no different than creating a new fixture in term of what request should be made to the API. The last request will overwrite the previous one’s data.

Please do not change the SourceFixtureId when making updates.

Invalidating existing fixtures

A Fixture can be invalidated using the ‘SourceFixtures' DELETE endpoint. This will not actually delete the fixture, but mark it as 'Unavailable’, so that downstream consumers of this data are aware it is not relevant.

You would want to 'Delete' a fixture if it is not relevant anymore. For instance:

  • The event has ended

  • The event has been cancelled

  • etc.

The expected parameters are sourceId and sourceFixtureId.

Querying what information has been sent for a specific fixture

In case a user of the API is interested what fixtures data has been pushed, he can use the 'SourceFixtures' GET endpoint.

This will return the 'Raw' data that has been integrated, before any processing (e.g. matching) is done.

The expected parameters are sourceId and sourceFixtureId.

Source Markets

In most cases market updates must be done when the price of any of the selections has changed. The API allows other fields to be changed as well (new selection, handicap boolean, selection name, etc.), but these should be rather fixed and rarely updated.

Sending new markets

A new market (event) is sent using the ‘SourceMarkets’ POST endpoint.

The endpoint expects three mandatory parameters:

  • sourceId - unique customer id provided by Genius Sports

  • sourceMarketId - this is the source market Id (provided the integrating team)

  • Body of the request, with the following mandatory fields:

    • sourceFixtureId - the event id provided by the integrating team.

    • name - name of the market (e.g. 'Money Line')

    • isHandicap - indicates whether this is a handicap market or not

    • selections, with the following mandatory fields:

      • id - this is the source id of the selection.

      • name - the source name of the selection (e.g. ‘Over', ‘Under’, ‘Home competitor name’, ‘Away competitor name', 'Draw’, etc.)

      • price

  • sourceMarketId must be unique across one source

  • selection Ids must be unique across one source

  • At least one of the decimalPrice, fractionalPrice or americanPrice properties should be set. A combination of all of them is also a valid.

Selections are tightly coupled with the type of the market. Hence the number of selections and the data will vary depending on the market type. For instance:

  • For market ‘Both team to score’ we will expect:

    • 2 selections

    • selection name 1 - 'Yes'

    • selection name 2 - 'No'

  • For market '1x2' we will expect:

    • 3 selections

    • selection name 1 - Home competitor name

    • selection name 2 - Away competitor name

    • selection name 3 - Draw

{ "sourceFixtureId": "1234", "name": "1x2", "isHandicap": false, "isSuspended": false, "selections": [ { "id": "1234", "name": "Espérance ST(Sportive de Tunis)", "isSuspended": false, "handicap": null, "price": { "decimal": 2, "fractional": { "denominator": 1, "numerator": 1 }, "american": 100 }, "range": { "min": 1, "max": 2 } }, { "id": "1235", "name": "Al Ahli Cairo", "isSuspended": false, "handicap": null, "price": { "decimal": 3 }, "range": { "min": 1, "max": 2 } }, { "id": "1236", "name": "Draw", "isSuspended": false, "handicap": null, "price": { "decimal": 2.5 }, "range": { "min": 1, "max": 2 } } ] }

 

{ "sourceFixtureId": "1234", "name": "Spread", "isHandicap": true, "isSuspended": false, "selections": [ { "id": "12345", "name": "Espérance ST(Sportive de Tunis)", "isSuspended": false, "handicap": 1, "price": { "decimal": 2, "fractional": { "denominator": 1, "numerator": 1 }, "american": 100 }, "range": { "min": 1, "max": 2 } }, { "id": "12356", "name": "Al Ahli Cairo", "isSuspended": false, "handicap": -1, "price": { "decimal": 3 }, "range": { "min": 1, "max": 2 } } ] }
{ "sourceFixtureId": "1234", "name": "Tom Brady Total Passing Yards", "isHandicap": true, "isSuspended": false, "selections": [ { "id": "12345", "name": "Tom Brady_Over", "isSuspended": false, "handicap": 300, "price": { "decimal": 2, "fractional": { "denominator": 1, "numerator": 1 }, "american": 100 }, "range": { "min": 1, "max": 2 } }, { "id": "12356", "name": "Tom Brady_Under", "isSuspended": false, "handicap": 300, "price": { "decimal": 3 }, "range": { "min": 1, "max": 2 } } ] }

Handicap Markets

  • Separate handicap markets should be created for each handicap line.

    • One market for -0.5/+0.5, one market for -1.5/+1.5, etc.

  • About handicap markets, It's also important the selections to have the handicap property set

Updating market prices

If a price update of an existing market must be made, the POST endpoint should be used. The value that must be changed is the 'price' field, which is part of the selection.

Each selection has its own price, thus you need to make sure to pass the correct selection Id and Name, so that the correct selection price is updated.

Suspending a market

In the case where bets are not accepted temporarily for a market, the state of the market can be marked as ‘Suspended'. Once the market is open to accept bets once again, a new update should be made to remove the 'suspended state’.

This is done using the SourceMarkets POST endpoint passing:

  • sourceId

  • sourceMarketId

  • Request Body

    • where isSuspended is true

{ "sourceFixtureId": "1234", "name": "Spread", "isHandicap": true, "isSuspended": true, "selections":

Invalidating an existing market

In addition to suspending a market, the user can also invalidate it using the ‘SourceMarkets' DELETE endpoint. This will not actually delete the market, but mark it as ‘Unavailable’, so that the downstream consumers of this data are aware its data is not relevant and shouldn’t be used.

The main use case for invalidating a market is when it has been permanently closed for the event. This differs from the suspended state, which indicates that the punter temporarily cannot place bets on that market.

The expected parameters are sourceId and sourceMarketId.

Suspending a selection

There is also the option to suspend only a specific selection in a market, if there’s a good reason for that. Such update should be rather rare, because most time the whole market would be suspended.

To make this change the user should use the SourceMarkets POST endpoint passing:

  • sourceId

  • sourceMarketId

  • Body

    • where the selections' isSuspended parameter is set to ‘true’

 

"selections": [ { "id": "1234", "name": "Espérance ST(Sportive de Tunis)", "isSuspended": true, "handicap": null, "price": { "decimal": 2, "fractional": { "denominator": 1, "numerator": 1 }, "american": 100 }, "range": { "min": 1, "max": 2 } },

Querying what information was sent for a specific market

In case a user of the API is interested what market data has been sent, he can use the 'SourceMarkets' GET endpoint.

This will return the 'Raw' market data that has been integrated, before any processing (e.g. matching) is done.

The expected parameters are sourceId and sourceMarketId.

Swagger

You can find sample calls and and further technical info from the swagger link below:
Swagger UI

FAQ

  • The access_token is valid for 86400 seconds (24h) for all environments

In betting the decimal betting price is set higher than one to account for both the original stake and the potential profit, ensuring that bettors receive a positive return when their bets are successful. Thus, there is a validation not allowing any prices equal to or lower than 1.

Due to additional internal processing of the received data, all events (external) in a source should have unique sourceFixtureIds.

Due to additional internal processing of the received data, all markets (external) in a source should have unique sourceMarketIds.

Due to additional internal processing of the received data, all selections (external) in a source should have unique selection Ids.

On update of existing fixture and/or market the sourceFixtureId, sourceMarketId and selection Ids must be kept the same.

The field is only applicable for range markets, e.g. ‘Number of goals’.

They are used to indicate whether the event and its markets and prices are available for PreMatch or InPlay betting.

This is a valid case. However, markets' data won’t be distributed to downstream consumers, unless the market is part of a fixture.

OddsFeed Ingestion API is built explicitly for the ingestion of external data. It has no knowledge whatsoever how this data is then process down the pipeline.

There is a description in swagger what each Response code means. If further clarity is needed you can refer to this page.