HERE Routing API 7
In maintenance
Routing API v7 Developer's Guide

# Calculate Matrix

Use the calculatematrix resource to return a matrix of route summaries. The required parameters for this resource are are an apiKey or app_id and app_code if you are using the app_id/app_code authentication (see Acquiring Credentials), 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
apiKey A 43-byte Base64 URL-safe encoded string used for the authentication of the client application. As a logged in user, you can generate it at https://developer.here.com/projects. API Keys never expire but you can invalidate your API Keys at any time. You cannot have more than two API Keys for one app at the same time.

You must include an apiKey with every request. For further details, see Acquiring Credentials.

app_id

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

If you use the app ID/app code option, you need to include an app_id and app_code with every request. For further details, see Acquiring Credentials.

app_code

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

If you use the app ID/app code option, you need to include an app_id and app_code with every request. For further details, 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.

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.

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, bicycle and pedestrian.

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 up to 20 BoundingBox-es. Example with two 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. The list of LinkIdTypes. LinkIdType is a xs:string with the following regular expression restrictions: [*-+]\d+
avoidlinks=-53623477
avoidTurns

List of turn types that the route should avoid. Defaults to empty list. For details on the available values, see the description of the TurnType enumeration type.

Enum [ difficult ]

Note: Currently, truck routing is the only mode that supports the avoidTurns option.
Note: The route always avoids u-turns on single-digitized roads, also when you don't specify the avoidTurns parameter. The exceptions are dead ends and single-digitized roads where u-turns are explicitly permitted by a road sign.
excludeCountries Countries that must be excluded from route calculation. Type: list of common:CountryCodeType.
excludecountries=AUT,CHE
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 | routeId]

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 the 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
speedProfile

Specifies the speed profile variant for a given routing mode. The speed profile affects travel time estimation as well as roads evaluation when computing the fastest route. Note that computed routes might differ depending on a used profile. See SpeedProfileType for details.

Enum [ default | fast ]

speedProfile=fast
Note: Currently, truck routing is the only mode that supports the speedProfile parameter.

## 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.
routeId ri Indicates whether RouteId shall be calculated and provided in summary entries.
Note: Requesting RouteId is known to slow down responses.