Locality
- Raiko Pajur
Table Of Contents
Locality
What is Locality? The locality entity has different meaning in different context:
For Fixture, Round, Season and Competition it defines the place where the entity will be held at.
For Competitor and Person it defines the nationality of the real-life Competitor/Person.
For Venue it defines the location of the venue in the real world.
The localities can be proposed on endpoint /v2/localities
A Locality will be considered as duplicate if the Name and Type of the proposed localities match any of the existing localities in the GSS System.
The localities can be requested through on endpoint /v2/localities.
When to use
The Locality entity is mostly used as additional data defining a specific location for every entity which in most cases is not required. The entities which require such additional data are Competitions, Persons and Competitors.
The locality property is editable so even if you do not know the locality at first for those competitors you can set the Locality to world (GSS Locality Id 2)
How to use
The Locality entity can be used by getting the GSS Id of the Locality from the Fixtures API v2 on endpoint /v2/localities. And then set the needed GSS Id to the request which is going to be made to Fixtures API v2 when it is needed. If you want to filter them by CountryCode you can call the endpoint with the following query string: /v2/localities?filter=code:<<your_code>>. If the locality you search for cannot be found using this code, you can try filter by name /v2/localities?filter=code[contains]:<<name>> where name could be the full name or part of it.
If the locality still does not appear please consider contacting us before trying to propose a new country.
Example workflow
GET GSS Localities from Fixtures API v2
curl --location --request GET 'https://ci.fixtures.api.geniussports.com/v2/localities?filter=code:BUL' \ --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 Locality Id "name": "string", // GSS Locality Name "createdOn": "2021-11-29T09:44:42.312Z", "modifiedOn": "2021-11-29T09:44:42.312Z", "updatesCount": 0, "localityType": "string", "code": "string" } ], "self": "string", "previous": "string", "next": "string", "first": "string", "last": "string" }POST Competition with any of the retrieved GSS Locality Ids:
curl --location --request POST 'https://ci.fixtures.api.geniussports.com/v2/competitions' \
--header 'x-api-key: <<api_key>>' \
--header 'Content-Type: application/json' \
--header 'Authorization: <<id_token>>' \
--data-raw '{
"sportId": 10,
"localityId": 3795038, // This could be any GSS Locality Id
"genderType": "1",
"name": "Some Competition Name"
}'
Read Data Points
Field | Type | Nullable | Description |
|---|---|---|---|
id | int64|unsigned |
| The numeric identifier of the Locality in GSS |
name | string |
| The name of the Locality |
localityType | string|in:ConstituentCountry,Continent,Country,FirstOrderAdministrativeRegion,NonGeographic,World,Game |
|
|
code | string|in:ISO 3166-1 alpha-3 |
| The ISO 3-letter code for the localityType Country |
createdOn | timestamp |
| The timestamp when the data entity was created |
modifiedOn | timestamp |
| The timestamp when the data entity was last updated |
updatesCount | int64|unsigned|default:0 |
| 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 Locality in GSS |
name | string |
|
| The name of the Locality |
localityType | string|in:ConstituentCountry,Continent,Country,FirstOrderAdministrativeRegion,NonGeographic,World,Game |
|
|
|
Validations
Description | On Create | On Update | On Delete | Response Code | Contains Conflict Header | Error Message |
|---|---|---|---|---|---|---|
Locality must not exist |
|
|
| 409 |
| Conflict detected! Locality with name {proposed name} and locality type {proposed type} already exists. Check if the locality you propose is the same as the one already existing in the database under id {existing id}. If it is you can update it, if not you should think of another name! |
Locality must exist |
|
|
| 400 |
| Not found. Missing Locality entity with id: {proposed id} |
Nothing is associated with the locality |
|
|
| 400 |
| The Locality is associated with an entity of type: {Related entity type name} and cannot be deleted until it referred to it! |