Skip to end of metadata
Go to start of metadata

You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 2 Next »

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.

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.

 Example 'Body' of the post request
{
    "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 - 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

 Example body for '1x2' market
{
  "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
      }
    }
  ]
}

 Example body of a 'Spread' market
{
  "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
      }
    }
  ]
}
 Example body of a 'Player props market'
{
  "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

 Example Request Body
{
  "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’

 Example Request Body
"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:
https://swaggerui.api.geniussports.com/?url=https://explorer.api.geniussports.com/OddsFeed-Ingestion%2Fv1%2FProduction%2Fswagger-latest.yaml

FAQ

 For how long is the access_token valid?

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

 Why do I get an error 'Decimal Price must be bigger than 1 (one) !' ?

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.

 Can I use the same sourceFixtureId across multiple different events?

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

 Can I use the same sourceMarketId across multiple different events?

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

 Can I use the same selection Ids across multiple different events?

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

 When updating a fixture and/or market can I use a different sourceFixtureId, sourceMarketId, selection Ids?

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

 What is the 'range' field in the selections used for?

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

 What are hasInPlay and hasPreMatch fields used for?

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

 Can I send markets before fixtures

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

 Can I see to what GS entities have the fixtures and markets been matched/classified to?

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.

 What does the 'Response code' mean?

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

  • No labels