Submit matrix for calculation

post

https://matrix.router.hereapi.com/v8/matrix

Calculates a routing matrix based on provided origins and destinations.

Response will be provided synchronously (see 200 response) or asynchronously (see 202 response) depending on the async query parameter.

Travel times will be included by default i.e., when matrixAttributes parameter is not specified. For other supported attributes, the corresponding flags must be specified in matrixAttributes.

Maximum request size is 10 MiB (uncompressed).

Query Params

async

boolean

Defaults to true

Specifies whether the response will be provided synchronously (false) or asynchronously (true). See Synchronous vs. Asynchronous Requests.

Body Params

origins

array of objects

required

length between 1 and 10000

List of waypoints defining origins of the routes in the matrix.

NOTE: Maximum number of matched waypoints on a single segment is limited to 100, including both origins and destinations. For requests where only origins are specified, the origins list is also used as destinations, thus limiting the number of origins to 50 in such a request.

origins*

destinations

array of objects

length between 1 and 10000

List of waypoints defining destinations of the routes in the matrix. When no destinations are specified, the matrix is assumed to be quadratic with origins used as destinations.

NOTE: Maximum number of matched waypoints on a single segment is limited to 100, including both origins and destinations.

destinations

regionDefinition

required

Definition of a region in which the matrix will be calculated.

Only the data inside of the region will be used for the calculation of the matrix. All origins and destinations outside of the region are considered as invalid. The corresponding values in the response matrix will be undefined.

If the region diameter is too large (cf. corresponding limits), the calculation will not be done and an error will be returned by the service.

The special variant world is used to enable calculation of matrices with routes of arbitrary length. Additionally, a profile can be selected from the list of supported predefined profiles. For more information, refer to the documentation of the profile request parameter.

profile

string

enum

A profile ID enables the calculation of matrices with routes of arbitrary length.

A profile comes with a set of predefined options. It is not possible to override them. All profiles explicitly set departureTime to any and require that the obligatory request parameter regionDefinition is set to world.

Profile ID	Description
`carFast`	Car with fast routing mode
`carShort`	Car with short routing mode
`truckFast`	Truck with fast routing mode
`pedestrian`	Pedestrian transport mode
`bicycle`	Bicycle transport mode

For the precise definition of a profile use the profiles/{profileId} endpoint, which returns the routing options predefined for the profile.

It is guaranteed that with each minor API change profiles are only added to the above list, but are never removed or modified. Profile IDs are case-sensitive.

The only request parameters permitted in combination with profile are the required parameters origins and regionDefinition, and the optional parameters destinations and matrixAttributes.

Allowed:

departureTime

string

Time of departure at all origins, in ISO 8601 (RFC 3339) format: the time zone offset is required, e.g., 2025-08-06T11:20:00+02:00

When departureTime is not specified, it is implicitly assumed to be the current time. The special value any enforces non time-aware routing.

In particular, dynamic traffic information is not taken into account in this case and only free-flow speeds based on historical traffic are applied.

arrivalTime

string

Time of arrival at a destination, in ISO 8601 (RFC 3339) format: the time zone offset is required, e.g., 2025-08-06T11:20:00+02:00

arrivalTime can not be used together with departureTime.

Note: This parameter can only be used for N x 1 matrix (multiple origins, single destination) calculation in flexible mode.

routingMode

string

enum

Defaults to fast

Specifies which optimization is applied during the calculation.

fast: Route calculation from start to destination optimized by travel time. In many cases, the route returned by fast mode may not be the route with the fastest possible travel time. For example, the routing service may favor a route that remains on a highway, even if a faster travel time can be achieved by taking a detour or shortcut through an inconvenient side road.
short: Route calculation from start to destination disregarding any speed information. In this mode, the distance of the route is minimized, while keeping the route sensible. This includes, for example, penalizing turns. Because of that, the resulting route will not necessarily be the one with minimal distance.

Notes:

The following Transport modes only support fast routingMode
- bicycle
- bus
- pedestrian
- privateBus
- scooter
- taxi

Allowed:

transportMode

string

enum

Defaults to car

Depending on the transport mode special constraints, speed attributes and weights are taken into account during route calculation.

car: Route calculation for cars.
truck: Route calculation for trucks. This mode considers truck access- and physical limitations. It also uses different speed assumptions when calculating the route.
pedestrian: Route calculation for pedestrians.
bicycle: Route calculation for bicycles.
taxi: Route calculation for taxis. This mode takes into account taxi restricted streets as well as streets reserved for exclusive taxi access. It does not, however, consider exclusive lanes in otherwise shared streets. Also, the taxi exclusive streets are used only if either the origin or destination are on them.
scooter: Route calculation for scooters. This mode takes into account roads that are allowed for scooters, however dedicated scooter lanes are not supported. It does not consider highways, unless the special parameter allowHighway is provided.
bus: Route calculation for buses that are allowed to drive through the bus-only roads.
privateBus: Route calculation for buses that are not allowed to drive through the bus-only roads.

Note: bicycle, bus and privateBus modes are currently provided as Beta, with limited functionality. Please refer to the Developer Guide for more details here.

avoid

object

Avoid routes that violate these properties.

allow

object

Explicitly allow features that require users to opt in.

maxSpeedOnSegment

array of objects

Segments with restrictions on maximum baseSpeed.

