Fixture
- Raiko Pajur
Table of Contents
Fixture
What is Fixture? A Fixture is representation of a real-life Fixture between two (or more if the Sport allows it) Competitors included in the Round of the Season of the Competition. In order to create such entity you must have created the whole structure explained in detail in the https://geniussports.atlassian.net/wiki/spaces/OTF/pages/3978199697 as the Fixture requires: GSS Season Id, GSS Competitors Ids and Start Time. The domain rules wont allow you to add a Fixture if the Season does not exist or if any of the Competitors does not exist. It also wont allow you to have multiple Fixtures with the same Competitors within certain range defined by the Sport e.g. You can’t have Competitor X and Competitor Y having fixture on date 2021-12-11T22:00:00 and on 2021-12-11T22:01:00 unless the Sport allows it.
How to find out if the Fixture exists:
One way is to call Fixtures API v2 for all Fixtures for specific Season and in specific time range and then find whether they have the same Competitors
Another way is to call directly Fixtures API v2 with Create request and it will let you know if such Fixture exist by responding with status code 409 and including the GSS Id of the Fixture in the headers as
geniussports-conflict-id. So you will have the following scenario if you receive 409 then good the Fixture already exists and you can take the GSS Fixture Id from the header. If you receive 201 then also good the Fixture was created and you can find the GSS Fixture Id in the response body.
A Fixture can be proposed through the Fixtures API v2 on endpoint /fixtures
A Fixture will be considered as duplicate when all of the properties GSS Season Id, GSS Round Id (if provided), GSS Competitors Ids match any of the already existing Fixture inside the GSS system and if the StartDate property of the Fixture falls withing certain time range defined by each Sport to the nearest existing GSS Fixture that matches the above mentioned criteria.
In order to use Competitors in any of the Fixtures the related Season and/or Round should have relation with the specific Competitors.
A Fixture can be requested through the Fixture API v2 on endpoint /v2/fixtures.
If the Fixture already exists with TBD Competitors and Fixture Officials are assigned to the Fixture you cannot propose new Non TBD Competitors which have Contract with a Person which is already set as Fixture Official.
When to use
The Fixture entity can be used to define the real-life Fixtures in the Round of a Season of a Competition e.g. Premier League 2021/2022 Round 1 Player 1 vs Player 2. This is the source of truth for all Sport Fixtures provided from the GSS.
How to use
The Fixture entity can be used to override some rules of the Round, Season and/or the Competition. The Fixture entity can be retrieved from the Fixtures API v2 on endpoint /v2/fixtures. And then set the needed GSS Id to the request which is going to be made to Fixtures API v2 when it is needed.
Example workflow
GET GSS Fixtures from Fixtures API v2
curl --location --request GET 'https://ci.fixtures.api.geniussports.com/v2/fixtures' \ --header 'x-api-key: <<api_key>>' \ --header 'Content-Type: application/json' \ --header 'Authorization: <<id_token>>' \ --data-raw ''Successful response would be with status code 200 and JSON data in format:
{ "page": 0, "pageSize": 0, "totalItems": 0, "items": [ { "id": 0, // GSS Fixture Id "createdOn": "2022-06-28T13:24:31.827Z", "modifiedOn": "2022-06-28T13:24:31.827Z", "updatesCount": 0, "metadataProperties": [ // Sport specific properties { "name": "string", "value": "string", "isDeleted": true } ], "startDate": "2022-06-28T13:24:31.827Z", // The start date of the fixture in UTC "name": "string", // The name of the Fixture "season": { // The Season in which the Fixture will be played "id": 0, "name": "string", "ref": "/seasons/{id}" }, "eventStatusType": "string", // The event status type of the Fixture: Notstarted, Inprogress, Finished, Cancelled "locality": { // The locality where the Fixture will take place "id": 0, "name": "string", "ref": "/localities/{id}" }, "timezone": { // The Timezone in which the Fixture will take place "id": 0, "name": "string", "ref": "/timezones/{id}" }, "venue": { // The Venue on which the Fixture will be held "id": 0, "name": "string", "ref": "/venues/{id}" }, "sport": { // The sport for which is the Fixture "id": 0, "name": "string", "ref": "/sports/{id}" }, "competition": { // The Competition in which is the Fixture "id": 0, "name": "string", "ref": "/competitions/{id}" }, "round": { // The Round in which is the Fixture "id": 0, "name": "string", "ref": "/rounds/{id}" }, "homeCompetitor": { // The Home Competitor of the Fixture if available "id": 0, "name": "string", "competitorType": "string", "ref": "/competitors/{type}/{id}" }, "genderType": "string", // The Gender of the Competitors in the Fixture "competitors": [ // The Competitors which will take part in the Fixture including the HomeCompetitor { "id": 0, "name": "string", "competitorType": "string", "ref": "/competitors/{type}/{id}v" } ], "fixtureLink": { // The Linked fixture if available "id": 0, "name": "string", "ref": "/fixtures/{id}" }, "eventType": "string", // The type of the fixture: Match, VirtualMatch, SeasonOutright, PartialOutright, AggregateEvent "matchDay": 0, // Null or in range 1-100. Representing real life match day. "attendance": 0 // Null or positive integer. The number of people present at the event } ], "self": "string", "previous": "string", "next": "string", "first": "string", "last": "string" }
Read Data Points
Field | Type | Nullable | Description |
|---|---|---|---|
id | int64|unsigned |
| The numeric identifier of the Fixture in GSS |
name | string |
| The name of the Fixture. If not provided it is auto-filled by the names of the Competitors separated by ' vs '. |
startDate | timestamp |
| The date and time in UTC on which the Fixture starts |
eventType | string| in: Match, VirtualMatch |
| Defines the type of the Fixtures |
genderType | string|in: undefined, male, female, mixed | Restricts the Fixture to contain only Competitors for the specific Gender. This property is read-only and is auto-filled by the associated Season | |
eventStatusType | string|in: NotStarted, Inprogress, Finished, Cancelled, Postponed |
| Defines the status of the Fixture |
sport | object|SportEmbed |
| The numeric identifier, name and a reference of the Sport for which is the Fixture. This property is read-only and is auto-filled by the associated Season |
competition | object|CompetitionEmbed |
| The numeric identifier, name and a reference of the Competition for which is the Fixture. This property is read-only and is auto-filled by the associated Season |
season | object|SeasonEmbed |
| The numeric identifier, name and a reference of the Season for which is the Fixture |
round | object|RoundEmbed |
| The numeric identifier, name and a reference of the Round for which is the Fixture. The property is nullable due to legacy reasons |
venue | object|VenueEmbed |
| The numeric identifier, name and a reference of the Venue at which the Fixture will be held |
locality | object|LocalityEmbed |
| The numeric identifier, name and a reference of the Locality where the Fixture will be held |
timezone | object|TimezoneEmbed | The numeric identifier, name and a reference of the Timezone in which the Fixture will be held. This property is read-only and is auto-filled by the associated Round or Season | |
competitors | array|object|CompetitorEmbed |
| The numeric identifiers, names and a references of the Competitors which will take part in the Fixture. Can only be updated if the Competitors are TBD Competitors |
fixtureLink | object|FixtureEmbed |
| The numeric identifier, name and a reference of the Fixture which is directly linked to the current one. E.g.: |
homeCompetitor | object|CompetitorEmbed |
| The numeric identifier, name and a reference of the Home Competitor in the Fixture. If the Home Competitor is not provided upon creation of the Fixture the Competitor which is first in the
Once set the Home Competitor can only be changed if there is at least one TBD Competitor in the already added Competitors in the Fixture. |
matchday | int32|unsigned |
| Representing real life match day. |
attendance | int32|unsigned |
| The number of people present at the event |
metadataProperties | array|MetadataEmbed |
| |
createdOn | timestamp |
| The timestamp when the data entity was created |
modifiedOn | timestamp |
| The timestamp when the data entity was modified |
updatesCount | int32|unsigned |
| The amount of times the data entity was updated |
Create/ Update Data Points
Field | Type | Required On Create | Required On Update | Patchable | Description |
|---|---|---|---|---|---|
id | int64|unsigned |
| The numeric identifier of the Fixture in GSS | ||
name | string |
|
| The name of the Fixture. If not provided it is auto-filled by the names of the Competitors send via | |
startDate | string |
| The date on which the Fixture starts | ||
competitiors | array|int64|unsigned |
|
|
| The GSS Competitor Ids which will take part in the Fixture. |
seasonId | int64|unsigned |
|
| The GSS Season Id with which the Fixture will be associated. Once set it cannot be changed! | |
roundId | int64|unsigned |
|
|
| The GSS Round Id of the Fixture. Once set it cannot be changed |
venueId | int64|unsigned |
|
|
| The GSS Venue Id at which the Fixture will be held if available. |
localityId | int64|unsigned |
|
|
| The GSS Locality Id where the Fixture will be held |
homeCompetitorId | int64|unsigned |
|
|
| The GSS Competitor Id of the Home Competitor. The Home Competitor Id must be contained in the proposed
Once set the Home Competitor can only be changed if there is at least one TBD Competitor in the already added Competitors in the Fixture. |
eventStatusType | int32|in: 0, 1, 2, 3, 4 |
|
|
| Defines the status of the Fixture:
By default on Create |
matchday | int32|unsigned |
|
|
| Representing real life match day. |
attendance | int32|unsigned |
|
|
| The number of people present at the event |
metadataProperties | string |
|
Validations
Description | On Create | On Update | On Patch | On Delete | Response Code | Contains Conflict Header | Error Message |
|---|---|---|---|---|---|---|---|
Fixture must exist |
| 400 | Not found. Missing Fixture entity with id: {proposed id} | ||||
Fixture must not exist |
| 409 | Conflict detected! There is an existing fixture with the same competitors in the next/previous 24 hours: {existing fixture id}. Check if the existing fixture is same as the proposed fixture and if not check the start time and the competitors again. | ||||
Any of the proposed Competitors cannot have fixture within specific time range |
| 400 | The following competitors have fixtures (competitorId-fixtureId): {combination of competitor and fixture ids separated by | ||||
Season must exist |
| 400 | Not found. Missing Season entity with id: {proposed season id} | ||||
Round must exist |
|
| 400 | Not found. Missing Round entity with id: {proposed round id} | |||
Locality must exist |
| 400 | Not found. Missing Locality entity with id: {proposed locality id} | ||||
Timezone must exist |
| 400 | Not found. Timezone with name {proposed timezone} does not exists. | ||||
All competitors must exist |
| 400 | The following competitors are missing: {competitors ids separated by ', '} | ||||
All competitors must have the same competitor type |
| 400 | Only competitors with same competitor type are allowed to be part of a fixture! | ||||
Competitors count is at least 2 This validation is not applied when |
| 400 | Competitors count is less than 2! | ||||
Competitors count matches Sport specific count (2 or more) |
| 400 | Competitors count is more than the sport limit! Sport Limit: {proposed sport’s | ||||
Competitors are part of proposed Season’s Competitor |
| 400 | Not all competitors {competitor ids separaterd by ', '} are added in this season: {proposed season id} | ||||
Only distinct competitors can be sent |
| 400 | Duplicated competitors: {competitor ids separated by ', '} | ||||
Competitors must not have active Contracts with associated Fixture Officials |
|
| 400 | Some of the persons marked as officials for the current fixture have contracts with the competitors proposed for the fixture! Persons which are officials and part of competitors contracts are: {person id → competitor id combinations separated by ', '} | |||
Fixture competitors cannot be changed unless they are TBD competitors. |
|
| 400 | Fixture competitors cannot be changed unless they are TBD competitors. Non TBD competitors changed: {competitor ids separated by ', '} | |||
HomeCompetitorId must be part of the proposed competitors |
| 400 | Home Competitor with Id {proposed home competitor id} is not part of the proposed competitors: {competitors ids separated by ', '}! | ||||
HomeCompetitorId must not be changed once already added competitors do not contain TBD competitors |
|
| 400 | Once set home competitor cannot be updated! Except for when one of the proposed competitors is TBD competitor! Current home compeitor Id: {competitor id} | |||
Fixture is not real (Locality is not set to Test Region) |
|
| 400 | Cannot delete fixture with id {proposed fixture id} because it is not test fixture! | |||
Proposed RoundId must be associated with Proposed Season Id |
|
|
|
| 400 | The round: {proposed round id} is not in season: {proposed season id} | |
Proposed |
| 400 | Fixture's 'startDate' should be in the year's date range of the Season | ||||
Proposed startDate must not be changed with more than the sport specific threshold (due to legacy reasons) |
|
| 400 | Forbidden! Changing the start time by more than {sport specific threshhold} hours is not allowed for this sport by PUT request. In order accomplish that you must POST to /fixture adding an extra property 'DeletedOldFixtureId': {proposed fixture id}. This will automatically delete the current fixture create new one, connected to it. | |||
Proposed startDate must be changed with more than the sport specific threshold on recreate (due to legacy reasons) |
|
| 400 | In order to trigger the 'Recreate event logic' fixtures must have more than {sport specific threshhold} hours difference in the 'startTime'. Currently the diff is {difference between current and proposed start dates} hours. | |||
Venue must be associated with the sport of the Fixture |
|
| 400 | Can not attach fixture with sport id {0} to this venue because venue is not associated with the sport associated with the current fixture! | |||
Match day must be between 1 and 100 or not set ( |
|
|
|
| 400 |
| Allowed range is 1 to 100. |
Fixtures with |
|
|
|
| 400 |
| Cancelled and Postponed fixtures cannot be updated! |
Fixture name must be send for fixtures without competitors |
|
|
|
| 400 |
| Fixture name is required for fixtures without competitors. |
Attendance must be positive integer or not set ( |
|
|
|
| 400 |
| Allowed range is 1 to int.MaxValue |