INRIX Interface configuration

The INRIX services are configured in the file optima-configuration.xml.

The descriptions of the parameters is based on XPath syntax.

Prerequisites

Before setting anything, who configures Optima must:

The general INRIX interface settings are defined in:

configurations/configuration[@name='optima']/datex-interface/settings/inrix

Parameter Description

appTokenURL

Contains the current URL associated to the INRIX appToken API.

It can usually be omitted (commonly it is commented in the configuration file).

Required: NO

Default value: https://uas-api.inrix.com/v1/appToken.

The parameters involved into appToken call, are specified by → getAppTokenParams parameter.

bbox

Contains the bottom left and upper right corners of the bounding box used to limit the area of the INRIX XD Segments (XDS) obtained from INRIX API.

Required: NO

If not set, the bounding box to consider is automatically defined accordingly to the network bounds. For this reason, it is not provided a default value .

The bounding box is considered only for the XDS segments request (for the network mapping procedure) and not to request the speeds information.

It is formatted as a CSV string where the first number is the longitude and the second one is the latitude.

Example:

<bbox>
     <bottomLeft>12.36289,41.79238</bottomLeft>
     <upperRight>12.62681,41.99748</upperRight>
</bbox>

bboxRange

Contains a value, measured in degrees, to be added to expand:

  1. The bounding box considered to request the XDS.
  2. The bounding box used to request the INRIX speeds.

Required: NO

Default value: 0

Case 1 (XDS downloading process)

If the bbox parameter is not set, the network bounding box is considered and bboxRange is ignored.

If the bbox parameter is set, bboxRange is always applied.

Case 2 (INRIX speeds downloading process)

The bounding box used is always the one defined according to the network bounds, and bboxRange is always applied.

 

In both cases, it is applied as described:

expanded bbox bottomLeft longitude = bbox bottomLeft longitude - bboxRange
expanded bbox bottomLeft latitude= bbox bottomLeft latitude - bboxRange
expanded bbox upperRight longitude = bbox upperRight longitude + bboxRange
expanded bbox upperRight latitude= bbox upperRigth latitude + bboxRange

getAppTokenParams

Contains the parameters of the HTTP GET request for retrieving the app token used in the data download APIs.

Required: YES

Example:

<getAppTokenParams>
    <param name="appId">a52bacc6-c297-471a-99c8-65e62a5266e1</param>
    <param name="hashToken">1130ac49afc35e786e808238cc4ecc318909ffe3</param>
</getAppTokenParams>

getDataDownload

The status of the submitted download task is checked according with:

  • A specific frequence, indicated in frequency and expressed in seconds.
  • A specific number of attempts, indicated in maxAttempts.

Required: YES

Example:

<getDataDownload>
    <frequency>30</frequency>
    <maxAttempts>5</maxAttempts>
</getDataDownload>

locationRequestParameters

IDs of the geographies for which to request the XDS definition.

Required: YES

Example:

<locationRequestParameters>	
	<geoId>84</geoId>	
	<geoId>86</geoId>
</locationRequestParameters>

See also → How to specify a GeoID number.

loadLocationsFromDbIfTableExists

Contains a boolean value:

  • true: load the INRIX location mapping from the plst table if it contains at least one record with plst.type = inrix

  • false: N.A.

Required: NO

Default value: true

mapDownloadUrl

Contains the current URL used to download the latest INRIX data map.

It can usually be omitted (commonly it is commented in the configuration file).

Required: NO

Default value: https://mapdata.inrix.io/v1/datadownload.

The parameters involved into mapDownload call are specified by the mandatory → getDataDownload parameter.

mapVersionUrl

Contains the current URL used to query the INRIX map version API.

It can usually be omitted (commonly it is commented in the configuration file).

Required: NO

Default value: https://gateway-api.inrix.com/v1/mapversion/?accesstoken=%s.

The string %s, specifies where Optima should place the security token in the URL itself.

segmentXdsFile

When Optima starts, the INRIX interface asks for the last map version of the XD Segments provided by INRIX.

Required: YES

If segmentXdsFile is empty, INRIX XDS file is downloaded via the URL specified in → mapDownloadUrl .

If segmentXdsFile is not empty, INRIX XDS file is loaded (and mapped) from the file /filename.xds specified.

