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.
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:
- Information regarding the specific methods of the use case:
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:
[
{
"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": {
"idEvento": 1,
"idEtapa": 123,
"objectid_1": 123123,
"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,
"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"
}
}
]
Description of the fields for the use case of "Eventos deportivos" through the DGT 3.0 platform. Publish the geometric information of the event along with its roads, pk and passing times:
(*)= Field that may not appear in the posted JSON
-
type (string): Feature Identifier.
-
geometry: Collection of coordinates that represent the result of tracking a sports event. This collection of coordinates will be contained in the collection represented by the geom field of this same JSON document
-
type(string): Geometry type identifier.
-
coordinates: Routemeter Coordinate Collection.
-
-
properties: Schema properties for the publication of sporting events.
-
eventoId (integer):Sporting event identifier.
-
etapaId (integer): Identificador de la etapa que pertenece a un evento deportivo único definido por el campo idEvento.
-
objectid_1 (integer): Identificador del tramo que pertenece a una etapa única definida por el campo etapaId.
-
(*) objectid(integer): Identificador del objeto según GIS.
-
ddtram_cod(int): Identificador oficial del tramo en BDC (Base de Datos de Carreteras)
-
ddcar_codi(string): Identificador de la carretera en BDC (Base de Datos de Carreteras)
-
ddcar_deno(string): Denominación de carretera en BDC (Base de Datos de Carreteras)
-
ddtram_den(string): Denominación del tramo en base de datos de carreteras
-
ddtram_tip(string):Tipología del titular del tramo en bases de datos de carreteras
-
ddtram_tit(string): Nombre del titular del tramo en bases de datos de carreteras
-
ddtram_t_1(string):Tipología del tramo en base de datos de carreteras
-
(*) ddtram_lon(integer):Longitud total del tramo en base de datos de carreteras
-
pk_ini(string): Punto kilométrico de inicio del tramo y oficial del tramo en base de datos de carreteras.
-
pk_fin(string): Punto kilométrico de fin del tramo y oficial del tramo en base de datos de carreteras.
-
i(*) dtipovian(string): Tipología de la carretera en Bases de datos de carreteras
-
ddprov_pro(string): Provincia del tramo en base de datos de carreteras
-
(*) ddcom_comu(string): Comunidad autónoma del tramo en base de datos de carreteras
-
(*) color(string): Color de vía segun GIS para mapamovilidad.es
-
(*) pkinigis(integer): Punto kilométrico de inicio del tramo según el GIS.
-
(*) pkfingis(integer): Punto kilométrico de fin del tramo según GIS.
-
(*) shape_leng(numeric): Longitud de la forma según coordenadas
-
ddcar_carr(string): Nomenclatura oficial de la carretera en base de datos de carreteras
-
pk_inicio_tram_etp(integer): Punto kilométrico de inicio de ocupación del tramo
-
pk_fin_tram_etp(integer): Punto kilométrico de fin de ocupación del tramo etapa
-
tipo_vialidad(string): Descripción de la vialidad por la que se ve afectado el tramo
-
cod_vialidad(string): Código identificativo de la vialidad por la que se ve afectado el tramo
-
geom(string): Colección de coordenadas que representan la ruta total del tramo sobre el que se está haciendo el seguimiento.
-
tsinicio(ZonedDateTime): Fecha de inicio de la prueba.
-
tsfin(ZonedDateTime): Fecha de fin de la prueba.
-
evento (número entero): Denominación del evento resuelto en DGT
-
timestamp (Fecha UTC): Fecha y hora en formato UTC del momento en el que el evento se ha generado. Es necesario que sea de un máximo de 30 segundos de antiguedad con respecto a la hora UTC.
See more information and a connection example here.
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.nevertheless, certain API methods can reply with code 202 - ACCEPTED along with a description indicating the reason for acceptance.Regardless of whether the message code is 202 or an error code, the format of the error response is like the following example:
{
"status": 401,
"code": 1,
"message": "User not found or valid"
}
Partially satisfactory responses
-
HTTP Status: 202 - Accepted
Code Message 27 One more Beacon is expected in order to do the dynamic tracking
Information regarding errors in this use case can be found here. These errors will have three main categories:
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 15 Invalid GeoJson 16 GeoJson does not belong to municipality 17 TimestampStart should be future 18 TimestampEnd should be future 19 TimestampStart should be before TimestampEnd 20 The type is not a cone 21 Cone use type has to be Infrastructure 22 Cone vehicle type has to be None 23 The beacon type must have value 4 (Unique) 24 The plan requested to track was not found 25 The event requested to track has not started yet or has already finished 26 The provided coordinates for both dynamic tracking beacons are exactly the same
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:
{
"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