MLF API

Returns the MLF forecast, for all streets involved, covering the interval:

[Request Timestamp, Request Timestamp + 1 hour].

Request Timestamp is the time instant associated to the API call.

The MLF API requires the configuration of the file:

/opt/ptv-optima-as/standalone/configuration/optima/optima-configuration.xml

Two specific tags must be configured:

<mlf>
<proxy>

<mlf> tag

Select the tag <configuration>/<mlf> of the file optima-configuration.xml.

Property	Type	Description
mlf	Object	Contains two tags: <customerId>: In a scalable multi-tenant environment (as a service context), the customerId is used to identify the "tenant". It is a free string, built with letters, numbers and dashes. It's a best practice to use a UUID in its hexadecimal representation with dashes, as indicated here. The Optima on-premise context is a single-tenant context. If TRE needs to be connected to the MLF service, the parameter → Traffic data parameters > CustomerID must be set to the customerId value. <serverHost>: It is the URL where the MLF service is responding.

Property

Type

Description

mlf

Object

Contains two tags:

<customerId>:

In a scalable multi-tenant environment (as a service context), the customerId is used to identify the "tenant".
It is a free string, built with letters, numbers and dashes. It's a best practice to use a UUID in its hexadecimal representation with dashes, as indicated here.
The Optima on-premise context is a single-tenant context.

If TRE needs to be connected to the MLF service, the parameter → Traffic data parameters > CustomerID must be set to the customerId value.

<serverHost>: It is the URL where the MLF service is responding.

Example:

<mlf>
     <customerId>4b0e2501-bfa3-49f9-8c7b-5d75f6cf12d7</customerId>
     <serverHost>https://mlf01
</mlf>

<proxy> tag

Select the tag <configuration>/<proxy> of the file optima-configuration.xml.

Property	Type	Description
proxy	Object	The <url> tag contains the URL of the proxy associated to the MLF service. Here you can make use of Apache Common Expression.

Property

Type

Description

proxy

Object

The <url> tag contains the URL of the proxy associated to the MLF service.

Here you can make use of Apache Common Expression.

Example:

<proxy>
       <mlf>
            <url>${configuration[@name='optima']/mlf/serverHost}/mlf-api-processing-api/ml-forecast/public/forecast/realtime</url>
       </mlf>
</proxy>

Authentication phase

Before using the endpoint, you must run the authentication phase (→ Login).

After the authentication, a session opens and a valid session token persists until:

The end of the session time-out, that is set through the parameter sessionTimeout (→ OptimaWSI configuration > OptimaAuth section).
An explicit Logout call (→ Logout).

Request

GET

https://<OPTIMA_HOST_IP_ADDRESS>:<PORT_NUMBER>/optima-wsi/ml-forecast/forecast/realtime

Request parameters

Not applicable.

Request content-type

Not applicable

Request body (payload)

Not applicable

Response

Response status

HTTP status	Description
200 OK	Result of the processed request. Even empty results.
204 Bad request	Generally returned when data are not available.
400 Bad request	Several conditions can be classified under this code. Generally, when the API has been called with wrong arguments.
404 Not found	Result of the processed request. For example, in case of a missing street or a missing link.
500 Internal server error	Several conditions can be classified under this code.
503 Service Unavailable	The server cannot handle the request (because it is overloaded or down for maintenance). Generally, this is a temporary state.

Response content-type

application/x-protobuf

Response output

A binary file containing the forecast.

It can be deserialized via the forecast_data_message.proto file:

//model.statistical_forecast 

syntax = "proto3"; 
 
import "google/protobuf/timestamp.proto"; 
 
package com.ptvgroup.mlf.common.messagehandling.forecast; 
 
 message ForecastData { 
 
    message StreetForecast {   
        int32 id=1;   
        int32 fromNode=2;   
        repeated Forecast forecast=3;
		string openLRcode=4;  
    }  
 
    message Forecast { 
        google.protobuf.Timestamp start=1; 
        google.protobuf.Timestamp end=2; 
        bool flow_valid=3; 
        double flow=4; 
        bool speed_valid=5; 
        double speed=6; 
        string timezone=7; 
    } 
 
    repeated StreetForecast streetForecast=1; 
  
 }