The filename.xds is stored in:

/opt/ptv-optima-as/standalone/deployments/datex-interface.war/WEB-INF/classes.

Example:

<segmentXdsFile>/1.xds</segmentXdsFile>

/opt/ptv-optima-as/standalone/deployments/datex-interface.war/WEB-INF/classes/1.xds.

Example:

<inrix>
      <getAppTokenParams>
			<param name="appId">test-inrix-app-id</param>
			<param name="hashToken">test-inrix-hash-token</param>
      </getAppTokenParams>
      <getDataDownload>
			<frequency>30</frequency>	
			<maxAttempts>5</maxAttempts>
      </getDataDownload>
      <locationRequestParameters>
			<geoId>84</geoId>
			<geoId>86</geoId>
      </locationRequestParameters>
      <segmentXdsFile></segmentXdsFile>
      <bboxRange>0.2</bboxRange>
</inrix>

A GeoID number is generally associated to the area covered in a specific project.

To get the GeoID number you have two alternatives:

  • Ask directly to support team to retrieve a GeoID that fits your area of interest.

  • Use the GetGeography INRIX API documented here.

The inrix_trafficstate_import settings are defined in:

configurations/configuration[@name='optima']/datex-interface/datex-process[@name='Traffic State INRIX']/provider[@name='inrix_trafficstate_import']

Parameter Description

requestBaseUrl

Base URL to get the data.

connectionTimeout

Connection timeout.

0 = wait forever

Unit: seconds

readTimeout

Read timeout.

0 = wait forever

Unit: seconds

speedRequestParameters

Parameters to add to the request used to load speed data.

List of XML elements with the format:
<param name="key">value</param>

maxfunctionalclass

You can filter the data feed based on functional class, to get results faster.

maxfunctionalclass is an indicator of the maximum functional class that must be matched for a traffic flow item included in the response.

All items with functional class lower than or the same as the set value, are included in the response.

Admitted values:

  • 1: a road with high volume, maximum speed traffic.
  • 2: a road with high volume, high speed traffic.
  • 3: a road with high volume traffic.
  • 4: a road with high volume traffic at moderate speeds between neighborhoods.
  • 5: a road whose volume and traffic flow are below the level of any other functional class.

The default value is 5.

Example:

<requestBaseUrl>https://segment-api.inrix.com/v1/segments/speed</requestBaseUrl>
<connectionTimeout>1000</connectionTimeout>
<readTimeout>30000</readTimeout>
<minScore>30</minScore>
<speedRequestParameters>
	<param name="Resolution">100</param>
</speedRequestParameters>
<maxfunctionalclass>5</maxfunctionalclass>

The inrix_trafficstate_save_on_db settings are defined in:

configurations/configuration[@name='optima']/datex-interface/datex-process[@name='Traffic State INRIX']/provider[@name='inrix_trafficstate_save_on_db']

Parameter Description
sqlBefore List of queries to run before writing traffic states to the Optima database.
sqlAfter List of queries to run after writing traffic states to the Optima database.

Example:

<sqlAfter>
    <query>UPDATE trafficstate_inrix_rltm as t set strt_shap = s.shap from strt s where s.idno=t.strt and s.tail=t.fsnd</query>
    <query>UPDATE trafficstate_inrix_rltm as t set ldat = now()</query> -->
</sqlAfter>

Purpose

OpenLR Optimizer is an Optima tool which allows to tune the parameters defined in the OpenLR decoding configuration file OpenLR-Decoder-Properties.xml in order to find the set of parameters that maximizes the defined simple KPI of OpenLR matching.

Service for activating the optimizer tool

The procedure to calculate the optimized parameters is triggered by a POST request:

http:<server>:port/openlroptimizer/matchingoptimisation/create

This service can be reached if the OptimaWSI module and openlr-optimizer-automatic-parameter-tuning.war are deployed.

The body of the request contains the parameters that will be optimized. It must be a JSON and have the following structure:

{
    "parameterList": [{
            "minValue": "0",
            "maxValue": "30",
            "stepVariation": "5",
            "name": "BEARING_DISTANCE"},
           {
            "minValue": "0",
            "maxValue": "1000",
            "stepVariation": "100",
            "name": "MAX_NODE_DISTANCE"
        }]
}

