Genius Sports Persons API
The Persons API from Genius Sports — 5 operation(s) for persons.
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 Persons 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: Persons
paths:
/persons:
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:
- Persons
get:
tags:
- Persons
summary: Retrieve persons by ID/s. MAX 200 per page. (Not available yet)
description: Returns persons 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/PersonsListResponseModelHATEOASReponseModel'
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: []
post:
tags:
- Persons
summary: Create new person
consumes:
- application/json
produces:
- application/json
parameters:
- name: x-api-key
in: header
required: true
type: string
- name: gs-fixtures-api-sub-source
in: header
description: Sub Source Name
required: false
type: string
- in: body
name: CreatePersonViewModel
required: true
schema:
$ref: '#/definitions/CreatePersonViewModel'
responses:
'520':
description: Unknown error
schema:
$ref: '#/definitions/ErrorModel'
'201':
description: Created
schema:
$ref: '#/definitions/PersonResponseModel'
'400':
description: Bad request
schema:
$ref: '#/definitions/BadRequestModel'
'202':
description: Accepted
schema:
$ref: '#/definitions/AcceptedModel'
'500':
description: Internal Server Error
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'
'409':
description: Conflict, see the response message or the 'geniussports-conflict-id' header to see the ID of the conflict!
schema:
$ref: '#/definitions/ErrorDuplicateModel'
security:
- Auth0: []
- api_key: []
put:
tags:
- Persons
summary: Update existing person
consumes:
- application/json
produces:
- application/json
parameters:
- name: x-api-key
in: header
required: true
type: string
- name: gs-fixtures-api-sub-source
in: header
description: Sub Source Name
required: false
type: string
- in: body
name: UpdatePersonViewModel
required: true
schema:
$ref: '#/definitions/UpdatePersonViewModel'
responses:
'200':
description: Success
schema:
$ref: '#/definitions/PersonResponseModel'
'520':
description: Unknown error
schema:
$ref: '#/definitions/ErrorModel'
'400':
description: Bad request
schema:
$ref: '#/definitions/BadRequestModel'
'202':
description: Accepted
schema:
$ref: '#/definitions/AcceptedModel'
'500':
description: Internal Server Error
schema:
$ref: '#/definitions/ErrorModel'
'404':
description: Not found
schema:
$ref: '#/definitions/ErrorModel'
'504':
description: Gateway Timeout
schema:
$ref: '#/definitions/ErrorModel'
'409':
description: Conflict, see the response message or the 'geniussports-conflict-id' header to see the ID of the conflict!
schema:
$ref: '#/definitions/ErrorDuplicateModel'
security:
- Auth0: []
- api_key: []
/persons/coaches:
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:
- Persons
get:
tags:
- Persons
summary: Retrieve persons which were in the past or are currently coaches by ID/s. MAX 200 per page. (Not available yet)
description: Returns persons 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/PersonsListResponseModelHATEOASReponseModel'
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: []
/persons/{id}:
options:
consumes:
- application/json
produces:
- application/json
parameters:
- 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:
- Persons
get:
tags:
- Persons
summary: Retrieve persons details by ID. (not available yet)
description: Returns persons details including sport specific details (metadata properties)
produces:
- application/json
parameters:
- name: x-api-key
in: header
required: true
type: string
- name: id
in: path
description: Single person ID to return details for
required: true
type: string
responses:
'200':
description: successful operation
schema:
$ref: '#/definitions/PersonResponseModel'
headers:
Access-Control-Allow-Origin:
type: string
'520':
description: Unknown error
schema:
$ref: '#/definitions/ErrorModel'
'400':
description: Bad request
schema:
$ref: '#/definitions/BadRequestModel'
'202':
description: Accepted
schema:
$ref: '#/definitions/AcceptedModel'
'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: []
delete:
tags:
- Persons
summary: Delete existing person
produces:
- application/json
parameters:
- name: x-api-key
in: header
required: true
type: string
- name: gs-fixtures-api-sub-source
in: header
description: Sub Source Name
required: false
type: string
- name: id
in: path
required: true
type: string
responses:
'200':
description: Success
'520':
description: Unknown error
schema:
$ref: '#/definitions/ErrorModel'
'400':
description: Bad request
schema:
$ref: '#/definitions/BadRequestModel'
'202':
description: Accepted
schema:
$ref: '#/definitions/AcceptedModel'
'500':
description: Internal Server Error
schema:
$ref: '#/definitions/ErrorModel'
'404':
description: Not found
schema:
$ref: '#/definitions/ErrorModel'
'504':
description: Gateway Timeout
schema:
$ref: '#/definitions/ErrorModel'
security:
- Auth0: []
- api_key: []
/persons/{id}/contracts:
options:
consumes:
- application/json
produces:
- application/json
parameters:
- 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:
- Persons
/persons/{id}/officials:
options:
consumes:
- application/json
produces:
- application/json
parameters:
- 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:
- Persons
get:
tags:
- Persons
summary: Retrieve person's officials by person ID. MAX 200 per page.
description: Returns person's officials 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.
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.
required: false
type: string
- name: id
in: path
description: Single person ID to return officials for
required: true
type: string
responses:
'200':
description: successful operation
schema:
$ref: '#/definitions/PersonOfficialResponseModelHATEOASReponseModel'
headers:
Access-Control-Allow-Origin:
type: string
'520':
description: Unknown error
schema:
$ref: '#/definitions/ErrorModel'
'400':
description: Bad request
schema:
$ref: '#/definitions/BadRequestModel'
'301':
description: redirect operation
headers:
Location:
type: string
'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
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: '#/definitions/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
ErrorDuplicateModel:
type: object
properties:
messages:
type: array
items:
type: string
geniusSportsConflictId:
type: string
description: This is the official genius sports ID, which you have conflict with.
JsonbModel:
type: object
properties:
name:
type: string
value:
type: string
isDeleted:
type: boolean
HALEmbededResponse:
type: object
required:
- id
- name
- ref
properties:
id:
type: integer
format: int64
name:
type: string
externalIds:
$ref: '#/definitions/ExternalIdsViewModel'
ref:
type: string
PersonsListResponseModelHATEOASReponseModel:
type: object
properties:
page:
type: integer
format: int32
pageSize:
type: integer
format: int32
totalItems:
type: integer
format: int64
items:
type: array
items:
$ref: '#/definitions/PersonResponseModel'
self:
type: string
previous:
type: string
next:
type: string
first:
type: string
last:
type: string
UpdatePersonViewModel:
type: object
required:
- firstName
- genderType
- id
- isActive
- 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:
description: 'This property defines the possible gender types which can be set as integer values. Each integer value is associated with relevant gender type as follows: 0 - Undefined; 1 - Male; 2 - Female; 3 - Mixed. It can only be updated if the person does not have active relations to the any competitor'
$ref: '#/definitions/PersonGenderType'
id:
type: integer
format: int64
description: The ID of the person.
title: Id
isActive:
type: boolean
description: Whether the person can be used as fixture official or as part of a competitor. Setting this to false will deactivate all relations of a person to fixtures as fixture official or to competitor as coach/player or any other type of relation between person and competitor. It will also prevent using the person in future competitor/ fixture relations
title: Is Active
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
ExternalIdsViewModel:
type: object
properties:
optaId:
type: string
optaLegacyId:
type: string
fibaId:
type: string
vesselId:
type: string
statsEngineId:
type: string
# --- truncated at 32 KB (35 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/genius-sports/refs/heads/main/openapi/genius-sports-persons-api-openapi.yml