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.

Note

If you are a Routing user, please see Routing Migration Guide

If you are an Isoline Routing user, please see Isoline Routing Migration Guide

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

Note

The app code credentials are not supported in v8. For more information on the currently available authentication methods, see the Identity & Access Management Developer Guide.

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".

results matching ""

    No results matching ""