Managing Distance Matrices

Distance Matrices are a technical concept to store driving distances and travel times between two locations persistently.

Benefits

Depending on the size of the distance matrix and the routing A route corresponds to a path of a vehicle through the underlying transport network. The main attributes of a route are the distance and the time that the vehicle travels along the path. algorithm, the calculation of a distance matrix can take a reasonable amount of time. Under the following circumstances the reuse of a distance matrix is reasonable:

• A set of locations is used by several optimization services.
• The locations do not change very often.
• High performance routing is not available.

Prerequisites

Please ensure following prerequisites are fulfilled before you start with the use case:

• Installed and licensed PTV xDima Service

Concepts

• Distance Matrices

Programming Guide

The xdima service provides several operations to manage distance matrices from the client side. In order to create a matrix call createDistanceMatrix and pass the origin and destination coordinates. It is possible to further customize the request for example by providing parameters for the estimation of relations that cannot be routed.

var request = {
    "distanceMatrixOptions": {
        "averageSpeed" : 70.0,
        "detourFactor" : 1.43
    },
    "startLocations": [
    {
        "$type": "OffRoadRouteLocation",
        "offRoadCoordinate": {"x": 6.13565, "y": 49.4806576}
    },
    {
        "$type": "OffRoadRouteLocation",
        "offRoadCoordinate": {"x": 6.06479, "y": 49.62127}
    }
    ],
    "destinationLocations": [
    {
        "$type": "OffRoadRouteLocation",
        "offRoadCoordinate": {"x": 6.125657, "y": 49.4816576}
    },
    {
        "$type": "OffRoadRouteLocation",
        "offRoadCoordinate": {"x": 6.16678, "y": 49.455127}
    }
    ]
};

xdima.createDistanceMatrix(request, responseCallback);
            

When a distance matrix is created it is assigned a unique id. This id is returned in the DistanceMatrixSummary and has to be set as id in subsequent requests that refer to this distance matrix. For example, see how the id is used for the operation deleteMatrix below. In order to use a distance matrix for the xtour or xcluster services the id has to be set as field of the distance mode ExistingDistanceMatrix.

The side of the street at which a route location A route location is the position of an object to be routed to or from, which contains additional information on how to link this position to the road network and whether or or not this position is actually reached. Route locations are used as the input for route calculation and optimization throughout PTV xServer. is situated can be considered with the field sideOfStreetRestriction. If two OffRoadRouteLocations have same coordinates but different settings for the field sideOfStreetRestriction, they will be considered as two different locations in the matrix.

With listDistanceMatrices it is possible to list all available matrices and read their features and contents:

var request = {
    "resultFields": {
        "startLocations": true,
        "destinationLocations": true,
        "directDistanceRelations": true,
        "distanceMatrixOptions": true
    }
};

            xdima.listDistanceMatrices(request, responseCallback);
            

Finally deleteDistanceMatrix will delete matrices that are not needed anymore:

var request = {
    "id": response.summary.id
};

xdima.deleteDistanceMatrix(request, responseCallback);
            

The following example shows how to create and calculate dima, list its unresolved relations and delete the dima afterwards:

The following example shows how to get some matrix elements from a distance matrix: