| Table of Contents | ||
|---|---|---|
|
Overview
Welcome to the Fixtures API v2 documentation!
What is Fixtures API v2?
This API allows you to access specific information about sports, competitions, seasons, sport events, players, and related concepts from the Genius Sports Fixtures master data.
For what use cases you can use Fixtures API v2?
1. Read Data
When to use it?
When you want to retrieve various details related to fixture schedules, such as:
...
Discover who is playing in a particular fixture.
Example: Real Madrid vs. Barcelona
Find out when and where a sport event (fixture) is happening.
Example: 22.08.2024 at 19:00 at Santiago Bernabeu
Learn about specific sport-specific rules of the game.
Example: Extra time applied
2. Ingest Data in Genius Sports
When to use it?
When you need to integrate your competitions, fixtures and associated data directly into the Genius Sports Fixtures master data. This streamlines the integration process as all necessary internal procedures, including validation, matching, and state management, are handled internally by Genius Sports.
...
Update start time of Real Madrid vs. Barcelona to 19:15
Send the contracted players with their metadata per team e.g. Real Madrid with players: Daniel Carvajal Ramos (Date of Birth: 1991-07-01, Male, …), Lucas Vazquez Iglesias (…), etc.
3. Update Genius Sports data
When to use it?
If you require modifying Genius Sports Fixtures data that cannot be done through ingestion, such as Competition Name, Competitor Name, or Venue, your data must adhere to Genius Sports' specific structure, which can be seen below and in the API endpoints. To utilize these functionalities, you need a Genius Sports ID, obtainable through the Ingestion endpoint by tracking the results. Depending on your permissions' level, you can undertake actions like:
...
After ingesting data through Ingestion and obtaining the Genius Sports ID for a competition and fixture, if you wish to update the venue you can do that by sending that information. For example adding country “Spain” to “Santiago Bernabeu” venue.
How is our data Structured?
Our data is organized according to the following primary properties, forming our Fixtures Hierarchy. Each of these properties can be accessed through the corresponding endpoints of the API.
...
| Lucidchart | ||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
What is new in Fixtures API v2?
Consistent pagination with up to 200 items per page
Sorting by specific field(s) for example by id, name, descending
Filter by specific fields
For single ID filtering: Example: filter=id[equals]:1
For filtering by multiple IDs: Example: filter=id[in]:1,2,3
For stacking filters: Separate them with "". Example: filter=id[in]:1,2,3sportId[in]:1,2,3,4,5
Different filter comparators available:
equals: Matches exact values of all data types
notequals: Filters out values not matching the specified criteria
in: Matches values from a specified list, works only with integer and decimal values
nin: Excludes values from a specified list, works only with integer and decimal values
gte: Greater than or equal to comparator
lte: Less than or equal to comparator
contains: Matches values containing a specified substring
startsWith: Matches values starting with a specified substring
Duplications of the "filter" property are allowed only in the case of "range" filtering, such as filter=startDate[gte]:2021-07-28~startDate[lte]:2021-07-29
filtering by null:
Equal to null: filter=cityName[equals]:null
Not equal to null: filter=cityName[notequals]:null
The API maintains a uniform structure, with each endpoint offering two functionalities:
A listing endpoint for multiple items, enabling filtering and sorting via query parameters.
An endpoint dedicated to retrieving a single item using its unique identifier (ID).
The API doesn’t contain deleted fixtures
New “Person” entity introduced: Person is a representation of a real-life person which can be used in specific context:
For Competitors of type /wiki/spaces/OTF/pages/3976890114 it is the person behind the player.
For Competitors of type /wiki/spaces/OTF/pages/3978134069 it is part of their squad, or is the coach, or the owner.
For Competitors of type /wiki/spaces/OTF/pages/3977642592 it is the persons behind the Doubles Partnership or their coach.
For Competitors of type Dog and Horse it is the trainer, the owner or the breeder.
- For Competitors of type Horses it could also be its JockeyFor /wiki/spaces/OTF/pages/3976890121 either Official Referee or Assistant Referee
In the Fixtures API v2, we support rosters (also known as "Squads"), which represent a list of all players registered to a team and available for selection in each fixture. However, the API does not support lineups, which refer to specific players participating in a particular fixture.
How to Start with Fixtures API v2?
Access to Fixture API V2
To access the Fixture API V2 you will need to use an Auth0 Client (client Secret and clientId) and API key supplied by Genius Sports. Please contact your integration manager for further details.
Steps to call the API
Call the Auth API to get a Token:
...
| Panel | ||||||
|---|---|---|---|---|---|---|
| ||||||
Online Technical Documentation |
Sample API calls demonstrating how to utilize the API for particular use cases
Use case “Read Data”
Find the sport
First step is to find the sport you are licensed to receive or is relevant to your current work. The following examples will all be from American Football:
...
| Code Block |
|---|
{
"page": 1,
"pageSize": 5,
"totalItems": 285,
"items": [
{
"isDeleted": false,
"startDate": "2023-01-17T01:15:00Z",
"name": "Tampa Bay Buccaneers v Dallas Cowboys",
"season": {
"id": 108075,
"name": "2022/2023 NFL",
"ref": "/seasons/108075"
},
"eventStatusType": "Finished",
"locality": {
"id": 140,
"name": "United States of America",
"ref": "/localities/140"
},
"timezone": {
"id": 34,
"name": "US/Eastern",
"ref": "/timezones/34"
},
"venue": {
"id": 257,
"name": "Raymond James Stadium",
"ref": "/venues/257"
},
"sport": {
"id": 17,
"name": "American Football",
"ref": "/sports/17"
},
"competition": {
"id": 296,
"name": "NFL",
"ref": "/competitions/296"
},
"round": {
"id": 984676,
"name": "Wild Card",
"ref": "/rounds/984676"
},
"genderType": "Male",
"homeCompetitor": {
"id": 92305,
"name": "Tampa Bay Buccaneers",
"competitorType": "Team",
"ref": "/competitors/Teams/92305"
},
"competitors": [
{
"metadataProperties": [
{
"name": "ShortName",
"value": "Buccaneers",
"isDeleted": false
},
{
"name": "FullDescription",
"value": "Tampa Bay Buccaneers",
"isDeleted": false
}
],
"id": 92305,
"name": "Tampa Bay Buccaneers",
"competitorType": "Team",
"ref": "/competitors/Teams/92305"
},
{
"metadataProperties": [
{
"name": "ShortName",
"value": "Cowboys",
"isDeleted": false
},
{
"name": "FullDescription",
"value": "Dallas Cowboys",
"isDeleted": false
}
],
"id": 96760,
"name": "Dallas Cowboys",
"competitorType": "Team",
"ref": "/competitors/Teams/96760"
}
],
"eventType": "Match",
"metadataProperties": [
{
"name": "OvertimePeriodDuration",
"value": "15",
"isDeleted": false
},
{
"name": "HasLineups",
"value": "yes",
"isDeleted": false
}
],
"id": 9913192,
"createdOn": "2023-01-09T04:51:07Z",
"modifiedOn": "2023-01-17T05:30:02Z",
"updatesCount": 4
},
{
"isDeleted": false,
"startDate": "2023-02-12T23:40:00Z",
"name": "Philadelphia Eagles v Kansas City Chiefs",
"season": {
"id": 108075,
"name": "2022/2023 NFL",
"ref": "/seasons/108075"
},
"eventStatusType": "Finished",
"locality": {
"id": 140,
"name": "United States of America",
"ref": "/localities/140"
},
"timezone": {
"id": 34,
"name": "US/Eastern",
"ref": "/timezones/34"
},
"venue": {
"id": 262,
"name": "State Farm Stadium",
"ref": "/venues/262"
},
"sport": {
"id": 17,
"name": "American Football",
"ref": "/sports/17"
},
"competition": {
"id": 296,
"name": "NFL",
"ref": "/competitions/296"
},
"round": {
"id": 984680,
"name": "Super Bowl 57",
"ref": "/rounds/984680"
},
"genderType": "Male",
"homeCompetitor": {
"id": 89169,
"name": "Philadelphia Eagles",
"competitorType": "Team",
"ref": "/competitors/Teams/89169"
},
"competitors": [
{
"metadataProperties": [
{
"name": "ShortName",
"value": "Eagles",
"isDeleted": false
},
{
"name": "FullDescription",
"value": "Philadelphia Eagles",
"isDeleted": false
}
],
"id": 89169,
"name": "Philadelphia Eagles",
"competitorType": "Team",
"ref": "/competitors/Teams/89169"
},
{
"metadataProperties": [
{
"name": "ShortName",
"value": "Chiefs",
"isDeleted": false
},
{
"name": "FullDescription",
"value": "Kansas City Chiefs",
"isDeleted": false
}
],
"id": 86068,
"name": "Kansas City Chiefs",
"competitorType": "Team",
"ref": "/competitors/Teams/86068"
}
],
"eventType": "Match",
"metadataProperties": [
{
"name": "OvertimePeriodDuration",
"value": "15",
"isDeleted": false
},
{
"name": "HomeAwayNeutralVenue",
"value": "neutral",
"isDeleted": false
},
{
"name": "HasLineups",
"value": "yes",
"isDeleted": false
}
],
"id": 9809948,
"createdOn": "2022-11-14T09:38:48Z",
"modifiedOn": "2023-02-13T04:00:02Z",
"updatesCount": 5
},
{
"isDeleted": false,
"startDate": "2023-01-29T23:30:00Z",
"name": "Kansas City Chiefs v Cincinnati Bengals",
"season": {
"id": 108075,
"name": "2022/2023 NFL",
"ref": "/seasons/108075"
},
"eventStatusType": "Finished",
"locality": {
"id": 140,
"name": "United States of America",
"ref": "/localities/140"
},
"timezone": {
"id": 34,
"name": "US/Eastern",
"ref": "/timezones/34"
},
"venue": {
"id": 239,
"name": "Arrowhead Stadium",
"ref": "/venues/239"
},
"sport": {
"id": 17,
"name": "American Football",
"ref": "/sports/17"
},
"competition": {
"id": 296,
"name": "NFL",
"ref": "/competitions/296"
},
"round": {
"id": 984679,
"name": "Conference Championships",
"ref": "/rounds/984679"
},
"genderType": "Male",
"homeCompetitor": {
"id": 86068,
"name": "Kansas City Chiefs",
"competitorType": "Team",
"ref": "/competitors/Teams/86068"
},
"competitors": [
{
"metadataProperties": [
{
"name": "ShortName",
"value": "Chiefs",
"isDeleted": false
},
{
"name": "FullDescription",
"value": "Kansas City Chiefs",
"isDeleted": false
}
],
"id": 86068,
"name": "Kansas City Chiefs",
"competitorType": "Team",
"ref": "/competitors/Teams/86068"
},
{
"metadataProperties": [
{
"name": "ShortName",
"value": "Bengals",
"isDeleted": false
},
{
"name": "FullDescription",
"value": "Cincinnati Bengals",
"isDeleted": false
}
],
"id": 102450,
"name": "Cincinnati Bengals",
"competitorType": "Team",
"ref": "/competitors/Teams/102450"
}
],
"eventType": "Match",
"isProtected": true,
"metadataProperties": [
{
"name": "OvertimePeriodDuration",
"value": "15",
"isDeleted": false
},
{
"name": "HasLineups",
"value": "yes",
"isDeleted": false
}
],
"id": 9809946,
"createdOn": "2022-11-14T07:36:54Z",
"modifiedOn": "2023-01-30T03:30:02Z",
"updatesCount": 6
},
{
"isDeleted": false,
"startDate": "2023-01-29T20:00:00Z",
"name": "Philadelphia Eagles v San Francisco 49ers",
"season": {
"id": 108075,
"name": "2022/2023 NFL",
"ref": "/seasons/108075"
},
"eventStatusType": "Finished",
"locality": {
"id": 140,
"name": "United States of America",
"ref": "/localities/140"
},
"timezone": {
"id": 34,
"name": "US/Eastern",
"ref": "/timezones/34"
},
"venue": {
"id": 250,
"name": "Lincoln Financial Field",
"ref": "/venues/250"
},
"sport": {
"id": 17,
"name": "American Football",
"ref": "/sports/17"
},
"competition": {
"id": 296,
"name": "NFL",
"ref": "/competitions/296"
},
"round": {
"id": 984679,
"name": "Conference Championships",
"ref": "/rounds/984679"
},
"genderType": "Male",
"homeCompetitor": {
"id": 89169,
"name": "Philadelphia Eagles",
"competitorType": "Team",
"ref": "/competitors/Teams/89169"
},
"competitors": [
{
"metadataProperties": [
{
"name": "ShortName",
"value": "Eagles",
"isDeleted": false
},
{
"name": "FullDescription",
"value": "Philadelphia Eagles",
"isDeleted": false
}
],
"id": 89169,
"name": "Philadelphia Eagles",
"competitorType": "Team",
"ref": "/competitors/Teams/89169"
},
{
"metadataProperties": [
{
"name": "ShortName",
"value": "49ers",
"isDeleted": false
},
{
"name": "FullDescription",
"value": "San Francisco 49ers",
"isDeleted": false
}
],
"id": 106530,
"name": "San Francisco 49ers",
"competitorType": "Team",
"ref": "/competitors/Teams/106530"
}
],
"eventType": "Match",
"metadataProperties": [
{
"name": "OvertimePeriodDuration",
"value": "15",
"isDeleted": false
},
{
"name": "HasLineups",
"value": "yes",
"isDeleted": false
}
],
"id": 9809945,
"createdOn": "2022-11-14T09:36:54Z",
"modifiedOn": "2023-01-30T00:00:04Z",
"updatesCount": 3
},
{
"isDeleted": false,
"startDate": "2023-01-22T23:30:00Z",
"name": "San Francisco 49ers v Dallas Cowboys",
"season": {
"id": 108075,
"name": "2022/2023 NFL",
"ref": "/seasons/108075"
},
"eventStatusType": "Finished",
"locality": {
"id": 140,
"name": "United States of America",
"ref": "/localities/140"
},
"timezone": {
"id": 34,
"name": "US/Eastern",
"ref": "/timezones/34"
},
"venue": {
"id": 3455,
"name": "Levi's Stadium",
"ref": "/venues/3455"
},
"sport": {
"id": 17,
"name": "American Football",
"ref": "/sports/17"
},
"competition": {
"id": 296,
"name": "NFL",
"ref": "/competitions/296"
},
"round": {
"id": 984677,
"name": "Divisional Playoffs",
"ref": "/rounds/984677"
},
"genderType": "Male",
"homeCompetitor": {
"id": 106530,
"name": "San Francisco 49ers",
"competitorType": "Team",
"ref": "/competitors/Teams/106530"
},
"competitors": [
{
"metadataProperties": [
{
"name": "ShortName",
"value": "49ers",
"isDeleted": false
},
{
"name": "FullDescription",
"value": "San Francisco 49ers",
"isDeleted": false
}
],
"id": 106530,
"name": "San Francisco 49ers",
"competitorType": "Team",
"ref": "/competitors/Teams/106530"
},
{
"metadataProperties": [
{
"name": "ShortName",
"value": "Cowboys",
"isDeleted": false
},
{
"name": "FullDescription",
"value": "Dallas Cowboys",
"isDeleted": false
}
],
"id": 96760,
"name": "Dallas Cowboys",
"competitorType": "Team",
"ref": "/competitors/Teams/96760"
}
],
"eventType": "Match",
"metadataProperties": [
{
"name": "OvertimePeriodDuration",
"value": "15",
"isDeleted": false
},
{
"name": "HasLineups",
"value": "yes",
"isDeleted": false
}
],
"id": 9809943,
"createdOn": "2022-11-14T09:32:50Z",
"modifiedOn": "2023-01-23T03:30:02Z",
"updatesCount": 6
}
],
"self": "/fixtures/?filter=season.id%5Bequals%5D:108075&page=1&pageSize=5",
"next": "/fixtures/?filter=season.id%5Bequals%5D:108075&page=2&pageSize=5",
"first": "/fixtures/?filter=season.id%5Bequals%5D:108075&page=1&pageSize=5",
"last": "/fixtures/?filter=season.id%5Bequals%5D:108075&page=57&pageSize=5"
} |
Use Case “Ingest Data in Genius Sports”
Ingesting a fixture example
...
GET call to:
Code Block https://fixtures.api.geniussports.com/v2/ingestion/fixtures/{trackingRequestId}/statusResponse
Code Block { "status": 5, "trackingRequestId": "ec7b12d5-ffc1-4b0d-b301-c6e97e46a201", "requestCuratedValue": { "competition": { "sourceEntityId": "54645656546637", "status": 8, "name": "[Test] Final Competition", "id": "90001340" }, "sport": { "sourceEntityId": "6385e897-a774-4fdb-8fdd-87367d07c01c", "status": 8, "name": "Football", "id": "10" }, "fixture": { "sourceEntityId": "78681c6e-ca65-462d-b722-dc6f9842a49e", "status": 5, "matchingId": "6c2de3af-78bb-4ff4-99ee-d9cbedc78eec", "name": "The Giants vs The Small", "id": "91414163" }, "competitors": [ { "sourceEntityId": "4537745345", "status": 8, "name": "The Giants", "id": "90023531" }, { "sourceEntityId": "4545774sad5", "status": 8, "name": "The Small", "id": "90023532" } ], "season": { "sourceEntityId": "c53ba281-2bba-41d2-9738-b5420b500c84", "status": 8, "name": "2024 [Test] Final Competition", "id": "90005318" }, "fixtureLocality": { "status": 8, "name": "Test Region", "id": "3795038" } }
Use Case “Update Genius Sports data”
To Add a Person to a Team
...