To start the deserialization procedure, insert in your selected folder X:

The MLF API binary file response.bin
The forecast_data_message.proto file (as above)

At this point, run the command inside folder X:

On Windows:

protoc.exe   --decode=com.ptvgroup.mlf.common.messagehandling.forecast.ForecastData  
forecast_data_message.proto < response.bin

On Linux:

protoc   --decode=com.ptvgroup.mlf.common.messagehandling.forecast.ForecastData  
forecast_data_message.proto < response.bin

Important: This example makes reference to protoc (Protobuf standard) version 27.2, downloadable here. As new versions of Optima are released over time, you can always find the corresponding file here (right-click to download).

The resulting output file is in .txt format and can be found in the same folder X.

Example: response code 200

Request

https://<OPTIMA_HOST_IP_ADDRESS>:<PORT_NUMBER>/optima-wsi/ml-forecast/forecast/realtime

Response status

HTTP status	Description
200 OK	Result of the processed request.

Response output

The output is in deserialized format .txt:

streetForecast { 
  id: 1567666 
  fromNode: 225909 
  forecast { 
    start { 
      seconds: 1657287522 
    } 
    end { 
      seconds: 1657291122 
    } 
    speed_valid: true 
    speed: 40.75 
    timezone: "Europe/Amsterdam" 
  } 
} 
streetForecast { 
  id: 1567666 
  fromNode: 237654 
  forecast { 
    start { 
      seconds: 1657287522 
    } 
    end { 
      seconds: 1657291122 
    } 
    speed_valid: true 
    speed: 40.833332061767578 
    timezone: "Europe/Amsterdam" 
  } 
} 
streetForecast { 
  id: 1567668 
  fromNode: 253484 
  forecast { 
    start { 
      seconds: 1657287522 
    } 
    end { 
      seconds: 1657291122 
    } 
    speed_valid: true 
    speed: 40.833332061767578 
    timezone: "Europe/Amsterdam" 
  } 
}

Example: response code 400

Request

https://<OPTIMA_HOST_IP_ADDRESS>:<PORT_NUMBER>/optima-wsi/ml-forecast/forecast/realtime

Response status

HTTP status	Description
400 Bad request	Several conditions can be classified under this code. Generally, when the API has been called with wrong arguments.

HTTP status

Description

400 Bad request

Several conditions can be classified under this code.

Generally, when the API has been called with wrong arguments.

Response output

{
  "traceId": "string",
  "errorId": "string",
  "description": "string",
  "errorCode": "string",
  "causes": [
    {
      "description": "string",
      "errorCode": "string",
      "parameter": "string",
      "details": {
        "additionalProp1": {},
        "additionalProp2": {},
        "additionalProp3": {}
      }
    }
  ],
  "details": {
    "additionalProp1": {},
    "additionalProp2": {},
    "additionalProp3": {}
  }
}

Example: response code 503

Request

https://<OPTIMA_HOST_IP_ADDRESS>:<PORT_NUMBER>/optima-wsi/ml-forecast/forecast/realtime

Response status

HTTP status	Description
503 Service Unavailable	The server cannot handle the request (because it is overloaded or down for maintenance). Generally, this is a temporary state.

Response output

{
  "traceId": "string",
  "errorId": "string",
  "description": "string",
  "errorCode": "string",
  "causes": [
    {
      "description": "string",
      "errorCode": "string",
      "parameter": "string",
      "details": {
        "additionalProp1": {},
        "additionalProp2": {},
        "additionalProp3": {}
      }
    }
  ],
  "details": {
    "additionalProp1": {},
    "additionalProp2": {},
    "additionalProp3": {}
  }
}