Home - dgt30-eng/Use-case-13 GitHub Wiki

Use Case 13 is dedicated to information related to the protection in real time of cyclists circulating on the road network.

Within the DGT 3.0 platform, the following is implemented:

• An interface that allows providers to send information in real time about their users who are riding bicycles on national roads
• Publication of validated information through the outbox interface so that any third party authorized by DGT can consume the real-time location of cyclists to inform users of their applications / vehicles
• The implementation of a logic to validate the information received to avoid problems derived from the inaccuracy of the GPS of the devices when sending their position and incorrect reception of the data.

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.

The publication functionality requires access certificates that must be requested and supplied by DGT 3.0. If these certificates have not already been requested, they should be requested from [email protected].

Everything related to MQTT is temporarily disabled.

Below are the URLs with which each functionality is accessed:

The two functionalities are described below.

This use case has a REST API for the publication (sending) of the data by the companies that request it. Details of this can be found in the following sections:

• General details for making a request:

General · (cmobility30.es)

• The details of the master tables and data that can compose the event:

Master Tables

• The structure of the event can be seen here:

Event

This use case also has a subscription service (reception) to the data for the companies that request it through the MQTT protocol. Below you can find the details of this:

MQTT (MQ Telemetry Transport) is a messaging protocol used as a simple and lightweight method to transfer data to / from low-power devices.

The protocol supports a single messaging pattern, each message is published in a topic to which you must subscribe to receive the information

Subscription to the service of this use case must be through the topic:

out_usecase13_cyclists

In the topic, the events are published in JSON format. Here you can see an example:

{
    "actionId": "f6df58ea71de392c9e783d8b1a4a94f34a3403sdcf1dff660fe31ae7e6beaa1e",
    "timestamp": "2021-03-15T13:34:00.000Z",
    "lonStart": -3.45368,
    "latStart": -4.45368,
    "lonEnd": 40.36586,
    "latEnd": 41.36586,
    "eventTypeId": 2,
}

Description of the fields for the use case of "Cyclists" through the DGT 3.0 platform.

• actionId (Text): Unique identifier of an event.
• 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.
• lonStart (Decimal number): longitude of WGS 84 type coordinates where the event has been generated.
• latStart (Decimal number): latitude of WGS 84 type coordinates where the event has been generated.
• lonEnd (Decimal number): longitude of WGS 84 type coordinates where the event has been generated.
• latEnd (Decimal number): latitude of WGS 84 type coordinates where the event has been generated.
• eventTypeId (Decimal number): Event type identifier

More information and an example connection can be found here.

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:

{
    "status": 401,
    "code": 1,
    "message": "User not found or valid"
}

These errors will have three main categories:

• HTTP Status: 401 - Unauthorized

  Code	Message
  1	User not found or valid

• 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	Permission denied. Role assigned to user missing

In the case of getting an error 3 - Missing required property, the response obtained will have a value in the message that will indicate the missing fields to send:

{
    "status": 400,
    "code": 3,
    "message": "[deviceTypeId: must not be null, deviceUseTypeId: must not be null, informationQualityId: must not be null]"
}

• HTTP Status: 500 - Internal Server Error

  Code	Message
  13	Internal error