Locations

Matrix Routing is a PTV feature to compute distances and travel times matrices.

Origins and Destinations

To compute a matrix, you need to provide some locations.
The locations can be origins and/or destinations.
Destinations are optional. If they are not provided, the service will compute a square matrix (origins x origins).

{
    "origins": [
        {
            "latitude": 49.5915,
            "longitude": 6.1232,
            "includeLastMeters": true
        }
    ]
}

Location Types

The Matrix Routing API supports different location types and attributes in order to support different use cases.

By choosing the appropriate location type the route will actually reach the location off the road or stop on the road close to the location.

Off-road locations

The route from or to an off-road location starts or ends at the given location, and the distance to the match point on the nearest possible road will be included in the route. The travel time for this part is calculated using an average vehicle-specific speed.

This location type should be used when the route ends rather at the front door than at the road, for example for routings from house to house or for delivery services.

{
    "origins": [
        {
            "latitude": 49.612936,
            "longitude": 6.108476,
            "includeLastMeters": true
        }
    ],
    "destinations": [
        {
            "latitude": 49.613063,
            "longitude": 6.109887,
            "includeLastMeters": true
        }
    ]
}

For several exact addresses with street and house number, the Geocoding API provides an additional roadAccessPosition which is on that road from which the house can be accessed. This is not necessarily the nearest road.

{
    "origins": [
        {
            "latitude": 51.540508,
            "longitude": 0.003530,
            "roadAccess": {
                "latitude": 51.540611,
                "longitude": 0.003830
            },
            "includeLastMeters": true
        }
    ],
    "destinations": [
        {
            "latitude": 49.4404499,
            "longitude": 6.4970397,
            "includeLastMeters": true
        }
    ]
}

On-road locations

The route from or to an on-road location starts or ends on the road which is nearest to the given location and which can be used by the selected vehicle.

This location type should be used when the distance from the given location to the match point on the road is not significant, for example when calculating the distance between city centers or click-points on the map.

{
    "origins": [
        {
            "latitude": 49.612936,
            "longitude": 6.108476,
            "includeLastMeters": false
        }
    ],
    "destinations": [
        {
            "latitude": 49.613063,
            "longitude": 6.109887,
            "includeLastMeters": false
        }
    ]
}

Side of street

Prevent the driver from crossing the street

In some use cases, the driver shall not cross the street to reach the destination for delivery or pickup, e.g. for safety reasons. Therefore, it is possible to take into account the side of the street of the route location during the matrix calculation, in order to start or arrive on the same side of the road as the route location.

In this example, the first route has been calculated using a destination without the matchSideOfStreet parameter. It is allowed to cross the street in order to reach the destination as fast as possible.

The second route has been calculated considering the side of the street at which the destination is located. Therefore, it is forbidden to cross the street. The vehicle has to take a detour to be able to reach the destination.

{
    "origins": [
        {
            "latitude": 49.5915,
            "longitude": 6.1232,
            "includeLastMeters": false
        }
    ],
    "destinations": [
        {
            "latitude": 49.5915,
            "longitude": 6.1244,
            "includeLastMeters": false
            "matchSideOfStreet": true
        }
    ]
}