|
|
use case 10 - Sport Events |
|
|
\ No newline at end of file |
|
|
**Use case 10** is dedicated to information related to sporting events
|
|
|
|
|
|
DGT 3.0 Plataform , with the perimeter beaconing service for sporting events, collects and publishes information on the real-time location of all sporting events (cycling competitions, road athletics events, rallies, etc.) that affect circulation and safety road of the users who transit through the roads of the Spanish territory.
|
|
|
|
|
|
In this way, the user better plans their trips, and consider the option of using public transport that allows the reduction of polluting emissions.
|
|
|
|
|
|
The beaconing information of the special vehicles that reaches the end user will depend on the implementation carried out by the agent/third party that consumes the information from the DGT 3.0 platform and publishes it through the vehicle information system, mobile application or other devices.
|
|
|
|
|
|
This use case aims to collect and publish real-time location information of all sporting events (cycling competitions, road athletics events, rallies, etc.) that may affect traffic and road safety of users traveling on the roads of Spanish territory.
|
|
|
|
|
|
The way in which the vehicle information reaches the end user will depend on the implementation carried out by the agent/third party that consumes the information from the DGT 3.0 platform and publishes it to the user through the vehicle information system, mobile application, etc.
|
|
|
|
|
|
The platform has two different functionalities for the **publication (sending)** and for the **subscription (reception)** of information. The first is through a REST API and the second through a real-time MQTT service
|
|
|
|
|
|
|
|
|
Both the publication and subscription functionality require different access certificates that must be requested and supplied by DGT 3.0. These certificates, if they have not already been requested, must be requested from *[soporte@cmobility30.es](mailto:soporte@cmobility30.es)*.
|
|
|
|
|
|
|
|
|
Below are the URLs with which each functionality is accessed:
|
|
|
|
|
|
| Mode | URL | Description |
|
|
|
| ----------- | -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
|
|
|
| Publication | https://pre.cmobility30.es/use-case-10 | Client integration environment endpoint for publishing (certain publishing methods will be accessible for consumption) |
|
|
|
| Suscription | mqtt://mqtt.pre.cmobility30.es:8883 | Integration environment endpoint for subscription |
|
|
|
|
|
|
The two functionalities are described below.
|
|
|
|
|
|
## Publication
|
|
|
|
|
|
This use case has a REST API for the publication (sending) of the data by the companies that so wish. Details of this can be found in the following sections:
|
|
|
|
|
|
- General details for making a request:
|
|
|
|
|
|
> [General · (cmobility30.es)](https://gitlab.cs.cmobility30.es/dgt3.0_esp/general/-/wikis/home)
|
|
|
|
|
|
- Information regarding the specific methods of the use case:
|
|
|
|
|
|
> [Publication methods](publicacion/Metodos)
|
|
|
|
|
|
**Note:** *Some publication methods for obtaining information may also be used by consumers.*
|
|
|
|
|
|
## Suscription
|
|
|
|
|
|
This use case also has a data subscription (reception) service by companies that so wish through the MQTT protocol. Details of this can be found below:
|
|
|
|
|
|
**MQTT (MQ Telemetry Transport)** is a messaging protocol used as a simple and lightweight method of transferring data to/from low-power devices.
|
|
|
|
|
|
The protocol supports a single messaging pattern, the pattern **Publication-Suscription**: each message is published in a topic to which you must subscribe to receive the information.
|
|
|
|
|
|
The subscription to the service of this use case must be through the topic:
|
|
|
|
|
|
> usecase10/events
|
|
|
|
|
|
The events are published in the topic in JSON format. Here you can see an example:
|
|
|
|
|
|
```json
|
|
|
[
|
|
|
{
|
|
|
"type": "Feature",
|
|
|
"geometry": {
|
|
|
"type": "LineString",
|
|
|
"coordinates": [
|
|
|
[-8.103828008, 42.43725749],
|
|
|
[-8.103811299, 42.4371521],
|
|
|
[-8.103694601, 42.436921801],
|
|
|
[-8.1035701, 42.436750501],
|
|
|
[-8.103351901, 42.436613301]
|
|
|
]
|
|
|
},
|
|
|
"properties": {
|
|
|
"objectid_1": 1,
|
|
|
"objectid": 63993,
|
|
|
"ddtram_cod": 58651,
|
|
|
"ddcar_codi": "58312",
|
|
|
"ddcar_deno": "De Carballiño (N-541) a Parada de Laviote (OU-0416)",
|
|
|
"ddtram_den": "De Carballiño (N-541) a Parada de Laviote (OU-0416)",
|
|
|
"ddtram_tip": "Diputación Provincial o Foral",
|
|
|
"ddtram_tit": "Excma. Diputación Provincial de Orense",
|
|
|
"ddtram_t_1": "Carretera Convencional",
|
|
|
"ddtram_lon": 14.802,
|
|
|
"pk_ini": 0,
|
|
|
"pk_fin": 14.52,
|
|
|
"idtipovian": "Convencional (Red Provincial)",
|
|
|
"ddprov_pro": "Ourense",
|
|
|
"ddcom_comu": "Galicia",
|
|
|
"color": 0,
|
|
|
"ddcar_carr": "OU-0417",
|
|
|
"ddtvia_ord": 3,
|
|
|
"pkinigis": 0,
|
|
|
"pkfingis": 14520,
|
|
|
"shape_leng": 29189.174671589997,
|
|
|
"shape_length": 0.046871310877717093,
|
|
|
"hora_inicio_paso": "15:30:00",
|
|
|
"hora_fin_paso": "21:00:00",
|
|
|
"pk_inicio_tram_etp": 0.20000000000000001,
|
|
|
"pk_fin_tram_etp": 4.75,
|
|
|
"tipo_vialidad": "Carretera normalizada",
|
|
|
"cod_vialidad": "RCL",
|
|
|
"geom": {
|
|
|
"type": "LineString",
|
|
|
"coordinates": [
|
|
|
[-8.103828007999937, 42.437257490000036],
|
|
|
[-8.103811298999972, 42.43715210000005],
|
|
|
[-8.103694600999972, 42.43692180100004],
|
|
|
[-8.093740699999955, 42.434503101000075],
|
|
|
[-8.093614100999957, 42.43436520100005],
|
|
|
[-8.092964999999936, 42.43318130100005],
|
|
|
[-8.092723598999953, 42.43292000000008],
|
|
|
[-8.092503700999941, 42.43276560100003],
|
|
|
[-8.092117499999972, 42.432682501000045],
|
|
|
[-8.091908299999943, 42.43263500100005],
|
|
|
[-8.091685299999938, 42.432479801000056],
|
|
|
[-8.091623899999945, 42.43243700100004],
|
|
|
[-8.091436199999976, 42.43236570100004],
|
|
|
[-8.091278498999941, 42.43237700100008],
|
|
|
[-8.09117729999997, 42.43242100200007],
|
|
|
[-8.090216798999961, 42.43317410100008],
|
|
|
[-8.090009298999973, 42.43326840100008],
|
|
|
[-8.089911899999947, 42.43329610100005],
|
|
|
[-8.089724899999965, 42.43332390100005],
|
|
|
[-8.088678899999934, 42.433407000000045],
|
|
|
[-8.08825509999997, 42.43336350100003],
|
|
|
[-8.088100876999931, 42.43333978700008]
|
|
|
]
|
|
|
},
|
|
|
"tsinicio": "2022-05-07T02:00:00",
|
|
|
"tsfin": "2022-05-07T02:00:00",
|
|
|
"evento": "XXIII SUBIDA A SALETA",
|
|
|
"timestamp" : "2022-05-07T12:00:00"
|
|
|
}
|
|
|
}
|
|
|
]
|
|
|
```
|
|
|
|
|
|
Schema for publication of sporting events through the DGT 3.0 platform. Publish the geometric information of the event along with its roads, pk and passing times:
|
|
|
|
|
|
- **type** (string): Feature Identifier.
|
|
|
|
|
|
- **geometry**: Collection of geometries of each stage section of TR10. Geometric representation with the coordinates.
|
|
|
|
|
|
- **type**(string): Geometry type identifier.
|
|
|
|
|
|
- **coordinates**: Routemeter Coordinate Collection.
|
|
|
|
|
|
- **timestamp** (fecha UTC): Date and time in UTC format of the moment in which the car park was updated for the last time. It needs to not be a future timestamp with respect to the current UTC time. The date must end with the character 'Z' that marks that it is in UTC
|
|
|
|
|
|
- **properties**: Schema properties for the publication of sporting events.
|
|
|
|
|
|
- **objectid_1**(integer): Stage Identifier
|
|
|
|
|
|
- **objectid**(integer): Object identifier according to GIS.
|
|
|
|
|
|
- **ddtram_cod**(int): Official identifier of the section in BDC (Road Database)
|
|
|
|
|
|
- **ddcar_codi**(string): Road identifier in BDC (Road Database)
|
|
|
|
|
|
- **ddcar_deno**(string): Road name in BDC (Road Database)
|
|
|
|
|
|
- **ddtram_den**(string): Name of the section in the road database
|
|
|
|
|
|
- **ddtram_tip**(string): Typology of the owner of the section in road databases
|
|
|
|
|
|
- **ddtram_tit**(string): Name of the owner of the section in road databases
|
|
|
|
|
|
- **ddtram_t_1**(string): Typology of the section in the road database
|
|
|
|
|
|
- **ddtram_lon**(integer): Total length of the section in the road database
|
|
|
|
|
|
- **pk_ini**(string): Kilometer starting point of the section and official section in the road database.
|
|
|
|
|
|
- **pk_fin**(string): Kilometer point of end of the section and official of the section in road database.
|
|
|
|
|
|
- **idtipovian**(string): Road typology in road databases.
|
|
|
|
|
|
- **ddprov_pro**(string): Province of the section in road database.
|
|
|
|
|
|
- **ddcom_comu**(string): Autonomous community of the section in the road database.
|
|
|
|
|
|
- **color**(string): Road color according to GIS for mapamovilidad.es.
|
|
|
|
|
|
- **pkinigis**(integer): Starting kilometer point of the section according to the GIS.
|
|
|
|
|
|
- **pkfingis**(integer): Kilometric point of end of the section according to GIS.
|
|
|
|
|
|
- **shape_length**(numeric): Length of the shape according to coordinates.
|
|
|
|
|
|
- **hora_fin_paso**(Time): Time of passage of the last participant.
|
|
|
|
|
|
- **hora_inicio_paso**(Time): Time of passage of the first participant.
|
|
|
|
|
|
- **ddcar_carr**(string): Official highway nomenclature in highway database.
|
|
|
|
|
|
- **pk_inicio_tram_etp**(integer): Kilometric starting point of occupation of the section.
|
|
|
|
|
|
- **pk_fin_tram_etp**(integer): Kilometric point of end of occupation of the stage section.
|
|
|
|
|
|
- **tipo_vialidad**(string): Description of the road by which the section is affected.
|
|
|
|
|
|
- **cod_vialidad**(string): Identification code of the road by which the section is affected
|
|
|
|
|
|
- **geom**(string): Collection of route meter coordinates.
|
|
|
|
|
|
- **tsinicio**(ZonedDateTime): Test start date.
|
|
|
|
|
|
- **tsfin**(ZonedDateTime): Test end date.
|
|
|
|
|
|
- **evento** (número entero): Name of the event resolved in DGT.
|
|
|
|
|
|
- **timestamp** (Date UTC): Date and time in UTC format of the moment in which the event was generated. It needs to be a maximum of 30 seconds old with respect to UTC time. The date must end with the character 'Z' that marks that it is in UTC.
|
|
|
|
|
|
See more information and a connection example [here](https://gitlab.cs.cmobility30.es/dgt3.0_esp/general/-/wikis/MQTT).
|
|
|
|
|
|
**Note:** *The information that is being published in the development environment is a simulation with non-real information that changes throughout the day, so that the consumption interface can be tested.*
|
|
|
|
|
|
## Errors
|
|
|
|
|
|
As stated above, all HTTP responses other than **200 – OK** can be considered **invalid**. The format of the error response is like the following example:
|
|
|
|
|
|
```json
|
|
|
{
|
|
|
"status": 401,
|
|
|
"code": 1,
|
|
|
"message": "User not found or valid"
|
|
|
}
|
|
|
```
|
|
|
|
|
|
*This does not apply to **Use Case 10 - Sporting Events**. Information regarding errors in that case can be found here.
|
|
|
|
|
|
Estos errores tendrán tres categorías principales:
|
|
|
|
|
|
#### Authentication Error
|
|
|
|
|
|
- HTTP Status: **401 - Unauthorized**
|
|
|
|
|
|
| Code | Message |
|
|
|
| ---- | ----------------------- |
|
|
|
| 1 | User not found or valid |
|
|
|
|
|
|
#### Client Error
|
|
|
|
|
|
- HTTP Status: **400 - Bad Request**
|
|
|
|
|
|
| Code | Message |
|
|
|
| ---- | ------------------------------------------------------------------- |
|
|
|
| 0 | Authenticate |
|
|
|
| 2 | Entity ID not found |
|
|
|
| 3 | Missing required property |
|
|
|
| 4 | The entity received cannot be proccessed |
|
|
|
| 5 | Incorrect token received |
|
|
|
| 6 | Expired token received |
|
|
|
| 7 | There is an error with the token provided. Please request a new one |
|
|
|
| 8 | No token received |
|
|
|
| 9 | Required request body is missing |
|
|
|
| 10 | Event is marked as expired by timestamp |
|
|
|
| 11 | Missing request header |
|
|
|
| 12 | Access denied role |
|
|
|
| 13 | Unique key violated |
|
|
|
| 14 | There is an error in one or more elements |
|
|
|
|
|
|
In the case of obtaining an *error 3 - Missing required property*, the response obtained will have a value in the *message* that will indicate the fields that are missing to be sent:
|
|
|
|
|
|
```json
|
|
|
{
|
|
|
"status": 400,
|
|
|
"code": 3,
|
|
|
"message": "[cityIne: must not be null, parkingId: must not be null, timestamp: must not be null]"
|
|
|
}
|
|
|
```
|
|
|
|
|
|
#### Server error
|
|
|
|
|
|
- HTTP Status: **500 - Internal Server Error**
|
|
|
|
|
|
| Code | Message |
|
|
|
| ---- | -------------- |
|
|
|
| 15 | Internal error | |