GuidesAPI Reference
API Reference

Get route by handle via POST

post
https://router.hereapi.com/v8/routes/

Decodes and returns a route from a previously calculated route handle.

Disclaimer: A route handle is not suitable for persistent route storage! It can be invalidated at any time.

A route handle encodes a previously calculated route. A route can be decoded from a handle as long as the service uses the same map data and encoding that were used when retrieving the handle.

Thus it is suitable for caching routes compactly. It can be used to retrieve updated traffic information or other data along the route. However, a user should be prepared to recalculate the route when decoding the handle fails.

All parameters of the /routes endpoint are supported, except for destination, via, alternatives and routingMode. See also the return parameter of /routes endpoint.

The origin parameter can be provided to update the start of the previously calculated route.

The transportMode parameter does not have to match the transport mode previously used for route calculation. However, when using a different transport mode, the request may fail, e.g. when the route has road segments forbidden for the provided transport mode.

Only selected parameters are permitted in the POST body. See the request body section below for details. If a parameter is provided in both the query string and the POST body, their values are merged.

Post body size limit is 10MiB.

Please refer to the Developer Guide for more information and examples.

Path Params
string
required

Route handle returned from a previous route calculation.

See return parameter of /routes endpoint for more information.

Query Params
string
enum
required

Mode of transport to be used for the calculation of the route.

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

networkRestrictedTruck transport mode requires the use of the networkRestrictedTruck[permittedNetworks] parameter.

Additionally, networkRestrictedTruck transport mode cannot use any of the following parameters that are otherwise allowed for trucks:

  • avoid[features] with any of tollRoad, controlledAccessHighway, carShuttleTrain, difficultTurns
  • avoid[truckRoadTypes]
  • vehicle[occupancy]
  • vehicle[engineType]
  • vehicle[kpraLength]
  • vehicle[category]
  • any ev[*] parameters
  • any fuel[*] parameters
string

A location defining the origin of the trip. The origin has to be located along the previously calculated route.

For a description of the format and options for this parameter, please refer to the description of the origin parameter in Calculate routes via GET.

This parameter supports the same options as the origin parameter in Calculate routes via GET, with the following exceptions:

Notes

  • minCourseDistance: While this parameter can be provided for compatibility reasons, it will not affect the result of a getRoutesByHandle request.
string

Specifies the time of departure as defined by either date-time or full-date T partial-time in RFC 3339, section 5.6 (for example, 2019-06-24T01:23:45).

The requested time is converted to local time at origin. When the optional timezone offset is not specified, time is assumed to be local. The special value any can be used to indicate that time should not be taken into account during routing. If neither departureTime or arrivalTime are specified, current time at departure place will be used. All time values in the response are returned in the timezone of each location.

Note: Only long-term traffic incidents will be used if departureTime=any and traffic[mode]=default or no traffic[mode] are specified.

avoid
object

Avoid roads that violate certain features of road network or that go through user-specified areas, segments, or zones.

Note that if the origin, destination, or any via is in an avoided area or on an avoided feature, a route is produced that violates the avoid restriction. In such a case, the route is trying to minimize the violation of the avoid restrictions and can therefore include large deviations from a route that is calculated without these avoid restrictions.

It is also possible that the produced route violates the avoid restriction in between waypoints, if no other route is possible or too hard to find. One such example is requesting a route to an island that is only reachable with ferries while specifying avoid[features]=ferry.

When using avoid features, it's not guaranteed to get alternatives. Further, they can even cause the route calculation to fail, if no route is possible or too hard to find.

allow
object

Explicitly allow features that require users to opt in.

exclude
object

Defines properties which will be strictly excluded from route calculation.

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

string
enum

Units of measurement used in guidance instructions. The default is metric.

Allowed:
lang
array of strings
Defaults to en-US

Specifies the list of preferred languages of the response. The first supported language from the list will be used for for the response if available. The next languages are used as fallbacks if the first one is not available. Additionally, some more fallback logic is applied if no language is available, like generalizing the requested language code. The value should comply with the IETF BCP 47. A list of supported languages for the routing service, as well as more information on the language fallback logic, can be found in the Developer Guide.

