U

Use case 10

Perimeter marking of sporting events.

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.

V-2 beacons, to track events, and connected cones, that will report the various road closures in the vicinity of the circuit to ensure safety, will be used. 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 sporting events 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.

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:

General · (cmobility30.es)

  • Information regarding the specific methods of the use case:

Publication methods

  • Information regarding the details of the master tables:

Master Tables

Suscription

This use case also has a data subscription (reception) service by companies that so wish through the MQTT protocol. This use case is only for the follow-up services of the sporting events, if you want to subscribe to the information on cone events (road closures) it must be done through the Bandeja de Salida interface that can be found in Use case 4. Virtual message board. 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. It 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. Of the collection of tracking coordinates that is published, the first in the list corresponds to the location of the trailing car, while the last in the list corresponds to the leading car.

    • 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): Identifier of the stage that belongs to a unique sporting event defined by the field idEvento.

    • objectid_1 (integer): Identifier of the section that belongs to a single stage defined by the etapaId field.

    • (*) objectid(integer): Object identifier according to GIS.

    • ddtram_cod(integer): Official identifier of the section in BDC (Base de Datos de Carreteras / Road Database).

    • ddcar_codi(string): Road identifier in BDC (Base de Datos de Carreteras / Road Database).

    • ddcar_deno(string): Road name in BDC (Base de Datos de Carreteras / Road Database).

    • ddtram_den(string): Name of the section in BDC (Base de Datos de Carreteras / Road Database).

    • ddtram_tip(string):Typology of the owner of the section in BDC (Base de Datos de Carreteras / Road Database).

    • ddtram_tit(string): Name of the owner of the section in BDC (Base de Datos de Carreteras / Road Database).

    • ddtram_t_1(string):Typology of the section in BDC (Base de Datos de Carreteras / Road Database).

    • (*) ddtram_lon(integer):Total length of the section in BDC (Base de Datos de Carreteras / Road Database).

    • pk_ini(string): Kilometer starting point of the section and official section in BDC (Base de Datos de Carreteras / Road Database).

    • pk_fin(string): Kilometer point of end of the section and official of the section in BDC (Base de Datos de Carreteras / Road Database).

    • (*) dtipovian(string):Road typology in BDC (Base de Datos de Carreteras / Road Database).

    • ddprov_pro(string): Province of the section in BDC (Base de Datos de Carreteras / Road Database).

    • (*) ddcom_comu(string): Autonomous community of the section in BDC (Base de Datos de Carreteras / 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_leng(numeric): Length of the shape according to coordinates.

    • ddcar_carr(string): Official highway nomenclature in BDC (Base de Datos de Carreteras / Road Database).

    • pk_inicio_tram_etp(integer): Kilometric starting point of occupation of the stage 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 coordinates that represent the total route of the segment being tracked. From the collection of coordinates that is published, the first in the list corresponds to the location where the event starts, while the last in the list corresponds to the location where the event ends.

    • tsinicio(ZonedDateTime): Event start date.

    • tsfin(ZonedDateTime): Event end date.

    • evento (Integer): Name of the event resolved in DGT.

    • timestamp (UTC Date): 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.

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