swagger: '2.0'
info:
description: 'This is Genius Sports Services Fixture API.
Changelog resume
- 2.0.261 - Ability to filter by WELL-KNOWN external system identifiers e.g optaId, vesselId, fibaId, etc.
- 2.0.196 - Added the ability to retrieve deleted fixtures
- 2.0.193 - Expose outright fixtures with an extra query param (eventTypes) on GET and (eventType) on GetById for fixtures.
- 2.0.107 - Made fixtures round optional for POST and PUT.
Authentication
You need to provide two tokens in every API call. The access_token for Auth0 client AND your API key
- In order to get Auth0 client and API-KEY contact the SBOT team.
- Once you have the client you can make a request to Auth0 to get a token by:
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''}'' - 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!
-
- Use the sports/10 call to retrieve Football (sport ID = 10)
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''
What is new in Fixtures API v2.
- Consistent pagination with up to 200 items per page
- Consistent response using HATEOAS model wrapper (when listing items)
- Sorting by specific field(s) (see each endpoint details for fore info, about which fields you can sort by)
- in order to sort just pass ''sortBy'' query param, example: sortBy=id
- then by sorting, example: sortBy=id,name
- sort by descending: example: sortBy=id:desc,name
- Powerful filter by specific field (see each endpoint details for fore info, about which fields you can filter by)
- in order to filter just pass ''filter'' query param, example: filter=id[equals]:1
- multiple IDs filtering, example: filter=id[in]:1,2,3
- Filter stacking (separate them with ~), example: filter=id[in]:1,2,3~sportId[in]:1,2,3,4,5
- different filter comparators: equals, in, gte, lte, contains, startsWith, notequals, nin:
- filter=id[equals]:1 - Equals comparator works with all data type
- filter=id[notequals]:1 - Not Equals comparator works with all data type
- filter=id[in]:1,2,3 - In comparator works only with integer and decimal values
- filter=id[nin]:1,2,3 - NIN comparator works only with integer and decimal values
- filter=startDate[gte]:2021-07-28~startDate[lte]:2021-07-29 - duplications of filter property allowed only in this ''range'' case
- filter=name[contains]:test
- filter=name[startsWith]:test
- filter=cityName[equals]:null
- filter=cityName[notequals]:null
- Filter by external id. Filter works only the Fixtures system has external provider and have explicitly allowed persisting external ids fir tat source. example: filter=externalIds.optaId[equals]:12345
- Imporoved and consistent structure of the API endpoints
- Each endpoint (which needs) from the hierarchy has exactly 2 endpoints:
- One for listing multiple items - the filtering sorting are implemented by query params
- One for single item by id
- No deleted fixtures by default
- Does not use SpoCoSy database (Party), but the Proposal API database (therefore there is Eventual consistency, and not everything is available right away)
Fixture Tree Structure
- organisations
- venue
- locality
- sports
- competitions
- seasons
- rounds (competitionPhase)
- fixture
- fixturecompetitors
- competitor (team, player, doubles, horse, etc)
Examples
I am interested in round 2 fixtures for the English Premier League
- Use sports call to retrieve the relevant sport ID - in this case ID 10 for Football
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'' - Use competitions call to see competitions for your sport - in this case ID 36 for ''England Premier League''
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'' - Use seasons call to see seasons for your competition - in this case you will see the 2017/2018 season as ID 64525
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'' - Use rounds call to see rounds for your season - Find Round 2 with ID 338088
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'' - Use fixtures call to get all fixtures we have for Round 2
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''
I am interested in Arsenal and their players
- You can re-use the 2017/2018 EPL season ID from the example above, ID 64525 to get Season Details
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'' - Find Arsenal in the response with competitor ID 10025 and use this ID to get all Arsenal contracts
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''
'
version: 2.0.280
title: v2 Competitions Fixtures 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: Fixtures
paths:
/fixtures:
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:
- Fixtures
get:
tags:
- Fixtures
summary: Retrieve fixtures by ID/s. MAX 200 per page.
description: Returns fixtures wrapped inside a HATEOAS model
produces:
- application/json
parameters:
- name: pageSize
in: query
description: The size of the page to be returned. The default value is 10.
required: false
type: string
- name: x-api-key
in: header
required: true
type: string
- name: deleted
in: query
description: 'This field specifies whether to include deleted, not deleted, or both. Possible values: False, True, or All.'
required: false
type: string
- name: eventTypes
in: query
description: This field specifies the event type to be returned (Match, SeasonOutright, PartialOutright, AggregateEvent). By default, if not provided, 'Match' is returned. Multiple types can be combined in a single request, separated by commas.
required: false
type: string
- name: withCompetitors
in: query
description: This field specifies whether when set to true to return fixtures without any TBD competitors or false for all fixtures
required: false
type: string
- name: page
in: query
description: The number of page to be returned. The default value is 1.
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, roundId, seasonId, competitionId, sportId, eventStatusType, localityId, timezoneId, venueId, startDate)'
required: false
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, roundId, seasonId, competitionId, sportId, eventStatusType, localityId, timezoneId, venueId, startDate)'
required: false
type: string
responses:
'200':
description: successful operation
schema:
$ref: '#/definitions/FixtureResponseModelHATEOASReponseModel'
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:
x-gs-attr-oldnewentityidssmap:
type: string
description: 'oldId=newId separated by semicolon '';'' e.g.: 1=2;3=4;...'
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: []
post:
tags:
- Fixtures
summary: Create new fixture
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: CreateFixture
required: true
schema:
$ref: '#/definitions/CreateFixture'
responses:
'520':
description: Unknown error
schema:
$ref: '#/definitions/ErrorModel'
'201':
description: Created
schema:
$ref: '#/definitions/FixtureResponseModel'
headers:
gs-duplicate-entity-replaced:
type: string
description: Returned when a duplicate entity has been replaced. Value is the 'duplicateEntityId' and the 'originalEntityId'
'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:
- Fixtures
summary: Update existing fixture
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: UpdateFixture
required: true
schema:
$ref: '#/definitions/UpdateFixture'
responses:
'200':
description: Success
schema:
$ref: '#/definitions/FixtureResponseModel'
headers:
gs-duplicate-entity-replaced:
type: string
description: Returned when a duplicate entity has been replaced. Value is the 'duplicateEntityId' and the 'originalEntityId'
'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: []
patch:
tags:
- Fixtures
summary: Patch existing fixture
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: PatchFixture
required: true
schema:
$ref: '#/definitions/PatchFixture'
responses:
'200':
description: Success
schema:
$ref: '#/definitions/FixtureResponseModel'
headers:
gs-duplicate-entity-replaced:
type: string
description: Returned when a duplicate entity has been replaced. Value is the 'duplicateEntityId' and the 'originalEntityId'
'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: []
/fixtures/refdata:
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:
- Fixtures
get:
tags:
- Fixtures
summary: Retrieve fixtures refdata by filter. MAX 200 per page.
description: Returns fixtures refdata 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, roundId, seasonId, competitionId, sportId, eventStatusType, localityId, timezoneId, venueId, startDate)'
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, roundId, seasonId, competitionId, sportId, eventStatusType, localityId, timezoneId, venueId, startDate)'
required: false
type: string
responses:
'200':
description: successful operation
schema:
$ref: '#/definitions/FixtureRefdataResponseModelHATEOASReponseModel'
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:
x-gs-attr-oldnewentityidssmap:
type: string
description: 'oldId=newId separated by semicolon '';'' e.g.: 1=2;3=4;...'
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: []
/fixtures/{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:
- Fixtures
get:
tags:
- Fixtures
summary: Retrieve fixtures details by ID.
description: Returns fixtures details including sport specific details (metadata properties)
produces:
- application/json
parameters:
- name: x-api-key
in: header
required: true
type: string
- name: deleted
in: query
description: 'This field specifies whether to include deleted, not deleted, or both. Possible values: False, True, or All.'
required: false
type: string
- name: eventType
in: query
description: The field specifies the type of event to return (Match, SeasonOutright, PartialOutright, AggregateEvent). If not provided, the search defaults to fixtures of type 'Match'.
required: false
type: string
- name: id
in: path
description: Single fixtures ID to return details for
required: true
type: string
responses:
'200':
description: successful operation
schema:
$ref: '#/definitions/FixtureResponseModel'
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
'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:
- Fixtures
summary: Delete existing fixture
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: []
/fixtures/{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:
- Fixtures
/fixtures/{id}/lineups:
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:
- Fixtures
get:
tags:
- Fixtures
summary: 'Retrieve whole fixture''s lineups by fixture ID for both teams '
description: Lineup availability may vary depending on the sport and specific fixture. In certain sports, lineups are provided only for selected competitions only. When lineup data is not available, the API will return an empty response.
produces:
- application/json
parameters:
- name: x-api-key
in: header
required: true
type: string
- name: id
in: path
description: Single fixture ID to return lineups for
required: true
type: string
responses:
'200':
description: successful operation
schema:
$ref: '#/definitions/FixtureLineupsResponseModel'
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: []
/fixtures/{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:
- Fixtures
get:
tags:
- Fixtures
summary: Retrieve fixture's officials by fixture ID. MAX 200 per page.
description: Returns fixture'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 fixture ID to return officials for
required: true
type: string
responses:
'200':
description: successful operation
schema:
$ref: '#/definitions/FixtureOfficialResponseModelHATEOASReponseModel'
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: []
post:
tags:
- Fixtures
summary: Adds new official to the fixture
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
- name: id
in: path
description: Single fixture ID to create official for
required: true
type: string
- in: body
name: CreateFixtureOfficial
required: true
schema:
$ref: '#/definitions/CreateFixtureOfficial'
responses:
'520':
description: Unknown error
schema:
$ref: '#/definitions/ErrorModel'
'201':
description: Created
schema:
$ref: '#/definitions/FixtureOfficialResponseModel'
'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:
- Fixtures
summary: Update existing fixture official
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
- name: id
in: path
description: Single fixture ID to update official for
required: true
type: string
- in: body
name: CreateFixtureOfficial
required: true
schema:
$ref: '#/definitions/CreateFixtureOfficial'
responses:
'200':
description: Success
schema:
$ref: '#/definitions/FixtureOfficialResponseModel'
'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: []
/fixtures/{id}/officials/{personId}:
options:
consumes:
- application/json
produces:
- application/json
parameters:
- name: personId
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:
- Fixtures
delete:
tags:
- Fixtures
summary: Removes official added to fixture
produces:
- application/json
parameters:
- name: gs-fixtures-api-sub-source
in: header
description: Sub Source Name
required: false
type: string
- name: x-api-key
in: header
required: true
type: string
- name: id
in: path
required: true
type: string
- name: personId
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: []
definitions:
Error:
type: object
required:
- domain
- message
- reason
properties:
reason:
type: string
domain:
type: string
locationType:
type: string
location:
type: string
message:
type: string
CompetitorHALEmbededResponse:
type: object
required:
- competitorType
- id
- name
- ref
properties:
id:
type: integer
format: int64
name:
type: string
externalIds:
$ref: '#/definitions/ExternalIdsViewModel'
competitorType:
type: string
description: Team, Player, Horse, Jockey, HorseOwner, Dog, Breeder, DoublesPartnership, Other, TBD
ref:
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
PatchFixture:
type: object
required:
- id
properties:
id:
type: integer
format: int64
description: The ID of the fixture.
title: Id
startDate:
type: string
format: date-time
description: The start date of the fixture in UTC ISO-8601 format
title: Start Date
venueId:
type: integer
format: int64
description: The ID of the venue the fixture is played at.
title: Venue ID
roundId:
type: integer
format: int64
description: The ID of the round the fixture is for.
title: Round ID
metadataProperties:
type: array
description: In order to retrieve allowed metadata properties with their values execute get request on this path - /sports/{id}/competition/metadata
title: metadataProperties
items:
$ref: '#/definitions/JsonbModelViewModel'
externalIds:
$ref: '#/definitions/ExternalIdsViewModel'
title: Patch Fixture Model
description: This model should be used to propose a partial update/patch to a fixture.
FixtureRefdataFixture:
type: object
properties:
id:
type: string
externalIds:
$ref: '#/definitions/ExternalIdsViewModel'
startDate:
type: string
format: date-time
metadataProperties:
type: array
items:
$ref: '#/definitions/JsonbModel'
competitors:
type: array
items:
$ref: '#/definitions/FixtureRefdataCompetitor'
season:
$ref: '#/definitions/FixtureRefdataSeason'
venue:
$ref: '#/definitions/FixtureRefdataVenue'
competition:
$ref: '#/definitions/FixtureRefdataCompetition'
Empty:
type: object
FixtureRefdataLineupPlayer:
type: object
properties:
id:
type: string
externalIds:
$ref: '#/definitions/ExternalIdsViewModel'
order:
type: integer
format: int32
isStarter:
type: boolean
name:
type: string
shirtNumber:
type: string
position:
type: string
formationPosition:
type: string
formationPositionName:
type: string
CreateFixtureOfficial:
type: object
properties:
personId:
type: integer
format: int64
description: Id of the person which will be added as fixture official
minimum: 1.0
person:
description: Person information if not been created early, if the person already exists - leave empty.
$ref: '#/definitions/CreatePersonViewModel'
metadataProperties:
type: array
description: In order to retrieve allowed metadata properties with their values execute get request on this path - /sports/{id}/fixtureperson/metadata
title: metadataProperties
items:
$ref: '#/definitions/JsonbModelViewModel'
FixtureResponseModelHATEOASReponseModel:
type: object
properties:
page:
type: integer
format: int32
pageSize:
type: integer
format: int32
totalItems:
type: integer
format: int64
items:
type: array
items:
$ref: '#/definitions/FixtureResponseModel'
self:
type: string
previous:
type: string
next:
type: string
first:
type: string
last:
type: string
BadRequestModel:
type: object
properties:
messages:
type: array
items:
type: string
ExternalIdsViewModel:
type: object
properties:
optaId:
type: string
optaLegacyId:
type: string
fibaId:
type: string
vesselId:
type: string
statsEngineId:
type: string
description: External system identifiers. Key represents the external system name (e.g., 'optaId', 'optaLegacyId', 'fibaId', 'vesselId','statsEngineId'), value represents the identifier. The property also allows filtering by specific external system identifiers. For example '?filter=externalIds.optaId[equals]:12345' to filter entities with a specific Opta ID.
ErrorModel:
type: object
properties:
code:
type: integer
format: int32
message:
type: string
error:
$ref: '#/definitions/Error'
FixtureOfficialResponseModelHATEOASReponseModel:
type: object
properties:
page:
type: integer
format: int32
pageSize:
type: integer
format: int32
totalItems:
type: integer
format: int64
items:
type: array
items:
$ref: '#/definitions/FixtureOfficialResponseModel'
self:
type: string
previous:
type: string
next:
type: string
first:
type: string
last:
type: string
PersonGenderType:
type: integer
title: Gender Type
format: int32
description: 'This property defines the possible person 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;'
enum:
- '0'
- '1'
- '2'
AcceptedModel:
type: object
properties:
messages:
type: array
items:
type: string
FixtureResponseModel:
type: object
required:
- competition
- createdOn
- eventStatusType
- eventType
- genderType
- id
- name
- sport
- startDate
- updatesCount
properties:
id:
type: integer
format: int64
createdOn:
type: string
format: date-time
modifiedOn:
type: string
format: date-time
updatesCount:
type: integer
format: int32
metadataProperties:
type: array
description: In order to retrieve allowed metadata properties with their values execute get request on this path - /sports/{id}/fixture/metadata
items:
$ref: '#/definitions/JsonbModel'
externalIds:
$ref: '#/definitions/ExternalIdsViewModel'
startDate:
type: string
format: date-time
name:
type: string
season:
$ref: '#/definitions/HALEmbededResponse'
eventStatusType:
type: string
description: Notstarted, Inprogress, Finished, Cancelled, Postponed.
locality:
$ref: '#/definitions/HALEmbededResponse'
timezone:
$ref: '#/definitions/HALEmbededResponse'
venue:
$ref: '#/definitions/HALEmbededResponse'
sport:
$ref: '#/definitions/HALEmbededResponse'
competition:
$ref: '#/definitions/HALEmbededResponse'
round:
$ref: '#/definitions/HALEmbededResponse'
homeCompetitor:
description: Id of the competitor marked as home competitor
$ref: '#/definitions/CompetitorHALEmbededResponse'
genderType:
type: string
description: Undefined, Male, Female, Mixed.
ageCategory:
$ref: '#/definitions/ageCategory'
competitors:
type: array
items:
$ref: '#/definitions/FixtureCompetitorHALEmbededResponse'
fixtureLink:
$ref: '#/definitions/HALEmbededResponse'
eventType:
type: string
description: Match, VirtualMatch, SeasonOutright, PartialOutright, AggregateEvent
matchDay:
type: integer
format: int32
attendance:
type: integer
format: int32
FixtureOfficialResponseModel:
type: object
required:
- createdOn
- id
- person
- sport
- updatesCount
properties:
id:
type: integer
format: int64
createdOn:
type: string
format: date-time
modifiedOn:
type: string
format: date-time
updatesCount:
type: integer
format: int32
person:
$ref: '#/definitions/PersonHALEmbededResponse'
sport:
$ref: '#/definitions/HALEmbededResponse'
metadataProperties:
type: array
items:
$ref: '#/definitions/JsonbModel'
FixtureCompetitorHALEmbededResponse:
type: object
required:
- competitorType
- id
- name
- ref
properties:
id:
type: integer
format: int64
name:
type: string
competitorType:
type: string
description: Team, Player, Horse, Jockey, HorseOwner, Dog, Breeder, DoublesPartnership, Other, TBD
externalIds:
$ref: '#/definitions/ExternalIdsViewModel'
metadataProperties:
type: array
items:
$ref: '#/definitions/JsonbModelViewModel'
ref:
type: string
FixtureRefdataResponse:
type: object
properties:
fixture:
$ref: '#/definitions/FixtureRefdataFixture'
PersonHALEmbededResponse:
type: object
required:
- firstName
- fullName
- genderType
- id
- lastName
- locality
- ref
properties:
id:
type: integer
format: int64
dateOfBirth:
type: string
format: date-time
firstName:
type: string
lastName:
type: string
fullName:
type: string
nickName:
type: string
genderType:
type: string
externalIds:
$ref: '#/definitions/ExternalIdsViewModel'
locality:
$ref: '#/definitions/HALEmbededResponse'
ref:
type: string
ageCategory:
type: string
title: Age Category
description: 'Default is Senior. One of: U5, U6, U7, U8, U9, U10, U11, U12, U13, U14, U15, U16, U17, U18, U19, U20, U21, U22, U23, Senior'
LineupPlayerResponseModel:
type: object
properties:
player:
$ref: '#/definitions/CompetitorHALEmbededResponse'
shirtNumber:
type: string
position:
type: string
formationPosition:
type: string
formationPositionName:
type: string
isHome:
type: boolean
order:
type: integer
format: int32
isStarter:
type: boolean
FixtureRefdataVenue:
type: object
properties:
id:
type: string
externalIds:
$ref: '#/definitions/ExternalIdsViewModel'
name:
type: string
HALEmbededResponse:
type: object
required:
- id
- name
- ref
properties:
id:
type: integer
format: int64
name:
type: string
externalIds:
$ref: '#/definitions/ExternalIdsViewModel'
ref:
type: string
FixtureRefdataCompetition:
type: object
properties:
id:
type: string
externalIds:
$ref: '#/definitions/ExternalIdsViewModel'
name:
type: string
UpdateFixture:
type: object
required:
- competitors
- startDate
properties:
id:
type: integer
format: int64
description: The ID of the fixture.
title: Id
competitors:
type: array
description: Array of competitors to be added to the fixture.
title: Competitors
items:
type: integer
description: Competitors which belong to the fixture.
title: Competitors
homeCompetitorId:
type: integer
format: int64
description: 'The ID of the competitor from the competitors list to be marked as home competitor of the fixture. Can only be updated if set to TBD competitor. By default if home competitor is not sent, the competitor which is first in the competitors list will be marked as home competitor. E.g. If you send competitors: [3,2,1], competitor with id 3 will be set as home competitor. If you send competitors: [1, 2, 3], competitor with id 1 will be marked as home competitor'
title: Home Competitor Id
startDate:
type: string
format: date-time
description: The start date of the fixture in UTC ISO-8601 format
title: Start Date
roundId:
type: integer
format: int64
description: The ID of the round the fixture belongs to.
title: Round ID
venueId:
type: integer
format: int64
description: The ID of the venue the fixture is played at.
title: Venue ID
localityId:
type: integer
format: int64
description: The ID of the country/region/administrative zone the fixture is played at.
title: Locality ID
EventStatusType:
type: integer
format: int32
description: 0 - Notstarted; 1 - Inprogress; 2 - Finished; 3 - Cancelled; 4 - Postponed
enum:
- 0
- 1
- 2
- 3
- 4
metadataProperties:
type: array
description: In order to retrieve allowed metadata properties with their values execute get request on this path - /sports/{id}/fixture/metadata
title: metadataProperties
items:
$ref: '#/definitions/JsonbModelViewModel'
externalIds:
$ref: '#/definitions/ExternalIdsViewModel'
matchDay:
type: integer
format: int32
attendance:
type: integer
format: int32
title: Update Fixture Model
description: This model should be used to propose an update to a fixture.
FixtureRefdataCompetitor:
type: object
properties:
id:
type: string
externalIds:
$ref: '#/definitions/ExternalIdsViewModel'
name:
type: string
isHome:
type: boolean
formation:
type: string
lineup:
type: array
items:
$ref: '#/definitions/FixtureRefdataLineupPlayer'
FixtureRefdataSeason:
type: object
properties:
id:
type: string
externalIds:
$ref: '#/definitions/ExternalIdsViewModel'
name:
type: string
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.
FixtureLineupsResponseModel:
type: object
required:
- confirmed
- createdOn
- id
- lineupPlayers
- updatesCount
properties:
id:
type: integer
format: int64
createdOn:
type: string
format: date-time
modifiedOn:
type: string
format: date-time
updatesCount:
type: integer
format: int32
fixture:
$ref: '#/definitions/HALEmbededResponse'
confirmed:
type: boolean
homeTeam:
$ref: '#/definitions/LineupTeamResponseModel'
awayTeam:
$ref: '#/definitions/LineupTeamResponseModel'
lineupPlayers:
type: array
items:
$ref: '#/definitions/LineupPlayerResponseModel'
CreateFixture:
type: object
required:
- competitors
- seasonId
- startDate
properties:
seasonId:
type: integer
format: int64
description: The ID of the season to fixture belongs to.
title: Season Id
competitors:
type: array
description: Array of competitors to be added to the fixture.
title: Competitors
items:
type: integer
description: Competitors which belong to the fixture.
title: Competitors
homeCompetitorId:
type: integer
format: int64
description: 'The ID of the competitor from the competitors list to be marked as home competitor of the fixture. Can only be updated if set to TBD competitor. By default if home competitor is not sent, the competitor which is first in the competitors list will be marked as home competitor. E.g. If you send competitors: [3,2,1], competitor with id 3 will be set as home competitor. If you send competitors: [1, 2, 3], competitor with id 1 will be marked as home competitor'
title: Home Competitor Id
startDate:
type: string
format: date-time
description: The start date of the fixture in UTC ISO-8601 format
title: Start Date
roundId:
type: integer
format: int64
description: The ID of the round the fixture belongs to.
title: Round ID
venueId:
type: integer
format: int64
description: The ID of the venue the fixture is played at.
title: Venue ID
localityId:
type: integer
format: int64
description: The ID of the country/region/administrative zone the fixture is played at.
title: Locality ID
name:
type: string
description: Optionally a name can be posted, which will override the default Competitor one V Competitor two logic. It's applicable for non two competitor sports
title: Name
maxLength: 250
metadataProperties:
type: array
description: In order to retrieve allowed metadata properties with their values execute get request on this path - /sports/{id}/fixture/metadata
title: metadataProperties
items:
$ref: '#/definitions/JsonbModelViewModel'
externalIds:
$ref: '#/definitions/ExternalIdsViewModel'
matchDay:
type: integer
format: int32
attendance:
type: integer
format: int32
title: Create Fixture Model
description: This model should be used to propose a new fixture.
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
FixtureRefdataResponseModelHATEOASReponseModel:
type: object
properties:
page:
type: integer
format: int32
pageSize:
type: integer
format: int32
totalItems:
type: integer
format: int64
items:
type: array
items:
$ref: '#/definitions/FixtureRefdataResponse'
self:
type: string
previous:
type: string
next:
type: string
first:
type: string
last:
type: string
LineupTeamResponseModel:
allOf:
- $ref: '#/definitions/CompetitorHALEmbededResponse'
- properties:
formation:
type: string
description: The team formation for the current lineup
title: Team formation in the lineup, e.g. 4-4-2
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