Note: If the first language in the list is not supported exactly, an info notification will be generated with code mainLanguageNotFound.

lang
return
array of objects

Defines which attributes are included in the response as part of data representation of a Route or Section.

  • polyline - Polyline for the route in Flexible Polyline Encoding. Either a 2D polyline (without elevation specified), or a 3D polyline with the 3rd dimension type Elevation (with elevation specified), using the WGS84 coordinate system.

  • actions - Actions (such as maneuvers or tasks) that must be taken to complete the section.

  • instructions - Include instructions in returned actions. Instructions are localized to the requested language.

  • summary - Include summary for the section.

  • travelSummary - Include summary for the travel portion of the section.

  • turnByTurnActions - Include all information necessary to support turn by turn guidance to complete the section.

  • mlDuration - Use a region-specific machine learning model to calculate route duration. Disclaimer: This parameter is currently in beta release, and is therefore subject to breaking changes.

  • typicalDuration - Include route duration under typical traffic conditions.

  • elevation - Include WGS84 elevation information in coordinate and geometry types. See e.g. polyline or location.

  • routeHandle - Encode calculated route and return a handle which can be used with routes/{routeHandle} to decode the route at a later point in time.

  • passthrough - Include information on passthrough via waypoints in the section.

  • incidents - Include a list of all incidents applicable to each section. Returned incidents may be referenced by incidents and/or intersectionIncidents span parameters. Incidents are localized to the requested language.

  • routingZones - Include information about routing zones each section goes through.

  • truckRoadTypes - Include information about road types each section goes through.

  • tolls - Include information about the tolls to be paid, per section, according to the tolls parameter and other toll-influencing parameters such as vehicle dimensions in the query, e.g transportMode, vehicle[hovOccupancy], vehicle[height]. Check the Developer Guide for tutorials on the topic. If tolls cannot be calculated for a section, it will contain the tollsDataUnavailable notice code.

    Note:

    • Toll requests support car dimensions such as atypical car height and weight, trailers, axle count and vehicle fuel type. However extreme parameter combinations may result in tolls being returned for a different vehicle type (for example, a car with 6 axles will most likely result in truck tolls). Therefore the request will return the most "typical" toll cost for the parameters provided.
    • Tolls are not available in route import service. See this tutorial for information on how to request tolls when using route import.

  • routeLabels - Include a list of the most important names and route numbers on this route that differentiate it from other alternatives

  • potentialTimeDependentViolations - Include info notices for potential time-dependent violations in the sections that match the current vehicle profile, but are not violating the restricted times for the calculated route.

  • noThroughRestrictions - Include information about the parts of the route that are not allowed to be driven through, i.e. route can only start, end, or have an intermediate via waypoint here.

The following restrictions apply when specifying the return parameter:

  • If actions is requested, then polyline must also be requested as well.
  • If instructions is requested, then actions must also be requested as well.
  • If turnByTurnActions is requested, then polyline must also be requested as well.
  • If at least one attribute is requested within the spans parameter, then polyline must be request as well
spans
array of objects

Defines which map content attributes are included in the response spans. For example, attributes,length will enable the fields attributes and length in the route response. For more information about the countryCode field, see the ISO standard.

This parameter also requires that the polyline option is set within the return parameter.

NOTE: Attribute speedLimit is deprecated, use maxSpeed instead. Attribute segmentId is deprecated, use segmentRef instead.

truck
object
deprecated

Truck-specific parameters.

NOTE: The attribute truck is deprecated and should be replaced with vehicle.

vehicle
object

Vehicle-specific parameters.

string
Defaults to empirical

Specifies which of the EV consumption models is being used. See the ev parameter for details on the models.

  • empirical
  • physical

Alpha: Physical consumption model is in development. It may not be stable and is subject to change.

ev

EV properties to be used for calculating consumption.

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

The following ev properties are additionally required in order to calculate State-of-Charge along the route:

  • initialCharge
  • maxCharge

Route reachability based on State-of-Charge will be evaluated for the following constraints, if additionally provided,

  • minChargeAtDestination
  • minChargeAtFirstChargingStation
  • minChargeAtChargingStation

The following properties are additionally required in order to calculate charging at charging station waypoints (see documentation for via parameter)

  • chargingCurve

