Routing API Developer's Guide

Calculate Matrix

Use the calculatematrix resource to return a matrix of route summaries. The required parameters for this resource are app_id and app_code, mode and a set of start and destination waypoints (start0 to startM and destination0 to destinationN). Other parameters can be left unspecified.

../routing/7.2/calculatematrix.{format}?<parameter>=<value>...
Note: Summaries of routes in the calculatematrix response are computed using algorithms optimized for M:N routes computation. They differ from algorithms used in the calculateroute resource therefore the route summary values may also differ to a certain extent.
Parameter Description
app_id

A 20 bytes Base64 URL-safe encoded string used for the authentication of the client application.

You must include an app_id with every request. To get an app_id assigned to you, please see Acquiring Credentials.

app_code

A 20 bytes Base64 URL-safe encoded string used for the authentication of the client application.

You must include an app_code with every request. To get an app_code assigned to you, please see Acquiring Credentials.

start List of waypoints defining start points of the routes in the matrix. The number of starts in M:N requests is limited to 15. In M:1 requests it is limited to 100.

See also WaypointParameterType.

start0=geo!52.5,13.4
destination List of waypoints defining destinations of the routes in the matrix. The number of destinations in one request is limited to 100. In case of pedestrian mode the number is limited by capacity of the request.

See also WaypointParameterType.

destination0=geo!52.5,13.4
mode The routing mode determines how the route is calculated. Matrix calculation is limited to transport types car, carHOV, truck and pedestrian.

See also RoutingModeType and Avoiding Certain Road Types.

Type;TransportModes;TrafficMode;Feature

mode=fastest;car;traffic:disabled;motorway:-2
searchRange Defines the maximum search range for destination waypoints, in meters. This parameter is especially useful for optimizing matrix calculation where the maximum desired effective distance is known in advance. Destination waypoints with a longer effective distance than specified by searchRange will be skipped. The parameter is optional. In pedestrian mode the default search range is 20 km. If parameter is omitted in other modes, no range limit will apply.
searchRange=10000
avoidAreas Areas which the route must not cross. Array of BoundingBox. Example with 2 bounding boxes:
avoidareas=52.517100760,
13.3905424488;
52.5169701849,
13.391808451!
52.517000760,
13.3700424488;
52.5168701849,
13.371308451
avoidLinks Links which the route must not cross. List of LinkIdType. LinkIdType is a xs:string with the following regular expression restrictions: [*-+]\d+
avoidlinks=-53623477
departure Time when travel is expected to start. Traffic speed and incidents are taken into account when calculating the route. You can use now to specify the current time. Type: xs:dateTime.
departure=2013-07-04T17:00:00+02
When the optional timezone offset is not specified time is assumed to be local.
matrixAttributes Defines which attributes are included in the response as part of the data representation of the route matrix entries. Defaults to indices and summary. See also MatrixRouteAttributeType.

Enum [indices | summary]

summaryAttributes Defines which attributes are included in the response as part of the data representation of the matrix entries summaries. Defaults to costfactor. See also MatrixRouteSummaryAttributeType.

Enum [traveltime | costfactor | distance]

truckType

Truck routing only, specifies the vehicle type. Defaults to truck.

Enum [truck | tractorTruck]

Note: Relevant for restrictions that apply exclusively to tractors with semi-trailers (observed in North America). Such restrictions are taken into account only in case of the truckType set to tractorTruck and the trailers count greater than 0 (for example &truckType=tractorTruck&trailersCount=1). The truck type is irrelevant in case of restrictions common for all types of trucks.
trailersCount

Truck routing only, specifies number of trailers pulled by a vehicle. The provided value must be between 0 and 4. Defaults to 0.

shippedHazardousGoods

Truck routing only, list of hazardous materials in the vehicle. Please refer to the enumeration type HazardousGoodTypeType for available values. Note the value allhazardousGoods does not apply to the request parameter.

Enum [explosive | gas | flammable | combustible | organic | poison | radioActive | corrosive | poisonousInhalation | harmfulToWater | other]

limitedWeight

Truck routing only, vehicle weight including trailers and shipped goods, in tons. The provided value must be between 0 and 1000.

weightPerAxle

Truck routing only, vehicle weight per axle in tons. The provided value must be between 0 and 1000.

height

Truck routing only, vehicle height in meters. The provided value must be between 0 and 50.

width

Truck routing only, vehicle width in meters. The provided value must be between 0 and 50.

length

Truck routing only, vehicle length in meters. The provided value must be between 0 and 300.

tunnelCategory

Truck routing only, specifies the tunnel category to restrict certain route links. The route will pass only through tunnels of a less strict category.

Enum [ B | C | D | E ]

tunnelcategory=C

MatrixRouteAttributeType

Enumeration Short value Description
indices ix Indicates whether StartIndex and DestinationIndex information should be returned in matrix entries in the response. By default indices are returned, they can be omitted though, to reduce response sizes. When omitting indices, matrix entries will be ordered line by line from left to right, i.e. increasing the StartIndex in the outer loop and increasing the DestinationIndex in the inner loop.
summary su Indicates whether summary information should be included in matrix entries in the responses. By default matrix entries will contain the summary. In case of route calculation failure or exceeded search range, matrix entries will contain a status information instead of the summary to indicate why calculating a specific matrix entry failed.

MatrixRouteSummaryAttributeType

Enumeration Short value Description
traveltime tt Indicates whether the travel time information should be provided in summary entries
costfactor cf Indicates whether the CostFactor information should be returned in summary entries.
distance di Indicates whether distance information should be returned in summary entries.