Team Competitor
- Raiko Pajur
Table of Contents
Team
A Competitor of type Team eases the representation of data for a real world team.
A Team can be proposed through the Fixtures API v2 on endpoint /v2/competitors/teams.
A team will be considered as duplicate when all of the following properties Name, GSS Locality Id, GSS Sport Id and GenderType match any of the already existing teams in the GSS system.
A Team can be requested through the Fixtures API v2 on endpoint /v2/competitors/teams.
When to use
The competitor of type Team can be used to define the real-life teams which are part of a Sport.
How to use
The competitor of type Team entity can be used by getting the GSS Id of the Team from the Fixtures API v2 on endpoint /v2/competitors/teams. 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 Teams from Fixtures API v2
curl --location --request GET 'https://ci.fixtures.api.geniussports.com/v2/competitors/teams' \ --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": [ { "metadataProperties": [ { "name": "string", "value": "string" } ], "id": 0, // GSS Team Id "name": "string", // GSS Team Name "abbreviation": "string", // Team abbreviation "sport": { "Id": 0, // Defines what competitors and in what fixtures, seasons, rounds the team can be used "Name": "string", "ref": "/sports/{id}" // Endpoint on which Sport is available }, "locality": { "Id": 0, // The Team location "Name": "string", "ref": "/localities/{id}" // Endpoint on which the Locality is available }, "genderType": "string", // The gender of the Team (defines in which seasons it can be used (e.g. season with gendertype Male cannot include teams with gender type Female) "competitorStatusType": "string", // Defines whether the player can be used in teams or in fixtures. It can only be used if the status is set to 'Active' "createdOn": "2021-11-29T11:02:48.077Z", "modifiedOn": "2021-11-29T11:02:48.077Z", "venue": { "Id": 0, // Possible venue considered as home venue "Name": "string", "Ref": "/venues/{Id}" } } ], "self": "string", "previous": "string", "next": "string", "first": "string", "last": "string" }POST Fixture with any of the retrieved GSS Teams Ids:
curl --location --request POST '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 '{ "seasonId": 0, "competitors": [ // Include separated by coma 2 GSS Team Ids which are going to compete in the fixture // e.g. 1, 2 ], "startDate": "2021-11-29T09:34:10.302Z", "name": "string" } '
Read Data Points
Field | Type | Nullable | Description |
|---|---|---|---|
id | int64|unsigned |
| The numeric identifier of the Team |
name | string |
| The name of the Team. |
abbreviation | string |
| Team abbreviation |
genderType | string|in: undefined, male, female, mixed |
| Restricts the Team to be used only in Mixed or in its specific gender Fixtures, Rounds, Seasons. It also defines what can be the Persons in the Contracts which will be added to the Team. |
competitorStatusType | string|in: Active, Retired, Unattached |
| Active - The Team can be used in Fixtures, Rounds, Seasons. Retired/ Unattached - The Team cannot be used in Fixtures, Rounds, Seasons. This property is auto set on creation to Active. |
sport | object|SportEmbed |
| The numeric identifier, name and a reference of the Sport that the Team can take part in. |
locality | object|LocalityEmbed |
| The id, name and reference of the Locality that represents the Home Country of the Team |
venue | object|VenueEmbed |
| Represents the home Venue of the Team |
metadataProperties | array|MetadataEmbed |
| |
createdOn | timestamp |
| The timestamp when the data entity was created |
modifiedOn | timestamp |
| The timestamp when the data entity was last updated |
updatesCount | int32|unsigned |
| The amount of times the data entity was updated |
Create/ Update Data Points
Field | Type | Required For Create | Required For Update | Description |
|---|---|---|---|---|
id | int64|unsigned |
|
| The numeric identifier of the Team |
name | string |
|
| The name of the Team. |
abbreviation | string |
|
| Team abbreviation |
genderType | int32|in: 0, 1, 2, 3 |
|
| 0 - Undefined; 1 - Male; 2 - Female; 3 - Mixed |
competitorStatusType | int34|in: 0, 1, 2 |
|
| 0 - Active, 1 - Retired, 2 - Unattached Active - The Player can be used in Fixtures, Rounds, Seasons. Retired/ Unattached - The Player cannot be used in Fixtures, Rounds, Seasons. This property is auto set on creation to Active. |
localityId | int64|unsigned |
|
| The Locality which will represent the Home Country of the Team. |
venueId | int64|unsigned |
|
| The Venue which will represent the home venue of the Team. |
sportId | int64|unsigned |
|
| The GSS Sport Id in which the Team can be used in Fixtures, Rounds, Seasons |
metadataProperties | array|MetadataEmbed |
|
|
Validations
Description | On Create | On Update | On Delete | Response Code | Contains Conflict Header | Error Message |
|---|---|---|---|---|---|---|
Team must exist |
|
|
| 400 |
| Not found. Missing Team entity with id: {proposed id} |
Team must not exist |
|
|
| 409 |
| Conflict detected! Competitor with name {proposed name}, locality {proposed locality id}, sport {proposed sport id}, gender {proposed genderType} and type Team already exist. Check if the competitor you propose is the same as the one already existing in the database under id {existing team id}. If it is you can update it, if not you should think of another name or check if any of the values is wrong! |
Name MUST end with Women (legacy reasons) (e.g. Barcelona Women) when GenderType is set to Female (2) |
|
|
| 400 |
| Competitor name must contain Women as name ending when competitor is of type Team (0) and gender Female (2)! |
Venue must exist |
|
|
| 400 |
| Not found. Missing Venue entity with id: {proposed venue id} |
Venue must be associated with the sport to which the team is associated |
|
|
| 400 |
| Venue {proposed venue id} cannot be assigned to competitor as the venue is not associated with competitor's sport {proposed sport id}. You can resolve that issue by changing competitor's sport to any sport associated with the selected venue, by checking if the venue provided is wrong venue or by associating the venue to competitor's sport! |
Locality must exist |
|
|
| 400 |
| Not found. Missing Locality entity with id: {proposed locality id} |
Name MUST NOT end with Women (legacy reasons) (e.g. Barcelona Women) when GenderType is set to Male (1) |
|
|
| 400 |
| Competitor name must not contain Women as name ending when competitor is not of type Team (0) and gender Female (2)! |
Sport must exist |
|
|
| 400 |
| Not found. Missing Sport entity with id: {proposed sport id} |
Must not have competitor links |
|
|
| 400 |
| The team cannot be deleted, because it have links to other competitors. Associated competitor ids: {competitor ids separated by ', '} |
Must not be associated with Seasons |
|
|
| 400 |
| Only competitor without associated Seasons can be deleted! |
Must not be associated with Rounds |
|
|
| 400 |
| Only competitor without associated Rounds can be deleted! |
Must not be associated with Fixtures |
|
|
| 400 |
| Only competitor without associated Fixtures can be deleted! |
On CompetitorStatusType change the Player must not be part of future fixtures |
|
|
| 400 |
| Competitor cannot be associated with future fixtures when status is changed! In order to update status of the current competitor delete all fixtures associated with it. |
Abbreviation length should not be longer then 3 symbols |
|
|
| 400 |
| Field abbreviation length should be between 1 and 3 symbols |