Search for content

Results Representation

The response of a Matrix Routing request is composed of arrays and other information.

Depending on what has been set in the options, plain arrays or encoded string are returned.

The following sections explain how to interprete these results.

Plain arrays

Depending on the results parameter, the response contains one or several one-dimensional arrays.
For each combination, origins (i) and destinations (j) the expected result can be found using the formula:

result = i * N + j

with N, the number of destinations.

{
    "distances": [
        0,
        569819,
        571137,
        0
    ],
    "travelTimes": [
        0,
        27720,
        27599,
        0
    ],
    "violationFlags": [
    	false,
    	true,
    	true,
    	false
    ]
}

Encoded strings

For large contents, the use of encoded strings reduce considerably the size of the response. Therefore, it is recommended to use encoded strings for large matrices.

Distances, Travel times and Toll costs

These strings should be interpretated as array of bytes. Each array is composed of contiguous unsigned integers using a 4-bytes little endian scheme.

Please note that the units are:

  • distances in meters
  • travel times in seconds
  • toll costs in cents (hundredth of currency)

 

Travel time profiles

Travel time profiles can only be returned in an encoded format.

The travel time profiles are returned in a compact form as a contiguous array of bytes with the following memory layout (each unsigned integer uses either a 2 or 4-bytes little endian scheme).

Please note that

  • k stands for the number of distance matrix relations which have been requested
  • ni stands for the number of pairs (x,y) returned for the ith function
  • minTravelTimei is the minimum travel time expressed in milliseconds of the ith function
  • the x value is expressed as an offset in minutes from the start time of the horizon.
  • the y value is expressed as an offset in seconds from the minimum travel time of the function.

 

Direct distance and Violation flags

The direct distance and violation flags are returned as contiguous arrays of bytes. Each byte codes up to 8 flags.

Please note that

  • k stands for the number of distance matrix relations which have been requested
  • n stands for the number of bytes necessary to hold the response

Direct distance

If a relation cannot be calculated using the road network, the relation is estimated using the direct distance ; i.e. the distance as the crow flies.
The direct distance and estimated travel time is calculated from the geographical distance using the following fields:

  • detourFactor: the factor that describes the average detour an actual route on the road requires, compared to the geographical distance.
  • averageSpeed: the average speed of the vehicle. It is used to estimate the travel time.

If all relations can be calculated, the percentageOfDirectDistanceRelations is equal to zero.

{
    "percentageOfDirectDistanceRelations": 0
}