Venue
- Raiko Pajur
Table Of Contents
Venue
What is Venue? The venue entity defines different things in different context:
For Fixture, Round, Season, Competition: a more specific Locality for the entity
For Team: It defines the home venue of it
Each venue can have multiple sub-venues. E.g. in snooker the Sheffield Theater Venue can have multiple snooker tables and on each table a different Fixture can take place.
Venue can be used on Season level to define the place where all Fixtures and Rounds will take place.
A Venue can be associated with multiple Sports e.g. Madison Square Garden where it can both host basketball Fixtures and ice hockey Fixtures.
Venues can be proposed through the Fixtures API v2 on endpoint /v2/venues.
Venue will be considered as duplicate when all of the following properties Name, GSS Locality Id and GSS Parent Venue Id (if provided) match any of the already existing venues in the GSS system.
Venues can be requested on Fixtures API v2 on endpoint /v2/venues.
When to use
The Venue entity is mostly used as additional data defining more specific location for every entity which related to it. The association of entity with venue is not required and also it is editable which means that it can be changed anytime.
How to use
The Venue entity can be used by getting the GSS Id of the Venue from the Fixtures API v2 on endpoint /v2/venues. 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 Venues from Fixtures API v2
curl --location --request GET 'https://ci.fixtures.api.geniussports.com/v2/venues' \ --header 'x-api-key: <<api_key>>' \ --header 'Content-Type: application/json' \ --header 'Authorization: <<id_token>>' \ --data-raw ''The successful response would be with status code 200 and JSON data in the format:
{ "page": 0, "pageSize": 0, "totalItems": 0, "items": [ { "id": 0, // GSS Venue Id "name": "string", // GSS Venue Name "latitude": 0, "longitude": 0, "locality": { "Id": 0, // GSS Locality Id to which the venue is related "Name": "string", "ref": "/localities/{id}" // Endpoint on which the Locality is available }, "capacity": 0, "cityName": "string", "sports": [ { "Id": 0, "Name": "string", "ref": "/sports/{id}" // Endpoint on which Sport is available } ], // GSS Sport Ids to which the venue is related "parentVenue": { "Id": 0, "Name": "string", "Ref": "/venues/{Id}" } } ], "self": "string", "previous": "string", "next": "string", "first": "string", "last": "string" }POST Fixture with any of the retrieved GSS Venue 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": [ 0 ], "startDate": "2021-11-29T09:34:10.302Z", "roundId": 0, "venueId": 0,// GSS Venue Id from previous request "localityId": 0, "name": "string" } '
Read Data Points
Field | Type | Nullable | Description |
|---|---|---|---|
id | int64|unsigned |
| The numeric identifier of the Venue |
name | string |
| The name of the Venue |
latitude | double|between:-90,90 |
| The latitude coordinates at geographic coordinate system, in degrees |
longitude | double|between:-180,180 |
| The longitude coordinates at geographic coordinate system, in degrees |
locality | object|LocalityEmbed |
| The name, id and a reference of the Locality where the Venue is located |
capacity | int32|unsigned |
| The spectator capacity of the Venue |
cityName | string |
| The name of the City where the Venue is located |
parentVenue | object|VenueEmbed |
| The numeric identifier, name and relative reference to the parent Venue, in the case if the Venue is a Sub-Venue |
sports | array|int64|unsigned |
| The list of Sports related to the Venue |
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 For Create | Required For Update | Description |
|---|---|---|---|---|
id | int64|unsigned |
|
| The numeric identifier of the Venue |
name | string |
|
| The name of the Venue |
latitude | double|between:-90,90 |
|
| The latitude coordinates at geographic coordinate system, in degrees |
longitude | double|between:-180,180 |
|
| The longitude coordinates at geographic coordinate system, in degrees |
localityId | int64|unsigned |
|
| GSS Locality Id where the Venue is located |
capacity | int32|unsigned |
|
| The spectator capacity of the Venue |
cityName | string |
|
| The name of the City where the Venue is located |
parentVenueId | int64|unsigned |
|
| GSS Venue Id when the Venue is a Sub-Venue |
sports | array|int64|unsigned |
|
| The list of GSS Sport Ids related to the Venue |
Validations
Description | On Create | On Update | On Delete | Response Code | Contains Conflict Header | Error Message |
|---|---|---|---|---|---|---|
Venue must exist |
|
|
| 400 |
| Not found. Missing Venue entity with id: {proposed id} |
Venue must not exist |
|
|
| 409 |
| Conflict detected! Venue with name {proposed name} and locality {proposed locality id} already exists. Check if the venue you propose is the same as the one already existing in the database under id {existing venue 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 locality id} |
Sports must exist |
|
|
| 400 |
| Not found. Only existing sports can be associated with venue. Sports which do not exist: {proposed sport ids separated by ', '} |
Parent-Venue must exist |
|
|
| 400 |
| Not found. Missing Venue entity with id: {proposed Parent Venue Id} |
Venue cannot be sub-venue of sub-venue |
|
|
| 400 |
| Cannot create sub venue with sub venue parent! |
When Venue is parent venue, the sport ids which are associated with the Sub Venue cannot be removed from the Venue |
|
|
| 400 |
| Cannot remove sports with ids {sport ids separated by ', '} from current venue because it has non deleted sub venue associated with it which are related to those sports! |
When Venue is Sub-Venue the associated sports must be part of the Parent-Venue’s sports |
|
|
| 400 |
| Parent venue does not contain sport(s): {sport ids separated by ', '} |
When Venue is Sub-Venue its Locality must match Parent-Venue’s locality |
|
|
| 400 |
| Sub venue locality should be the same as parent venue locality! Parent venue locality id: {locality id} |
When Sport is removed from Venue no Competitor associated with the Sport should be related to the Venue |
|
|
| 400 |
| Cannot remove sports with ids {sport ids separated by ', '} from current venue because it has non deleted competitors associated with it which are related to those sports! |
When Sport is removed from Venue no Fixture associated with the Sport should be related to the Venue |
|
|
| 400 |
| Cannot remove sports with ids {sport ids separated by ', '} from current venue because it has non deleted fixtures associated with it which are related to those sports! |
When Sport is removed from Venue no Season associated with the Sport should be related to the Venue |
|
|
| 400 |
| Cannot remove sports with ids {sport ids separated by ', '} from current venue because it has non deleted seasons associated with it which are related to those sports! |
Venue must not have sub-venues |
|
|
| 400 |
| Cannot delete venue associated with not deleted sub venues! |
Venue must not have associated fixtures |
|
|
| 400 | Only venues without associated fixtures can be deleted! |