Notes:

  • Hybrid vehicles (EV + Other fuel types) are not supported. Consumption properties are not supported for combination of ev and fuel vehicles.
  • EV parameters are not supported in combination with pedestrian, bicycle and network restricted truck transportMode.
fuel
object

Disclaimer: This parameter is currently in beta release, and is therefore subject to breaking changes.

Fuel parameters to be used for calculating consumption and related CO2 emission.

The following attributes are required for calculating consumption:

  • type
  • freeFlowSpeedTable

Notes:

  • Hybrid vehicles (EV + Other fuel types) are not supported. Consumption properties are not supported for combination of ev and fuel vehicles.
  • Fuel parameters are not supported in combination with pedestrian and bicycle transportMode.
number
0.5 to 2
Defaults to 1

Walking speed in meters per second. Influences the duration of walking segments along the route.

scooter
object

Scooter-specific parameters.

  • allowHighway: Specifies whether the scooter is allowed on highways or not. This parameter is optional. If not provided, the default is to avoid highways. There is a similar parameter avoid[features]=controlledAccessHighway to disallow highway usage. avoid[features] takes precedence, so if that parameter is also used, scooters are not allowed to use highways even if allowHighway is set to true. The following values are possible:
    • true: The scooter is allowed to use highways.
    • false: The scooter is not allowed to use highways.
string

Currency code compliant to ISO 4217. Costs for the calculated route will be returned using this currency.

If not provided, the router will specify it. On a best-effort basis, the router will try to specify the costs in the local currency.

rerouting
object

Rerouting parameters allow to request a new route calculation based on the route handle.

All attributes are optional.

taxi
object

Taxi-specific parameters.

  • allowDriveThroughTaxiRoads: Specifies if a vehicle is allowed to drive through taxi-only roads and lanes. Even if this option is set to false, the vehicle is still allowed on taxi-only roads at the start of the route and at the destination.
tolls
object

Defines properties which control toll calculation and reporting in the response.

string

Specify new base speed for segment by value. Affects route selection and the ETA. Cannot increase base speed on segment.

traffic
object

Traffic specific parameters.

networkRestrictedTruck
object

Disclaimer: This parameter is currently in beta release, and is therefore subject to breaking changes.

Parameters specific to the networkRestrictedTruck transport mode.

string

A list of up to six billing tags, separated by the + sign.

This parameter provides a way to track your platform usage. For details, refer to the Cost Management Developer Guide section on Billing Tags

Body Params
avoid
object

Avoid routes that violate certain features of road network or that go through user-specified geographical bounding boxes.

For the general description of the functionality please refer to the avoid parameter of the query string.

Passing parameters in the POST body is suggested when the length of the parameters exceeds the limitation of the GET request.

exclude
object

User-specified properties that need to be strictly excluded during route calculation.

For the general description of the functionality please refer to the exclude parameter of the query string.

Passing parameters in the POST body is suggested when the length of the parameters exceeds the limitation of the GET request.

maxSpeedOnSegment
array of objects

Segments with restrictions on maximum baseSpeed.

For the general description of the functionality please refer to the maxSpeedOnSegment parameter of the query string.

Passing parameters in the POST body is suggested when the length of the parameters exceeds the limitation of the GET request.

Example of a parameter value excluding two segments:

[
  {
    "segment": "here:cm:segment:207551710#+",
    "speed": 10
  },
  {
    "segment": "here:cm:segment:76771992",
    "speed": 1
  }
]

Notes:

  • Maximum number of penalized segments in one request cannot be greater than 1000. "penalized segments" refer to segments that have a restrictions on maximum baseSpeed with maxSpeedOnSegment or avoided with avoid[segments].
  • In case the same segment is penalized multiple times through values provided in the query string and/or the POST body, then the most restrictive value will be applied.
maxSpeedOnSegment
networkRestrictedTruck
object

Disclaimer: This parameter is currently in beta release, and is therefore subject to breaking changes.

Parameters specific to the networkRestrictedTruck transport mode.

Headers
string

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

Responses

Updated 2 days ago

Language
Credentials
Response 
Click Try It! to start a request and see the response here! Or choose an example:
application/json
Updated 2 days ago