Genius Sports Sports API
The Sports API from Genius Sports — 2 operation(s) for sports.
OpenAPI Specification
swagger: '2.0'
info:
description: 'This is Genius Sports Services Fixture API.<h3>Changelog resume</h3><ul> <li>2.0.261 - Ability to filter by WELL-KNOWN external system identifiers e.g optaId, vesselId, fibaId, etc.</li> <li>2.0.196 - Added the ability to retrieve deleted fixtures</li> <li>2.0.193 - Expose outright fixtures with an extra query param (eventTypes) on GET and (eventType) on GetById for fixtures.</li> <li>2.0.107 - Made fixtures round optional for POST and PUT.</li></ul><h3>Authentication</h3><p>You need to provide two tokens in every API call. The access_token for Auth0 client AND your API key</p><ul> <li> In order to get Auth0 client and API-KEY contact the SBOT team. </li> <li>Once you have the client you can make a request to Auth0 to get a token by: <code> curl --request POST --url https://{env or nothing for prod}.auth.geniussports.com/oauth/token --header ''content-type: application/json'' --data ''{''client_id'':''4Ew9c8DX58O1i0zsrTW9DlLSlDg9Rrt7'',''client_secret'':''client-secret'',''audience'':''https://api.geniussports.com'',''grant_type'':''client_credentials''}'' </code> </li> <li> Once you the get the response you would need to take the value from the ''access_token'' property. At this point you are ready to get started! </li> <li> <ul style=''line-height:150%''> <li> Use the sports/10 call to retrieve Football (sport ID = 10) <ul> <li><code>curl https://{env or nothing for prod}fixtures.api.geniussports.com/v2/sports?filter=id[equals]:10 -H ''Content-Type: application/json'' -H ''x-api-key: YOUR_API_KEY'' -H ''Authorization: Bearer YOUR_ACCESS_TOKEN''</code> </li> </ul> </li> </ul> </li></ul><h3> What is new in Fixtures API v2.</h3><ul> <li>Consistent pagination with up to 200 items per page</li> <li>Consistent response using <a href=''https://en.wikipedia.org/wiki/HATEOAS'' target=''_blank''>HATEOAS</a> model wrapper (when listing items)</li> </li> <li>Sorting by specific field(s) (see each endpoint details for fore info, about which fields you can sort by) <ul> <li>in order to sort just pass <strong>''sortBy'' query param</strong>, example: <strong>sortBy=id</strong> </li> <li>then by sorting, example: <strong> sortBy=id,name</strong></li> <li>sort by descending: example: <strong> sortBy=id:desc,name</strong></li> </ul> </li> <li>Powerful filter by specific field (see each endpoint details for fore info, about which fields you can filter by) <ul> <li>in order to filter just pass <strong>''filter'' query param</strong>, example: <strong>filter=id[equals]:1</strong> </li> <li>multiple IDs filtering, example: <strong> filter=id[in]:1,2,3</strong></li> <li>Filter stacking (separate them with <strong>~</strong>), example: <strong> filter=id[in]:1,2,3~sportId[in]:1,2,3,4,5</strong></li> <li>different filter comparators: equals, in, gte, lte, contains, startsWith, notequals, nin: <strong> <ul> <li>filter=id[equals]:1 - Equals comparator works with all data type</li> <li>filter=id[notequals]:1 - Not Equals comparator works with all data type</li> <li>filter=id[in]:1,2,3 - In comparator works only with integer and decimal values</li> <li>filter=id[nin]:1,2,3 - NIN comparator works only with integer and decimal values</li> <li>filter=startDate[gte]:2021-07-28~startDate[lte]:2021-07-29 - duplications of filter property allowed only in this ''range'' case</li> <li>filter=name[contains]:test</li> <li>filter=name[startsWith]:test</li> <li>filter=cityName[equals]:null</li> <li>filter=cityName[notequals]:null</li> </ul> </strong> </li> <li>Filter by external id. Filter works only the Fixtures system has external provider and have explicitly allowed persisting external ids fir tat source. example: <strong> filter=externalIds.optaId[equals]:12345</strong></li> </ul> </li> <li>Imporoved and consistent structure of the API endpoints <ul> <li>Each endpoint (which needs) from the hierarchy has exactly 2 endpoints:</li> <ul> <li>One for listing multiple items - the filtering sorting are implemented by query params</li> <li>One for single item by id</li> </ul> </ul> </li> <li>No deleted fixtures by default</li> <li>Does not use SpoCoSy database (Party), but the Proposal API database (therefore there is <strong> Eventual consistency</strong>, and not everything is available right away)</li></ul><h3>Fixture Tree Structure</h3><ul style=''line-height:130%''> <li>organisations</li> <li>venue</li> <li>locality</li> <li>sports</li> <ul> <li>competitions</li> <ul> <li>seasons</li> <ul> <li>rounds (competitionPhase)</li> <ul> <li>fixture</li> <ul> <li>fixturecompetitors</li> <ul> <li>competitor (team, player, doubles, horse, etc) </li> </ul> </ul> </ul> </ul> </ul> </ul></ul><h3>Examples</h3><h4>I am interested in round 2 fixtures for the English Premier League</h4><ul style=''line-height:130%''> <li>Use sports call to retrieve the relevant sport ID - in this case ID 10 for Football</li> <li><code>curl https://ci.fixtures.api.geniussports.com/v2/sports -H ''Content-Type: application/json'' -H ''x-api-key: YOUR_API_KEY'' -H ''Authorization: Bearer YOUR_ID_TOKEN''</code> </li> <li>Use competitions call to see competitions for your sport - in this case ID 36 for ''England Premier League''</li> <li><code>curl https://ci.fixtures.api.geniussports.com/v2/competitions?filter=sportId[equals]:10~name[contains]:Premier -H ''Content-Type: application/json'' -H ''x-api-key: YOUR_API_KEY'' -H ''Authorization: Bearer YOUR_ID_TOKEN''</code> </li> <li>Use seasons call to see seasons for your competition - in this case you will see the 2017/2018 season as ID 64525</li> <li><code>curl https://ci.fixtures.api.geniussports.com/v2/seasons?filter=competitionId[equals]:36 -H ''Content-Type: application/json'' -H ''x-api-key: YOUR_API_KEY'' -H ''Authorization: Bearer YOUR_ID_TOKEN''</code> </li> <li>Use rounds call to see rounds for your season - Find Round 2 with ID 338088</li> <li><code>curl https://ci.fixtures.api.geniussports.com/v2/rounds?filter=seasonId[equals]:64525 -H ''Content-Type: application/json'' -H ''x-api-key: YOUR_API_KEY'' -H ''Authorization: Bearer YOUR_ID_TOKEN''</code> </li> <li>Use fixtures call to get all fixtures we have for Round 2</li> <li><code>curl https://ci.fixtures.api.geniussports.com/v2/fixtures?filter=roundId[equals]:338088 -H ''Content-Type: application/json'' -H ''x-api-key: YOUR_API_KEY'' -H ''Authorization: Bearer YOUR_ID_TOKEN''</code> </li></ul><br><h4>I am interested in Arsenal and their players</h4><ul style=''line-height:130%''> <li>You can re-use the 2017/2018 EPL season ID from the example above, ID 64525 to get Season Details</li> <li><code>curl https://ci.fixtures.api.geniussports.com/v2/seasons/64525 - ''Content-Type: application/json'' -H ''x-api-key: YOUR_API_KEY'' -H ''Authorization: Bearer YOUR_ID_TOKEN''</code> </li> <li>Find Arsenal in the response with competitor ID 10025 and use this ID to get all Arsenal contracts</li> <li><code>curl https://ci.fixtures.api.geniussports.com/v2/competitors/teams/10025 -H ''Content-Type: application/json'' -H ''x-api-key: YOUR_API_KEY'' -H ''Authorization: Bearer YOUR_ID_TOKEN''</code> </li></ul>'
version: 2.0.280
title: Fixtures-v2 Competitions Sports API
contact:
email: sbonboarding@geniussports.com
license:
name: Apache 2.0
url: http://www.apache.org/licenses/LICENSE-2.0.html
host: fixtures.api.geniussports.com
basePath: /v2
schemes:
- https
tags:
- name: Sports
paths:
/sports:
options:
consumes:
- application/json
produces:
- application/json
responses:
'200':
description: 200 response
schema:
$ref: '#/definitions/Empty'
headers:
Access-Control-Allow-Origin:
type: string
Access-Control-Allow-Methods:
type: string
Access-Control-Allow-Headers:
type: string
tags:
- Sports
get:
tags:
- Sports
summary: Retrieve sports by ID/s. MAX 200 per page.
description: Returns sports wrapped inside a HATEOAS model
produces:
- application/json
parameters:
- name: page
in: query
description: The number of page to be returned. The default value is 1.
required: false
type: string
- name: pageSize
in: query
description: The size of the page to be returned. The default value is 10.
required: false
type: string
- name: sortBy
in: query
description: 'The field to ''order by'' by. Descending ordering also allowed. Fields to order by for this endpoint: (id, name)'
required: false
type: string
- name: x-api-key
in: header
required: true
type: string
- name: filter
in: query
description: 'The field to ''filter'' by. Check main description for filter comparators. Fields to filter by for this endpoint: (id, name)'
required: false
type: string
responses:
'200':
description: successful operation
schema:
$ref: '#/definitions/SportResponseModelHATEOASReponseModel'
headers:
Access-Control-Allow-Origin:
type: string
'520':
description: Unknown error
schema:
$ref: '#/definitions/ErrorModel'
'400':
description: Bad request
schema:
$ref: '#/definitions/BadRequestModel'
'500':
description: Internal Server Error
schema:
$ref: '#/definitions/ErrorModel'
'401':
description: Unauthorized
schema:
$ref: '#/definitions/ErrorModel'
'413':
description: Payload Too Large
schema:
$ref: '#/definitions/ErrorModel'
'403':
description: Forbidden
schema:
$ref: '#/definitions/ErrorModel'
'415':
description: Unsupported Media Type
schema:
$ref: '#/definitions/ErrorModel'
'404':
description: Not found
schema:
$ref: '#/definitions/ErrorModel'
'504':
description: Gateway Timeout
schema:
$ref: '#/definitions/ErrorModel'
'429':
description: Too Many Requests OR Limit Exceeded - On reason = Too Many requests one should re-try, for Limit Exceeded that does not help you
schema:
$ref: '#/definitions/ErrorModel'
security:
- Auth0: []
- api_key: []
/sports/{id}/{entityType}/metadata:
options:
consumes:
- application/json
produces:
- application/json
parameters:
- name: entityType
in: path
required: true
type: string
- name: id
in: path
required: true
type: string
responses:
'200':
description: 200 response
schema:
$ref: '#/definitions/Empty'
headers:
Access-Control-Allow-Origin:
type: string
Access-Control-Allow-Methods:
type: string
Access-Control-Allow-Headers:
type: string
tags:
- Sports
get:
tags:
- Sports
summary: Retrieve allowed properties per entity type name and per sport.
description: Retrieve allowed properties per entity type name and per sport.
produces:
- application/json
parameters:
- name: entityType
in: path
description: 'Entity type is the name of the entity for which the allowed properties will be retrieved. Entity types: competition, competitor, contract, fixture, round, season, venue, fixtureperson, player, team'
required: true
type: string
- name: x-api-key
in: header
required: true
type: string
- name: id
in: path
description: The sport for which the allowed properties will be retrieved.
required: true
type: string
responses:
'200':
description: successful operation
schema:
$ref: '#/definitions/ArrayOfMetadataPropertyTypesResponseModel'
headers:
Access-Control-Allow-Origin:
type: string
'520':
description: Unknown error
schema:
$ref: '#/definitions/ErrorModel'
'400':
description: Bad request
schema:
$ref: '#/definitions/BadRequestModel'
'500':
description: Internal Server Error
schema:
$ref: '#/definitions/ErrorModel'
'401':
description: Unauthorized
schema:
$ref: '#/definitions/ErrorModel'
'413':
description: Payload Too Large
schema:
$ref: '#/definitions/ErrorModel'
'403':
description: Forbidden
schema:
$ref: '#/definitions/ErrorModel'
'415':
description: Unsupported Media Type
schema:
$ref: '#/definitions/ErrorModel'
'404':
description: Not found
schema:
$ref: '#/definitions/ErrorModel'
'504':
description: Gateway Timeout
schema:
$ref: '#/definitions/ErrorModel'
'429':
description: Too Many Requests OR Limit Exceeded - On reason = Too Many requests one should re-try, for Limit Exceeded that does not help you
schema:
$ref: '#/definitions/ErrorModel'
security:
- Auth0: []
- api_key: []
definitions:
BadRequestModel:
type: object
properties:
messages:
type: array
items:
type: string
Error:
type: object
required:
- domain
- message
- reason
properties:
reason:
type: string
domain:
type: string
locationType:
type: string
location:
type: string
message:
type: string
Empty:
type: object
SportResponseModelHATEOASReponseModel:
type: object
properties:
page:
type: integer
format: int32
pageSize:
type: integer
format: int32
totalItems:
type: integer
format: int64
items:
type: array
items:
$ref: '#/definitions/SportResponseModel'
self:
type: string
previous:
type: string
next:
type: string
first:
type: string
last:
type: string
ArrayOfMetadataPropertyTypesResponseModel:
type: array
items:
$ref: '#/definitions/MetadataPropertyTypesResponseModel'
ErrorModel:
type: object
properties:
code:
type: integer
format: int32
message:
type: string
error:
$ref: '#/definitions/Error'
MetadataPropertyTypesResponseModel:
type: object
required:
- allowNonPredefinedValues
- id
- isRequired
- name
properties:
id:
type: integer
format: int64
title: Id of the property type
name:
type: string
title: Name of the property type
allowNonPredefinedValues:
type: boolean
title: True or false value. Defines whether you can use any value or you should use value from the list below.
isRequired:
type: boolean
description: Is property required for the specific entity for the specific sport
title: Is property required for the specific entity for the specific sport
values:
type: array
items:
type: string
SportResponseModel:
type: object
required:
- allowsDoubles
- allowsPlayers
- createdOn
- id
- name
- updatesCount
properties:
id:
type: integer
format: int64
title: Id of the sport
name:
type: string
title: Name of the sport
allowsPlayers:
type: boolean
description: Whether players can be proposed for the specific sport. True when Players can be proposed
title: Can Players be proposed for the specific sport
allowsDoubles:
type: boolean
description: Whether players can be proposed for the specific sport. True when Doubles can be proposed
title: Can Doubles be proposed for the specific sport
maxNumberOfCompetitorsInFixture:
type: integer
format: int32
description: The maximum number of competitors which can take part in a fixture for the specific sport. The minimum is 2. The maximum depends on this number. The maximum is inclusive e.g. number of competitors <= maxNumberOfCompetitorsInFixture. When maxNumberOfCompetitorsInFixture is set to null this means that there is no upper limit of the number of competitors which can take part in the fixtures for the specific sport.
title: The maximum number of competitors which can take part in a fixture for the specific sport
createdOn:
type: string
format: date-time
title: The date on which the sport was created
modifiedOn:
type: string
format: date-time
title: The date on which the sport was modified
updatesCount:
type: integer
format: int32
title: The number of updates made to the sport
securityDefinitions:
Auth0:
type: apiKey
name: Authorization
in: header
x-amazon-apigateway-authtype: oauth2
api_key:
type: apiKey
name: x-api-key
in: header
x-amazon-apigateway-security-policy: TLS_1_0