OddsFeed Platform Ingestion API

Provides a simple way to push (or ingest) fixture and market data in Genius Sports OddsFeed Platform (OIS).

Changelog

How does the security work?

To access Ingestion API each request must provide two headers:

• Authorization header with an OAuth2 JSON web token (Bearer) issued by Auth0.
• x-api-key with an API key secret of a key, registered with the API gateway in AWS.

How do I get a valid JW token for the Authorization header?

As an Ingestion API client, I must be provided with Auth0 Client credentials (client_ID and Client_secret) by Genius Sports (OIS team) and obtain a valid token from the Auth0 token endpoint using the Machine-to-Machine (client credentials) flow. I must obtain a new token whenever needed (based on the token expiration).

Make a POST request to the token endpoint: https://genius-sports.eu.auth0.com/oauth/token with the following payload:

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

You will receive a new token in the response access_token field.

Curl example:

How do I know the correct sport id to use with sportId fixtures property?

You can retrieve the ids and descriptions used for sports by Genius Sports via the coresponding Fixtures API sports call.

If you already know the valid name for the sport then you may use it as a filter to retrieve the specific sport id, or else you may retrieve all sports' ids and descriptions without filter.

Note You need to provide a distinct (different) x-api-key provided to you specifically for accessing the Fixtures API.

Using the Ingestion API

After obdaining your x-api-key and a valid JW token, you are ready to use the API.

Use this call to test connection:

• curl https://oddsfeed.api.geniussports.com/ingestion/v1/health -H 'Content-Type: application/json' -H 'x-api-key: YOUR_API_KEY' -H 'Authorization: Bearer YOUR_JW_TOKEN'

In order to work with source fixtures and markets, you also need to provide a valid GS sourceId (obdained by Genius Sports) in every call Url sourceId query parameter.

Working with source fixtures

There are three (3) operations supported for source fixture entries:

• POST: Use to ingest a source fixture. The fixture will be updated if already exists, inserted if new, then it will be propagated to OIS together with its source markets that might have been ingested before.
• GET: Use to retrieve a previously ingested source fixture.
• DELETE: Use to delete a previously ingested source fixture and change its OIS status to Unavailable. The fixture source markets will be deleted as well and their OIS status will also change to Unavailable.

Curl examples:

• POST example: Use to ingest a source fixture that you provide in the request body; you should recieve code 201 (Created) or 202 (Updated), or data validation error if the fixture data provided are invalid, i.e. if sportId is missing or invalid.
  • curl -X 'POST' https://oddsfeed.api.geniussports.com/ingestion/v1/sources/YOUR_SOURCE_ID/fixtures/YOUR_SOURCE_FIXTURE_ID -H 'Content-Type: application/json' -H 'x-api-key: YOUR_API_KEY' -H 'Authorization: Bearer YOUR_ID_TOKEN' -d '{YOUR_FIXTURE_JSON_OBJECT}'
• GET example: Use to retrieve the previously ingested source fixture; you should recieve code 200 (OK) and the source fixture in the response body.
  • curl https://oddsfeed.api.geniussports.com/ingestion/v1/sources/YOUR_SOURCE_ID/fixtures/YOUR_SOURCE_FIXTURE_ID -H 'Content-Type: application/json' -H 'x-api-key: YOUR_API_KEY' -H 'Authorization: Bearer YOUR_ID_TOKEN'
• DELETE example: Use to delete the source fixture and its source markets and change their OIS status to Unavailable; on success, you should recieve code 204 (NoContent).
  • curl -X 'DELETE' https://oddsfeed.api.geniussports.com/ingestion/v1/sources/YOUR_SOURCE_ID/fixtures/YOUR_SOURCE_FIXTURE_ID -H 'Content-Type: application/json' -H 'x-api-key: YOUR_API_KEY' -H 'Authorization: Bearer YOUR_ID_TOKEN'

Working with source markets

There are three (3) operations supported for source market entries as well:

• POST: Use to ingest a source market. The market will be updated if already exists or inserted if new, then it will be propagated to OIS only if its corresponding fixture is already ingested.
• GET: Use to retrieve a previously ingested source market.
• DELETE: Use to delete a previously ingested source market, then change its OIS status to Unavailable only if its corresponding fixture is already ingested.

Curl examples:

• POST example: Use to ingest a source market that you provide in the request body; you should recieve code 201 (Created) or 202 (Updated), or data validation error if the market data provided are invalid, i.e. if selections is missing or one or more selection price is missing or inconsistent.
  • curl -X 'POST' https://oddsfeed.api.geniussports.com/ingestion/v1/sources/YOUR_SOURCE_ID/markets/YOUR_SOURCE_MARKET_ID -H 'Content-Type: application/json' -H 'x-api-key: YOUR_API_KEY' -H 'Authorization: Bearer YOUR_ID_TOKEN' -d '{YOUR_MARKET_JSON_OBJECT}'
• GET example: Use to retrieve the previously ingested source market; you should recieve code 200 (OK) and the source market in the response body.
  • curl https://oddsfeed.api.geniussports.com/ingestion/v1/sources/YOUR_SOURCE_ID/markets/YOUR_SOURCE_MARKET_ID -H 'Content-Type: application/json' -H 'x-api-key: YOUR_API_KEY' -H 'Authorization: Bearer YOUR_ID_TOKEN'
• DELETE example: Use to delete the source market, and if its corresponding fixture is already ingested then change its OIS status to Unavailable; on success, you should recieve code 204 (NoContent).
  • curl -X 'DELETE' https://oddsfeed.api.geniussports.com/ingestion/v1/sources/YOUR_SOURCE_ID/markets/YOUR_SOURCE_MARKET_ID -H 'Content-Type: application/json' -H 'x-api-key: YOUR_API_KEY' -H 'Authorization: Bearer YOUR_ID_TOKEN'

Fixture and Market Structure

The data contract structures used for source fixture and market are fully described in the corresponding Swagger Models below, i.e. SourceFixtureRequest model for the fixture and SourceMarketRequest model for the market