The Matrix Routing service is an HTTP JSON API that calculates routing matrices of up to 10,000 origins and 10,000 destinations.
A routing matrix is a matrix with rows labeled by origins and columns by destinations. Each entry of the matrix is travel time or distance from the origin to the destination.
The Matrix Routing service provides the following features:
- Large number of origins and destinations (up to 10,000)
- Live traffic and historical speed patterns
- Car, Truck, Pedestrian, Bicycle and Taxi modes
- Truck attributes such as dimensions, weight, tunnel restrictions and more
- Avoiding areas and routing features, e.g., toll roads, ferries and motorways.
- Choice between synchronous and asynchronous APIs for flexible result downloads
To calculate a routing matrix, you provide the following information to the service:
- A list of origins and destinations, specified using geographic coordinates.
- Either a geographical region which contains the coordinates and inside of which the routes will be calculated (see Region), or a profile which enables calculation of routes with arbitrary length but has only a predefined set of options available (see Profiles). Matrix requests of routes with arbitrary length and custom options are only available for matrices with a maximum size of 15x100 or 100x1.
See Modes for a more detailed description of when to use a specific region or a predefined profile. For the full API specification, see the API Reference.
Access to the Routing service in Japan region is restricted. If your business requires this, please contact HERE.
Taxi mode is in alpha state. It is not yet stable and behavior may change drastically, or even become unsupported, without warning.
Some notable abilities and limitations of the service are:
- The service is particularly suitable for a large number of origins and destinations - it can compute matrices up to 10,000 x 10,000. The matrices don't have to be square. For example, you might want to compute the distances from one origin to several destinations.
- To enable custom options and dynamic traffic, the origins and destinations should be confined to a specific region, defined in the matrix request. The region can be a bounding box, polygon or circle with a maximum diameter of 400 km. It can be derived automatically from the provided origins and destinations. See Region.
- To compute matrices with routes of arbitrary length without limitation of 400 km diameter region, the service offers a set of predefined profiles. These do not allow to modify any options and compute matrices using free-flow speed based on historical traffic. See Profiles.
- Alternatively, it's possible to compute matrices with routes of arbitrary length without specifying a profile, but only when the matrix size does not exceed 15x100 or 100x1. See Modes.
- The matrix calculation can be done for cars, trucks, pedestrians, bicycles or taxis. When in truck mode, the matrix calculation can take into account special parameters, like the weight and height of the truck. See Truck Parameters.
- Traffic information can be taken into account during the matrix calculation. Depending on departure time, either live traffic or historical traffic patterns are used. See Traffic. Note that this feature is available only for modes where a predefined profile is not specified.
Matrix size limitations
Note that in this document, when we say that a feature is available for matrices with a maximum size of N x M, that means that the number of origins must not exceed N and that the number of destinations must not exceed M. For example, if the maximum is defined as 15 x 100, a 16 x 50 matrix is over that limit.
For the available authentication options, see the Identity & Access Management Developer Guide.
When submitting bug reports and asking for support for specific matrix calculations, always provide the
matrixId and the corresponding
errorCode, if any.