Introduction
We’re very excited to announce and present a new set of HERE Location Services that are leveraging the HERE platform and can be easily accessed through our Developer Portal at developer.here.com. These newly released versions of HERE Location Services provide a unified API framework, while leveraging the HERE platform, making it easy and efficient for any customer to adopt the breadth of our Location Services offering and beyond. As a customer of our Location Services you can now benefit from a set of redesigned and aligned APIs, as well as a streamlined architecture with compatibility across all location services, as they’re sharing the same HERE map data, authentication and authorization methods as well as API specification. In addition, the newly released HERE Location Services are leveraging fresher map content through higher map update frequency and faster availability of new regions (e.g. such as the recently integrated high detail map of Japan) realized today through the HERE platform.
With the new service framework in place, we are also on our way to delivering new functionalities that will only become available through the newly released HERE Location Services.
All our customers today can benefit from these new features and capabilities when accessing the newest versions of the HERE Location Services. If you’re already using token or API key authentication, then no change regarding access credentials is needed. If however, you’re still using app_id and app_code, please check out the documentation posted at https://developer.here.com/documentation/identity-access-management where you will find information on how to create and use new credentials.
We hope you are as excited as we are! We encourage all our customers to explore and evaluate our new services while getting themselves familiarized with the new features and functions they have to offer.
The new Matrix Routing API v8 is offered as a unified routing service for all matrix sizes. Additionally it has support for the following:
- Up to 10k x 10k elements (origins x destinations)
- Bicycle mode
- Service offering also in geography of Japan
For full details see Matrix Routing v8 Developer Guide and API Reference.
Migrate from Routing Services v7 to Routing Services v8
HERE's Routing v7 services are planned to be deprecated over the course of the next few months and the services are in maintenance mode. This guide is provided to help users of the Matrix Routing v7 service to switch to using the Matrix Routing v8 service for their applications.
Preparation
The following general actions must be taken to complete the migration:
- change authentication method (if applicable)
- update request parameters
- update handling of the new output format
Note
There are some input as well as output parameters that are no longer supported due to conceptual changes. These are detailed in this guide.
Authentication
For more information on the available usage plans and limits, see Pricing and Plans.
Migrate from Matrix v7 to Matrix Routing v8
This document highlights the most important changes necessary to migrate to the new version of the Matrix Routing service (v8). For full details, see the Matrix Routing v8 Developer Guide and API Reference.
Conceptual Changes
Synchronous vs asynchronous request
All Matrix Routing v7 requests are synchronous. Matrix Routing v8 offers a choice between synchronous and asynchronous request types. See the Matrix Routing v8 Developer Guide for more information.
Flexible, Region and Profile Modes
Matrix Routing v8 offers three modes: Flexible, Region and Profile. Flexible mode corresponds to Matrix Routing v7, while Region and Profile modes add the capability of calculating much bigger matrices, up to 10,000 origins and destinations. Learn more about these modes in Matrix Routing v8 Developer Guide.
GET vs POST Request
Matrix Routing v7 mainly used the GET method. The only exception was the possibility to send origin and destination points in a POST request body. In Matrix v8 all parameters must be placed in a POST request body. Only the async
parameter and some authentication parameters are expected to be part of the URL.
Migration of the Calculate Matrix Request
This section covers the actions that must be taken to migrate a v7 Calculate Matrix request to a v8 Matrix Routing request.
For more details about the types or specification of parameters, see the Developer Guide.
Request
This section describes changes in the request.
Parameters Added
regionDefinition
and profile
These parameters define which mode of Matrix Routing v8 will be used. See available modes in Developer Guide For example: to use Flexible mode, which corresponds to Matrix Routing v7, use world
as a value for regionDefinition
, and do not provide any profile
.
Parameters Changed
The following parameters are changed in this migration.
Base URL, Version, Resource
Parameter | Matrix Routing v7 | Matrix Routing v8 |
Base URL | string, https://matrix.route.api.here.com | string, https://matrix.router.hereapi.com |
Version | string, routing/7.2 | string, /v8 |
Resource | string /calculatematrix.json | string, /matrix |
mode
split into routingMode
, transportMode
, and avoid[features]
This migration splits the mode
parameter (v7) into a few separate specific options (v8). For RouteFeatureType
and RouteFeatureWeightType
, use avoid[features]
. The options (-1 and -3) were not providing sufficient value or user experience according to usage statistics and feedback, therefore v8 offers only the equivalent of RouteFeatureWeightType=-2
(softExclude
).
Traffic is used in Route calculations by default, unless departureTime
is set to any
, so TrafficMode
is no longer offered as a separate option. In v7, the setting looks like mode=<routingMode>;<transportMode>;<trafficMode>;<RouteFeatureType>=<RouteFeatureWeightType>
For individual parameters in v8, see below.
| Matrix Routing v7 | Matrix Routing v8 |
Parameter | mode=<routingMode> | routingMode |
Format | string, one of fastest ,shortest , balanced | string, one of fast ,short |
Behavior | Sets the routing mode. | Sets the routing mode. |
Note | | balanced mode is no longer offered. |
| Matrix Routing v7 | Matrix Routing v8 |
Parameter | mode=;<transportMode> | transportMode |
Format | string, one of car ,carHOV , truck ,bicycle ,pedestrian | string, car ,truck , bicycle ,pedestrian |
Behavior | Sets the transport mode. | Sets the transport mode. |
avoid[features]
mode=;;;<RouteFeatureType>=<RouteFeatureWeightType>
v7 Parameter | v8 Parameter/notes |
avoidAreas | Use avoid[areas] . Bounding boxes are supported. |
avoidSeasonalClosures | Not supported yet. |
tollroad:-2 | Use avoid[features]=tollRoad . |
motorway:-2 | Use avoid[features]=controlledAccessHighway . |
boatFerry:-2 | Use avoid[features]=ferry . |
railFerry:-2 | Use avoid[features]=carShuttleTrain . |
tunnel:-2 | Use avoid[features]=tunnel . |
dirtRoad:-2 | Use avoid[features]=dirtRoad . |
avoidTurns | Use avoid[features]=difficultTurns |
summaryAttributes
summaryAttributes
has been renamed to matrixAttributes
. The functionality of matrixAttributes
as known from Matrix Routing v7 has been removed. These two parameters have been replaced with matrixAttributes
, which allows to choose between travel times (travelTimes
) , distance (distance
), or both being returned for every entry in the result matrix.
routeId
from Matrix Routing v7 has been removed. This functionality has been migrated to Routing v8 API Reference and is called RouteHandle
in that API.
Other Parameters
In Routing v8, truck
parameters are deprecated. Use vehicle
parameters instead. Do not use truck
parameters and vehicle
parameters in the same request.
v7 Parameter | v8 Parameter/notes |
start | Use origins . |
destination | Use destinations . |
departure | departureTime . If not present, the current time is used. departureTime=any will make the service not use time-dependent attributes (also disabling traffic). Note that if you provide a time, a timezone offset must be provided. |
axleCount | Use vehicle[axleCount] . |
shippedHazardousGoods | Use vehicle[shippedHazardousGoods] . |
limitedWeight | Use vehicle[grossWeight] . Provide value in kilograms. |
weightPerAxle | Use vehicle[weightPerAxle] . Provide value in kilograms. |
height /width /length | Use vehicle[height] , vehicle[width] , and vehicle[length] . Provide values in centimeters. |
tunnelCategory | Use vehicle[tunnelCategory] . |
truckType | Use vehicle[type] . |
trailersCount | Use vehicle[trailerCount] . |
weightsPerAxleGroup | Use vehicle[weightPerAxleGroup] . It is now also possible to specify weight per triple axle group (in addition to single and tandem ). Provide values in kilograms. |
avoidLinks | Use avoid[segments] |
excludeCountries | Use exclude[countries] |
Parameters Expected to be Supported in Upcoming Releases
v7 Parameter | v8 Parameter/notes |
speedProfile | Not supported yet. |
avoidSeasonalClosures | Not supported yet. Planned as avoid[seasonalClosure] . |
Parameters Removed
The following parameters are removed in this migration.
v7 Parameter | v8 notes |
searchRange | Removed. |
Format | This migration removes the Format parameter (v7). The response is always returned in JSON format (v8). XML is no longer supported. |
Response
In Matrix Routing v7 every item of the result matrix was an object containing origin/destination indexes and requested information about the route between these points. Matrix Routing v8 changes this concept and returns arrays of values instead.
Here is a comparison of example responses to a 3x2 matrix request:
Matrix Routing v7 | Matrix Routing v8 |
{
"response": {
"metaInfo": {
"timestamp": "[timestamp]",
"mapVersion": "[map version]",
"moduleVersion": "[module version]",
"interfaceVersion": "[interface version]",
"availableMapVersion": ["map version"]
},
"matrixEntry": [
{
"startIndex": 0,
"destinationIndex": 0,
"summary": {
"distance": 21470,
"travelTime": 2313,
"costFactor": 2333
}
},
{
"startIndex": 0,
"destinationIndex": 1,
"summary": {
"distance": 18227,
"travelTime": 1953,
"costFactor": 1973
}
},
{
"startIndex": 0,
"destinationIndex": 2,
"summary": {
"distance": 24803,
"travelTime": 2280,
"costFactor": 2301
}
},
{
"startIndex": 1,
"destinationIndex": 0,
"summary": {
"distance": 16112,
"travelTime": 2749,
"costFactor": 2749
}
},
{
"startIndex": 1,
"destinationIndex": 1,
"summary": {
"distance": 21206,
"travelTime": 2446,
"costFactor": 2466
}
},
{
"startIndex": 1,
"destinationIndex": 2,
"summary": {
"distance": 27782,
"travelTime": 2773,
"costFactor": 2794
}
},
{
"startIndex": 2,
"destinationIndex": 0,
"summary": {
"distance": 20410,
"travelTime": 2222,
"costFactor": 2242
}
},
{
"startIndex": 2,
"destinationIndex": 1,
"summary": {
"distance": 17167,
"travelTime": 1862,
"costFactor": 1882
}
},
{
"startIndex": 2,
"destinationIndex": 2,
"summary": {
"distance": 23743,
"travelTime": 2189,
"costFactor": 2210
}
}
]
}
}
|
{
"matrixId": "[matrix ID]",
"matrix": {
"numOrigins": 3,
"numDestinations": 2,
"travelTimes": [
3663,
3016,
2915,
2247,
3045,
2177
],
"distances": [
35097,
30990,
34343,
31949,
32501,
24412
]
},
"regionDefinition": {
"type": "world"
}
}
|
For more information about the Matrix Routing v8 response format, see API Reference, section "Responses".