U

Use Case 7

Recommended Speeds

This use case is deprecated.

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

Recommended speeds are published on the endpoint in JSON format. Here an example is shown:

[
    {
        "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
            }
        ]
    }
]

Below is a description of each of the fields in the above JSON. This JSON publishes the information on a specific congestion as well as the recommended speeds at different points:

The document publishes a list of affected roads where there is a traffic jam, each of which is made up of a field properties and recommendedSpeeds. That is, each set of these two fields refers to a different road with different speed recommendations.

  • Properties: It contains information relative to the affected area.
    • Lat: Latitude where the jam starts.
    • Lon: Longitude where the jam starts.
    • Timestamp(UTC Date): Date and time in UTC format of the moment in which the information was updated. It may not match the current date and time.
    • Vialidad.
      • RoadDescription: Name of the road or roads that are affected.
      • Direction: The direction of the road on which the algorithm is applied. It can have values 1 (Ascending) or 0 (Descending).
      • AffectedLength: Length, in meters, of the section in which there is currently a retention. The greater this distance, the greater the distance between recommended speeds.
      • RoadMaxSpeed: Maximum speed of the track, in Km/h.
  • RecommendedSpeeds: It contains the recommended speeds in the different sections.
    • Speed: Recommended speed.
    • kmStart: Starting point of the recommendation zone. Represents the distance from the point of origin at which the advisory speed zone begins.
    • kmEnd: End point of the recommendation zone. Represents the distance from the point of origin at which the advisory speed zone ends.

Taking into consideration the previous fields, an example JSON is shown below along with its interpretation:

"recommendedSpeeds": [
            {
                "speed": 40,
                "kmStart": 0.0,
                "kmEnd": 12.399856336374242
            },
            {
                "speed": 50,
                "kmStart": 12.399856336374242,
                "kmEnd": 27.279683940023332
            }
]

From the point where the traffic jam originates, let us remember that it is given by the fields lat and lng, (let us suppose that the road coincides with kilometer point 200) up to kilometer point 212.4, the cars must circulate at a speed of 40km/h. From kilometer point 212.4 to 227.28, cars must travel at 50 km/h. And so on until reaching 90 km/h, which in this example is the maximum speed of the road.

Errors

All HTTP responses other than 200 – OK, can be considered invalid. Regardless of the error message, the response format is like the following example:

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

Information regarding errors in this use case can be found here. These errors will have three main categories:

Authentication Errors

  • HTTP Status: 401 - Unauthorized
    Code Message
    1 User not found or valid

Client Errors

  • 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

Below is a response of error 5 - Expired token received which will have the following format:

{
    "status": 400,
    "code": 5,
    "message": "Expired token received"
}

Server Errors

  • HTTP Status: 500 - Internal Server Error
    Code Message
    28 Internal error