The use case7 is dedicated to the publication of areas in which a speed lower than the maximum speed of the road is recommended.
To guarantee the correct operation of the use case, capturing the information of x,y dynamics that arrive at the platform will be tried in order to detect possible congestion zones.
This x,y information will be used to validate information from other use cases, to provide and disseminate recommended speeds and to feed the traffic management information systems of the Dirección General de Tráfico. In any case, this information will always be dissociated and anonymised, so that there will never be any record of the vehicle or driver that is generating this information.
Since the current state of the vehicles does not allow a sufficiently representative data sample to be obtained, this dynamic x,y information is obtained through third-party providers. These providers provide traffic information in real time, using this information, the use case performs the necessary calculations to publish the information on recommended speeds in the areas affected by congestion.
The platform, unlike other use cases, only has the functionality of subscription (reception) of information. This is done through a REST API service, which is described later.
The aforementioned reception functionality requires an access certificate, which must be requested and supplied by DGT 3.0. This certificate, if it has not already been requested, must be requested from soporte@cmobility30.es.
Below are the URLs to access the functionalities of the use case.
Mode | URL | Description |
---|---|---|
Subscription | https://pre.cmobility30.es/use-case-7 | Integration environment endpoint for subscription |
Subscription
This use case has a behavior similar to that offered by Bandeja de Salida that can be found in use case 4. Virtual message board. The API offers an endpoint through which the information on recommended speeds on the different roads and highways is published. This endpoint is shown below and must be accessed by making a GET type request. This request requires meeting the general preconditions described in General · (cmobility30.es).
{baseUrl}/v1/events
En el endpoint se publican las velocidades recomendadas en formato JSON. Aquí se puede ver un ejemplo:
[
{
"properties": {
"lat": 43.358929976820946,
"lng": -4.044689973816276,
"timeStamp": "2022-08-29T13:02:21.037+02:00",
"vialidad": {
"roadDescription": "A-67/Palencia",
"direction": 1,
"affectedLength": 2524.0,
"roadMaxSpeed": 90.0
}
},
"recommendedSpeeds": [
{
"speed": 40,
"kmStart": 0.0,
"kmEnd": 12.399856336374242
},
{
"speed": 50,
"kmStart": 12.399856336374242,
"kmEnd": 27.279683940023332
},
{
"speed": 60,
"kmStart": 27.279683940023332,
"kmEnd": 44.63948281094727
},
{
"speed": 70,
"kmStart": 44.63948281094727,
"kmEnd": 64.47925294914606
},
{
"speed": 80,
"kmStart": 64.47925294914606,
"kmEnd": 86.7989943546197
},
{
"speed": 90,
"kmStart": 86.7989943546197
}
]
},
{
"properties": {
"lat": 43.35894003510475,
"lng": -4.045290034264326,
"timeStamp": "2022-08-29T13:02:21.038+02:00",
"vialidad": {
"roadDescription": "N-611/N-634",
"direction": 0,
"affectedLength": 3083.0,
"roadMaxSpeed": 90.0
}
},
"recommendedSpeeds": [
{
"speed": 60,
"kmStart": 0.0,
"kmEnd": 67.68004816990603
},
{
"speed": 70,
"kmStart": 67.68004816990603,
"kmEnd": 145.02867464979863
},
{
"speed": 80,
"kmStart": 145.02867464979863,
"kmEnd": 232.0458794396778
},
{
"speed": 90,
"kmStart": 232.0458794396778
}
]
}
]
A continuación, se presenta una descripción de cada uno de los campos del JSON anterior. Dicho JSON, publica la información de una congestión concreta así como las velocidades recomendadas en diferentes puntos:
En el documento se publica una lista de carreteras afectadas en las que existe un atasco, cada una de ellas esta formada por un campo properties y recommendedSpeeds. Es decir, cada conjunto de estos dos campos referencia a una carretera diferente con recomendaciones de velocidad diferentes.
-
Properties: Contiene información relativa a la zona afectada.
- Lat: Latitud donde comienza el atasco.
- Lon: Longitud donde comienza el atasco.
- Timestamp(Fecha UTC): Fecha y hora en formato UTC del momento en el que se ha actualizado la información. Puede no coinicidir con la fecha y hora actuales.
-
Vialidad.
- RoadDescription: Nombre de la carretera o carreteras que se ven afectadas.
- Direction: La dirección de la carretera sobre la que se aplica el algoritmo. Puede tener valores 1 (Ascendente) o 0 (Descendente).
- AffectedLength: Longitud, en metros, del tramo en el que actualmente hay una retención. Cuanto mayor sea esta distancia mayor será la distancia entre velocidades recomendadas.
- RoadMaxSpeed: Velocidad máxima de la vía, en Km/h.
-
RecommendedSpeeds: Contiene las velocidades recomendadas en los distintos tramos.
- Speed: Velocidad recomendada.
- kmStart: Punto de inicio de la zona de recomendación. Representa la distancia desde el punto de origen en la que comienza la zona de velocidad recomendada.
- kmEnd: Punto de finalización de la zona de recomendación. Representa la distancia desde el punto de origen en la que finaliza la zona de velocidad recomendada.
Teniendo en consideración los campos anteriores a continuación se muestra un JSON de ejemplo junto con la interpretación del mismo:
"recommendedSpeeds": [
{
"speed": 40,
"kmStart": 0.0,
"kmEnd": 12.399856336374242
},
{
"speed": 50,
"kmStart": 12.399856336374242,
"kmEnd": 27.279683940023332
}
]
Desde el punto en el que se origina el atasco, recordemos que viene dado por los campos lat y lng, (supongamos que en la carretera coincide que es el punto kilométrico 200) hasta el punto kilométrico 212.4, los coches deben circular a una velocidad de 40 Km/h. Desde el punto kilométrico 212.4 hasta el 227.28 los coches deben circular a 50 Km/h. Y así sucesivamente hasta llegar a los 90 Km/h, que en este ejemplo es la velocidad máxima de la vía.
Errores
Todas las respuestas HTTP que no sean 200 – OK, se pueden considerar inválidas. Independientemente del mensaje de error, el formato de la respuesta es como el siguiente ejemplo:
{
"status": 401,
"code": 1,
"message": "User not found or valid"
}
La información relativa a los errores en este caso de uso se puede encontrar aquí. Estos errores tendrán tres categorías principales:
Error de Autentificación
- HTTP Status: 401 - Unauthorized
Code Message 1 User not found or valid
Error de Cliente
- HTTP Status: 400 - Bad Request
Code Message 0 Authenticate 2 Entity ID not found 3 Missing required property 4 Incorrect token received 5 Expired token received 6 There is an error with the token provided. Please request a new one 7 No token received 8 Missing request header 9 Permission denied. Role assigned to user missing 10 There is an error in one or more elements
A continuación se muestra una respuesta de error 5 - Expired token received la cual tendrá el siguiente formato:
{
"status": 400,
"code": 5,
"message": "Expired token received"
}
Error de Servidor
- HTTP Status: 500 - Internal Server Error
Code Message 28 Internal error