Fixture API
Ekaterina Kozuseva (Deactivated)
Muhammad Shabraz
Raiko Pajur
Martin Kuks
Fixture API
Genius Sports Fixture API is a PULL API delivering a competition overview for all sports. Customers can search by sport, competition, season, competitors or fixture. Each fixture contains the start date for the match, competitors, competition the match falls under and the venue. Customers will need access to the Fixture API to link schedules and rosters to Match State data.
Online Documentation
Fixtures API Production: https://explorer.api.geniussports.com/Fixtures/v1/PRODPRM/public/index.html
Fixtures API UAT: https://explorer.api.geniussports.com/Fixtures/v1/UAT/public/index.html
Access to the Fixture API
To access the Fixture API you will need to use a username, password and api key supplied by Genius Sports. Please contact your integration manager for further details.
Steps for calling APIs:
Call the Auth API to sign in using the username and password:
https://api.geniussports.com/Auth-v1/PROD/login
Take the "IdToken" returned by the auth call and add it as the "Authorization" header in the api call you are going to make to FixturesAPI
Add your API key as the "x-api-key" header in the call to FixturesAPI also
Call FixturesAPI
Note: IdTokens last for 1 hour, after which you need to sign back in or call the refresh endpoint using the "RefreshToken" from the first Auth API call
Example Calls
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:
https://api.geniussports.com/Fixtures-v1/PRODPRM/sports
The return will be all sports covered by Genius Sports and their corresponding sportId. The sportId for American Football = 17
"id": 17,
"name": "American Football",
"sportproperty": {
"needsUnitsOfPlay": false,
"recreateEventsThreshold": 48
},
"updates": 0,
"deleted": false,
"lastUpdate": "2017-06-27 22:27:06",
"_links": {
"self": {
"href": "/v1/PRODPRM/sports/17"
Find the competition
Once you have the sportId you can search for the competition within that sport (i.e. NFL, NCAA, CFL, etc):
https://api.geniussports.com/Fixtures-v1/PRODPRM/sports/:{sportId}/competitions
"competitions": [
{
"id": 296,
"name": "NFL",
"sportId": 17,
"sportName": "American Football",
"gender": "male",
"competitionproperty": {
"usesTBDTeams": true,
"competitionType": "Tournament",
"isTour": false,
"isProtected": true,
"regionId": 140,
"defaultTimeZone": "US/Eastern",
"shortName": "NFL",
"longName": "NFL",
"sponsorName": "NFL"
Find the season
https://api.geniussports.com/Fixtures-v1/PRODPRM/competitions/:{competitionId}/seasons
"id": 108075,
"name": "2022/2023 NFL",
"sportId": 17,
"sportName": "American Football",
"competitionId": 296,
"competitionName": "NFL",
"locked": "none",
"seasonproperty": {
"timezone": "Africa/Abidjan",
"endDate": "2023-02-12 00:00:00",
"startDate": "2022-09-09 00:20:00",
"longName": "2022/2023 NFL",
"fullDescription": "2022/2023 NFL",
"shortName": "2022/2023 NFL",
"sponsorName": "2022/2023 NFL"
Find the fixture
https://api.geniussports.com/Fixtures-v1/PRODPRM/seasons/:{seasonId}/fixtures
Below is one example fixture from season = 108075 (2022/23 NFL). As you can see, each fixture has the competitors, round, date/time, status and venue.
"fixtures": [
{
"id": 9249365,
"sportId": 17,
"name": "Los Angeles Rams v Buffalo Bills",
"sportName": "American Football",
"competitionId": "296",
"competitionName": "NFL",
"seasonId": 108075,
"seasonName": "2022/2023 NFL",
"roundId": 809216,
"roundName": "Week 1",
"startDate": "2022-09-09 00:20:00",
"statusType": "scheduled",
"type": "Match",
"fixturecompetitors": [
{
"id": 21697213,
"number": 1,
"fixturecompetitorproperty": {},
"updates": 0,
"deleted": false,
"lastUpdate": "2022-05-13 03:57:41",
"_links": {
"self": {
"href": "/v1/PRODPRM/fixtures/9249365"
}
},
"competitor": {
"id": 107844,
"name": "Los Angeles Rams",
"sportId": 17,
"gender": "male",
"updates": 1,
"deleted": false,
"lastUpdate": "2021-06-24 10:47:14",
"_links": {
"self": {
"href": "/v1/PRODPRM/competitors/107844"
}
},
"type": "team",
"teamproperty": {
"isProtected": "yes",
"shortName": "Rams",
"fullDescription": "Los Angeles Rams"
},
"playerproperty": {}
}
},
{
"id": 21697214,
"number": 2,
"fixturecompetitorproperty": {},
"updates": 0,
"deleted": false,
"lastUpdate": "2022-05-13 03:57:41",
"_links": {
"self": {
"href": "/v1/PRODPRM/fixtures/9249365"
}
},
"competitor": {
"id": 112554,
"name": "Buffalo Bills",
"sportId": 17,
"gender": "male",
"updates": 1,
"deleted": false,
"lastUpdate": "2021-06-24 10:39:59",
"_links": {
"self": {
"href": "/v1/PRODPRM/competitors/112554"
}
},
"type": "team",
"teamproperty": {
"isProtected": "yes",
"shortName": "Bills",
"fullDescription": "Buffalo Bills"
},
"playerproperty": {}
}
}
],
"venue": {
"id": 10602,
"name": "SoFi Stadium",
"regionId": 140,
"venueType": "Stadium",
"venueproperty": {
"latitude": "33.95345000000",
"longitude": "-118.3392000000",
"capacity": "70240",
"surface": "Artificial Turf",
"city": "Inglewood"
},
"updates": 0,
"deleted": false,
"lastUpdate": "2020-09-09 12:24:50",
"_links": {
"self": {
"href": "/v1/PRODPRM/venues/10602"
}
}
},
"fixtureproperty": {
"round": "1",
"hasLineups": true,
"timezone": "US/Eastern"
},
"updates": 1,
"deleted": false,
"lastUpdate": "2022-05-13 04:03:28",
"_links": {
"self": {
"href": "/v1/PRODPRM/fixtures/9249365"
Find the roster
Each fixture has a list of competitors and participants. For the NFL, a competitor is the team and participant is a player within the team. Customers need to pull rosters from the Fixture API in order to link playerId to player names, etc. In Genius Sports match state feeds only playerId is sent. Search for rosters by competitor (team). Example: Dallas Cowboys, competitorId = 96760
https://api.geniussports.com/Fixtures-v1/PRODPRM/contracts/:{competitorId}
"contracts": [
{
"id": 1595409,
"shirtNumber": "77",
"type": "Plays For",
"active": true,
"role": "",
"dateFrom": "2011-10-18",
"dateTo": "2050-01-01",
"competitor": {
"id": 578674,
"name": "Smith, Tyron",
"sportId": 17,
"gender": "male",
"updates": 0,
"deleted": false,
"lastUpdate": "2017-06-27 22:35:09",
"_links": {
"self": {
"href": "/v1/PRODPRM/competitors/578674"
}
},
"type": "athlete",
"teamproperty": {},
"playerproperty": {
"isProtected": "yes",
"status": "active",
"firstName": "Tyron",
"lastName": "Smith",
"shortName": "Smith"
}
},
"updates": 2,
"deleted": false,
"lastUpdate": "2021-07-08 13:10:46",
"_links": {
"self": {
"href": "/v1/PRODPRM/contracts/96760"
}
}
},
{
"id": 1646826,
"shirtNumber": "90",
"type": "Plays For",
"active": true,
"role": "",
"dateFrom": "2014-09-04",
"dateTo": "2050-01-01",
"competitor": {
"id": 796702,
"name": "Lawrence, D",
"sportId": 17,
"gender": "male",
"updates": 0,
"deleted": false,
"lastUpdate": "2017-06-27 22:37:19",
"_links": {
"self": {
"href": "/v1/PRODPRM/competitors/796702"
}
},
"type": "athlete",
"teamproperty": {},
"playerproperty": {
"isProtected": "yes",
"status": "active",
"firstName": "DeMarcus",
"lastName": "Lawrence",
"shortName": "Lawrence"
}
},
"updates": 2,
"deleted": false,
"lastUpdate": "2021-07-08 12:21:54",
"_links": {
"self": {
"href": "/v1/PRODPRM/contracts/96760"
}
}
The above code examples will get you started on using the Fixture API. There are more options for information available and is constantly updated throughout the year. You can find more information on that from the Online documentation section.
Limits on API Requests
The number of requests to the API is restricted to a maximum of 1 billion requests per month per user. The limit resets on the first day of the month.