Notes: Maximum amount of penalized segments in one request cannot be greater than 1000. "Penalized segments" refers to segments that have a restriction on maximum baseSpeed with maxSpeedOnSegment or are avoided with avoid[segments]

maxSpeedOnSegment

exclude

object

Defines properties which will be strictly excluded from route calculation.

Note - Exclude options guarantees exclusion, but doesn't guarantee finding a route.

vehicle

object

Different vehicle options to use during route calculation.

EV properties to be used only when requesting consumptions in matrixAttributes.

There are two consumption models (empirical, physical). Set the consumptionModel parameter to choose which model to use.

Required empirical model properties:

freeFlowSpeedTable

Required physical model properties:

driveEfficiency
recuperationEfficiency

When using the physical model, certain properties of the vehicle parameter are also required (see documentation for the vehicle parameter for more details):

rollingResistanceCoefficient
airDragCoefficient
currentWeight
frontalArea or combination of width and height

truck

object

deprecated

Renamed to vehicle

truckOptions

object

deprecated

Renamed to truck

scooter

object

Specific scooter options to use during route calculation when transportMode = scooter.

pedestrian

object

Specific pedestrian options to use during route calculation when transportMode = pedestrian.

taxi

object

Specific taxi options to use during route calculation when transportMode = taxi.

matrixAttributes

array of strings

Defaults to travelTimes

Defines which attributes are included in the response as part of the data representation of the matrix entries summaries. See ev and vehicle parameters for additional attributes to specify to calculate consumptions.

Notes:

The attribute consumptions cannot be used together with profile parameter.
Requesting all three attributes is supported for matrix sizes up to 1000 x 1000.

traffic

object

Traffic specific parameters.

violationMapping

array of objects

length ≤ 10

List of items for mapping certain violated restrictions to specific error codes in the matrix. This mapping can classify restrictions or blockages while still providing the resulting times and distances in the calculated matrix. Items are grouped into categories and evaluated collectively. Error codes are associated with the category, rather than being tied to individual restrictions or blockages.

There are three distinct types of mappings:

violated restrictions
traffic-related blockages
violations when avoiding areas or individual segments

These mappings must be maintained as separate violation mapping items, although they can belong to the same category.

A violation mapping type can support additional parameters defining how a particular violation should be managed. There are three settings for these parameters:

include: the violated restriction is added to a mapped category instead of causing a hard error code 3.

exclude: the violated restriction is not added to a mapped category and still causes an error code 3. This is the default for height and grossWeight.

ignore: the algorithm is not taking the restriction or property / attribute of the road into consideration. This is the default attribute for restrictions on bridge or time-dependent restrictions.

The parameters for each mapping type are listed in the respective schema.

Examples for mappings of different types as category 1:

map violations with violated height and violated grossWeight:
{ "category": 1, "type": "restriction", "grossWeight": "include", "height": "include" }
map violations with violated height and NOT violated grossWeight:
{ "category": 1, "type": "restriction", "height": "include", "grossWeight": "exclude" }
map violations with violated height, violation or non-violation of grossWeight doesn't matter:
{ "category": 1, "type": "restriction", "height": "include", "grossWeight": "ignore" }
map violations with violated height and violated currentWeight:
{ "category": 1, "type": "restriction", "height": "include", "currentWeight": "include" }
map violations with violated height and NOT violated currentWeight:
{ "category": 1, "type": "restriction", "height": "include", "currentWeight": "exclude" }
map violations with violated height, violation or non-violation of currentWeight doesn't matter:
{ "category": 1, "type": "restriction","height": "include", "currentWeight": "ignore" }
map violations of avoiding an area or a segment:
{ "category": 1, "type": "avoidAreasAndSegments" }
map violations of traffic-related blockages outside of bridges:
{ "category": 1, "type": "traffic", "bridge": "exclude" }

Unless include or exclude is stated, grossWeight or height can be mapped regardless, if it is timeDependent or on a bridge. Please see matrix description in the response section for more information about error codes.

If additional types of restrictions are supported for mapping in the future, they will default to "ignore" to ensure consistent results.

A violation mapping item belongs to either of two categories.

Mappings of type traffic or avoidAreasAndSegments are only supported for transport modes car and truck.

violationMapping

Headers

X-Request-Id

string

User-provided token that can be used to trace a request or a group of requests sent to the service.

Responses

200

Result matrix was calculated for the requested origins and destinations.

The matrix contains 3 optional flat arrays, travelTimes, distances, and consumptions depending on the specified matrixAttributes request parameter. Each array represents a 2D matrix where rows correspond to origins and columns to destinations. The k-th position in the array corresponds to the (i, j) position in the matrix defined by the following relationship:

k = num_destinations * i + j,

where i is origin and j is destination.

If the calculation of a route between i and j fails or yields a route that violates some options, the response includes another errorCodes array with a detailed error code for each failed calculation.

If the error code for the entry (i, j) is not 0 (success) or 3 (violated options) then the value for the entry (i, j) in the travelTimes and distances response array(s) is unspecified; the client using the response should not rely on the value of the entry (i, j) in the response array(s) in this case. For the list of supported error codes cf. errorCodes.

If the calculation of the entire matrix failed due to an expected error, e.g. timeout, the matrix field is none and the error field contains a detailed error description.

202Matrix calculation was successfully submitted.

400Matrix request contains invalid parameters.

401Authentication failed.

403Access denied.

413Payload too large. We support max. 10 MB (uncompressed).

429Too many requests.

500Unexpected service error.