Genius Sports competitors/players API
Groups the operations related to competitors of type Player
Work with this as data
Every API here is available over the APIs.io API and to AI agents over MCP.
MCP server
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
Tools for apis
7 MCP tools reach this
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.
Call it yourself
curl for this page
This API
curl "https://apis.io/api/v1/apis/genius-sports-competitors-players-api"
All apis
curl "https://apis.io/api/v1/apis?limit=25"Discovery needs no key. Ratings and market analysis are Pro.
Get an API key
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
OpenAPI Specification
openapi: 3.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 Competitors/players API
contact:
email: sbonboarding@geniussports.com
license:
name: Apache 2.0
url: http://www.apache.org/licenses/LICENSE-2.0.html
servers:
- url: https://fixtures.api.geniussports.com/v2
tags:
- name: competitors/players
description: Groups the operations related to competitors of type Player
paths:
/competitors/players:
get:
tags:
- competitors/players
summary: Retrieve competitors (players) by ID/s. MAX 200 per page.
description: Returns competitors (players) wrapped inside a HATEOAS model
parameters:
- name: page
in: query
description: The number of page to be returned. The default value is 1.
required: false
schema:
type: string
- name: pageSize
in: query
description: The size of the page to be returned. The default value is 10.
required: false
schema:
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, sportId, genderType, localityId, venueId, competitorStatusType)'
required: false
schema:
type: string
- name: x-api-key
in: header
required: true
schema:
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, sportId, genderType, localityId, venueId, competitorStatusType)'
required: false
schema:
type: string
responses:
'200':
description: successful operation
headers:
Access-Control-Allow-Origin:
schema:
type: string
content:
application/json:
schema:
$ref: '#/components/schemas/PlayerCompetitorResponseModelHATEOASReponseModel'
'520':
description: Unknown error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorModel'
'400':
description: Bad request
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequestModel'
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorModel'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorModel'
'413':
description: Payload Too Large
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorModel'
'403':
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorModel'
'415':
description: Unsupported Media Type
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorModel'
'404':
description: Not found
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorModel'
'504':
description: Gateway Timeout
content:
application/json:
schema:
$ref: '#/components/schemas/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
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorModel'
security:
- Auth0: []
- api_key: []
post:
tags:
- competitors/players
summary: Create new player
parameters:
- name: x-api-key
in: header
required: true
schema:
type: string
- name: gs-fixtures-api-sub-source
in: header
description: Sub Source Name
required: false
schema:
type: string
responses:
'520':
description: Unknown error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorModel'
'201':
description: Created
headers:
gs-duplicate-entity-replaced:
description: Returned when a duplicate entity has been replaced. Value is the 'duplicateEntityId' and the 'originalEntityId'
schema:
type: string
content:
application/json:
schema:
$ref: '#/components/schemas/PlayerCompetitorResponseModel'
'400':
description: Bad request
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequestModel'
'202':
description: Accepted
content:
application/json:
schema:
$ref: '#/components/schemas/AcceptedModel'
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorModel'
'404':
description: Not found
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorModel'
'504':
description: Gateway Timeout
content:
application/json:
schema:
$ref: '#/components/schemas/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
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorModel'
'409':
description: Conflict, see the response message or the 'geniussports-conflict-id' header to see the ID of the conflict!
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorDuplicateModel'
security:
- Auth0: []
- api_key: []
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/CreatePlayerCompetitor'
required: true
put:
tags:
- competitors/players
summary: Update existing player
parameters:
- name: x-api-key
in: header
required: true
schema:
type: string
- name: gs-fixtures-api-sub-source
in: header
description: Sub Source Name
required: false
schema:
type: string
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/PlayerCompetitorResponseModel'
'520':
description: Unknown error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorModel'
'400':
description: Bad request
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequestModel'
'202':
description: Accepted
content:
application/json:
schema:
$ref: '#/components/schemas/AcceptedModel'
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorModel'
'404':
description: Not found
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorModel'
'504':
description: Gateway Timeout
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorModel'
'409':
description: Conflict, see the response message or the 'geniussports-conflict-id' header to see the ID of the conflict!
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorDuplicateModel'
security:
- Auth0: []
- api_key: []
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/UpdatePlayerCompetitor'
required: true
/competitors/players/{id}:
get:
tags:
- competitors/players
summary: Retrieve competitors (players) details by ID.
description: Returns competitors (players) details including sport specific details (metadata properties)
parameters:
- name: x-api-key
in: header
required: true
schema:
type: string
- name: id
in: path
description: Single competitors (players) ID to return details for
required: true
schema:
type: string
responses:
'200':
description: successful operation
headers:
Access-Control-Allow-Origin:
schema:
type: string
content:
application/json:
schema:
$ref: '#/components/schemas/PlayerCompetitorResponseModel'
'520':
description: Unknown error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorModel'
'400':
description: Bad request
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequestModel'
'202':
description: Accepted
content:
application/json:
schema:
$ref: '#/components/schemas/AcceptedModel'
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorModel'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorModel'
'413':
description: Payload Too Large
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorModel'
'403':
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorModel'
'415':
description: Unsupported Media Type
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorModel'
'404':
description: Not found
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorModel'
'504':
description: Gateway Timeout
content:
application/json:
schema:
$ref: '#/components/schemas/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
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorModel'
security:
- Auth0: []
- api_key: []
/competitors/players/{id}/rounds:
get:
tags:
- competitors/players
summary: Retrieve rounds in which the Player will take part by Team ID/s. MAX 200 per page.
description: Returns the rounds in which the player will take part by GSS Player Id in the path, wrapped inside a HATEOAS model
parameters:
- name: page
in: query
description: The number of page to be returned. The default value is 1.
required: false
schema:
type: string
- name: pageSize
in: query
description: The size of the page to be returned. The default value is 10.
required: false
schema:
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
schema:
type: string
- name: x-api-key
in: header
required: true
schema:
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, isactive (default = true))'
required: false
schema:
type: string
- name: id
in: path
description: Single competitors (players) ID to return details for
required: true
schema:
type: string
responses:
'200':
description: successful operation
headers:
Access-Control-Allow-Origin:
schema:
type: string
content:
application/json:
schema:
$ref: '#/components/schemas/CompetitorRoundsResponseModelHATEOASReponseModel'
'520':
description: Unknown error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorModel'
'400':
description: Bad request
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequestModel'
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorModel'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorModel'
'413':
description: Payload Too Large
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorModel'
'403':
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorModel'
'415':
description: Unsupported Media Type
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorModel'
'404':
description: Not found
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorModel'
'504':
description: Gateway Timeout
content:
application/json:
schema:
$ref: '#/components/schemas/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
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorModel'
security:
- Auth0: []
- api_key: []
/competitors/players/{id}/seasons:
get:
tags:
- competitors/players
summary: Retrieve seasons in which the Player will take part by Team ID/s. MAX 200 per page.
description: Returns the seasons in which the player will take part by GSS Player Id in the path, wrapped inside a HATEOAS model
parameters:
- name: page
in: query
description: The number of page to be returned. The default value is 1.
required: false
schema:
type: string
- name: pageSize
in: query
description: The size of the page to be returned. The default value is 10.
required: false
schema:
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
schema:
type: string
- name: x-api-key
in: header
required: true
schema:
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, isactive (default = true))'
required: false
schema:
type: string
- name: id
in: path
description: Single competitors (players) ID to return details for
required: true
schema:
type: string
responses:
'200':
description: successful operation
headers:
Access-Control-Allow-Origin:
schema:
type: string
content:
application/json:
schema:
$ref: '#/components/schemas/CompetitorSeasonsResponseModelHATEOASReponseModel'
'520':
description: Unknown error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorModel'
'400':
description: Bad request
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequestModel'
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorModel'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorModel'
'413':
description: Payload Too Large
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorModel'
'403':
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorModel'
'415':
description: Unsupported Media Type
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorModel'
'404':
description: Not found
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorModel'
'504':
description: Gateway Timeout
content:
application/json:
schema:
$ref: '#/components/schemas/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
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorModel'
security:
- Auth0: []
- api_key: []
components:
schemas:
JsonbModelViewModel:
type: object
required:
- name
properties:
name:
type: string
description: Name of the property.
title: Property name
value:
type: string
description: Value of the property.
title: Property value
title: Create/Update Property Model
description: This model should be used to create or update single property value for specific property name for specific model.
CompetitorSeasonsResponseModelHATEOASReponseModel:
type: object
properties:
page:
type: integer
format: int32
pageSize:
type: integer
format: int32
totalItems:
type: integer
format: int64
items:
type: array
items:
$ref: '#/components/schemas/CompetitorSeasonsResponseModel'
self:
type: string
previous:
type: string
next:
type: string
first:
type: string
last:
type: string
JsonbModel:
type: object
properties:
name:
type: string
value:
type: string
isDeleted:
type: boolean
ErrorModel:
type: object
properties:
code:
type: integer
format: int32
message:
type: string
error:
$ref: '#/components/schemas/Error'
CompetitorStatusType:
type: integer
title: Competitor Status Type
format: int32
description: 'This property defines the possible status types which can be set as integer values. Each integer value is associated with relevant status type as follows: 0 - Active; 1 - Retired; 2 - Unattached.'
enum:
- '0'
- '1'
- '2'
BadRequestModel:
type: object
properties:
messages:
type: array
items:
type: string
CreatePersonViewModel:
type: object
required:
- firstName
- genderType
- lastName
- localityId
- useNickname
properties:
firstName:
type: string
description: The first name of the person
title: First Name
maxLength: 256
lastName:
type: string
description: The last name of the person
title: Last Name
maxLength: 256
nickName:
type: string
description: The nickname of the person
title: Nickname
maxLength: 128
useNickname:
type: boolean
description: Whether the nickname should be used instead of the name of the person when displaying the person. If the useNickname property is set to true nickname is required!
title: Is active
localityId:
type: integer
format: int64
description: Id of the country,virtual place, etc. of the person!
title: Locality Id
dateOfBirth:
type: string
format: date-time
description: The date of birth of the person
title: Date of birth
genderType:
$ref: '#/components/schemas/PersonGenderType'
sports:
type: array
description: Array of sport Ids to be added to the person.
title: Sports
items:
type: integer
description: Sports to which the person belongs to.
title: Sports
Error:
type: object
required:
- domain
- message
- reason
properties:
reason:
type: string
domain:
type: string
locationType:
type: string
location:
type: string
message:
type: string
UpdatePlayerCompetitor:
type: object
required:
- competitorStatusType
- id
properties:
metadataProperties:
type: array
items:
$ref: '#/components/schemas/JsonbModelViewModel'
id:
type: integer
format: int64
minimum: 1.0
competitorStatusType:
$ref: '#/components/schemas/CompetitorStatusType'
CompetitorRoundsResponseModelHATEOASReponseModel:
type: object
properties:
page:
type: integer
# --- truncated at 32 KB (38 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/genius-sports/refs/heads/main/openapi/genius-sports-competitors-players-api-openapi.yml