stepVariation is the incremental step used to vary the parameter value from the minimum value (minValue) to the maximum value (maxValue).

In the example, we want to optimize only two parameters: BEARING_DISTANCE and MAX_NODE_DISTANCE.

A full list of the parameters that can be optimized can be found in the file OpenLR-Decoder-Properties.xml:

  • BEARING_DISTANCE
  • MAX_NODE_DISTANCE
  • NODE_FACTOR
  • LINE_FACTOR
  • FRC_VARIANCE
  • MINIMUM_ACCEPTED_RATING
  • MAX_NUMBER_RETRIES
  • SAME_LINE_DEGRADATION
  • CONNECTED_ROUTE_INCREASE
  • DNP_VARIANCE
  • MAX_BEARING_DIFFERENCE

Simple KPI

The KPI defined to evaluate the OpenLR matching is:

where

  • is the number of compliant streets, namely the streets whose matching percentages fall into an interval [minimum-matching,maximum-matching] that defines a “good match”. This interval is defined in the openlr-optimizer.properties configuration file. The following configuration parameters must be set:

    • inrix-enabled=true

    • tomtom-enabled=false

    • minimum-matching=0.1

    • maximum-matching=1.5

  • The matching percentage is defined as the sum of progressives.
  • is the number of open streets as defined in the model.

Process overview

During the parameter optimization process, parameters are optimized one at a time in the order specified by the request, using the optimized values for the previous parameters and the default value (defined in the OpenLR-Decoder-Properties.xml file) for the successive parameters.

Optimizing a parameter

To find the optimum value for a parameter in the interval specified in the request:

  1. The OpenLR matching is executed using a decoding configuration that contains

    • the current value for the parameter to be optimized

    • the optimized values of the previous parameters (according to the order specified in the request)

    • the values defined in OpenLR-Decoder-Properties.xml for the parameters that are not specified in the request

  2. The KPI of the matching is calculated.

These two steps are repeated varying incrementally (from minValue to maxValue) the value of the parameter to be optimized. The optimal value for the parameter is that for which the maximum KPI has been obtained.

Output

The result of the optimization process is not persisted. It is logged in the server.log, as you can see in the following example. You have to copy the optimized values into the OpenLR decoding configuration.

2018-01-10 15:03:42,738 INFO  [optimizer.MatchingOptimizer] (EJB default - 1) Final report for optimization..
2018-01-10 15:03:42,738 INFO  [optimizer.MatchingOptimizer] (EJB default - 1) Parameter named: BearingDistance optimized with value: 25,000000
2018-01-10 15:03:42,738 INFO  [optimizer.MatchingOptimizer] (EJB default - 1) Parameter named: MaxNodeDistance optimized with value: 500,000000
2018-01-10 15:03:42,738 INFO  [optimizer.MatchingOptimizer] (EJB default - 1) Parameter named: NodeFactor optimized with value: 2,000000
2018-01-10 15:03:42,738 INFO  [optimizer.MatchingOptimizer] (EJB default - 1) Parameter named: LineFactor optimized with value: 3,000000
2018-01-10 15:03:42,738 INFO  [optimizer.MatchingOptimizer] (EJB default - 1) Parameter named: FRC_Variance optimized with value: 0,000000
2018-01-10 15:03:42,738 INFO  [optimizer.MatchingOptimizer] (EJB default - 1) Parameter named: MinimumAcceptedRating optimized with value: 300,000000
2018-01-10 15:03:42,738 INFO  [optimizer.MatchingOptimizer] (EJB default - 1) Parameter named: MaxNumberRetries optimized with value: 16,000000
2018-01-10 15:03:42,738 INFO  [optimizer.MatchingOptimizer] (EJB default - 1) Parameter named: SameLineDegradation optimized with value: 0,000000
2018-01-10 15:03:42,738 INFO  [optimizer.MatchingOptimizer] (EJB default - 1) Parameter named: ConnectedRouteIncrease optimized with value: 0,000000
2018-01-10 15:03:42,738 INFO  [optimizer.MatchingOptimizer] (EJB default - 1) Parameter named: DNPVariance optimized with value: 80,000000
2018-01-10 15:03:42,738 INFO  [optimizer.MatchingOptimizer] (EJB default - 1) Parameter named: maxBearingDifference optimized with value: 0,000000