GuidesAPI Reference
API Reference

Calculate routes via GET

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

Calculates a route using a generic vehicle/pedestrian mode, e.g. car, truck, pedestrian, etc...

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
required

A location defining the origin of the trip.

Format

Format: Place[WaypointOptions]

  • Place: {lat},{lng}[PlaceOptions]
  • PlaceOptions: ;option1=<value1>;option2=<value2>...
  • WaypointOptions: !option1=<value1>!option2=<value2>...

A waypoint consists of:

  • Exactly one place
  • Optional settings for the place
  • Optional settings for the waypoint itself

Supported place options

  • course: int, degrees clock-wise from north. Indicating desired direction at the place. E.g. 90 indicating east. Often combined with radius and/or minCourseDistance

  • sideOfStreetHint: {lat},{lng}. Indicating the side of the street that should be used. E.g. if the location is to the left of the street, the router will prefer using that side in case the street has dividers. E.g. 52.511496,13.304140;sideOfStreetHint=52.512149,13.304076 indicates that the north side of the street should be preferred. This option is required, if matchSideOfStreet is set to always. Option cannot be combined with radius, radiusPenalty or snapRadius.

  • displayLocation: {lat},{lng}. Indicates the location on the map where this POI is to be displayed. This attribute is passed through to the displayLocation attribute in the corresponding Place object in the output.

  • uTurnPermission: enum [allow, avoid]. Specifies the U-Turn Permission mode at the stop-over waypoint. If unspecified, the permission will be determined by the global setting, avoid[features]=uTurns. This feature is not supported for pass-through waypoints and U-Turns are generally avoided in that case.

    • allow : Allow making a U-Turn at this stop-over waypoint
    • avoid : Avoid making a U-Turn at this stop-over waypoint

  • matchSideOfStreet: enum [always, onlyIfDivided]. Specifies how the location set by sideOfStreetHint should be handled. Requires sideOfStreetHint to be specified as well.

    • always : Always prefer the given side of street.
    • onlyIfDivided: Only prefer using side of street set by sideOfStreetHint in case the street has dividers. This is the default behavior.

  • nameHint: string. Causes the router to look for the place with the most similar name. The typical examples include: North being used to differentiate between interstates I66 North and I66 South, Downtown Avenue being used to correctly select a residental street.

    Empty string values are ignored.

  • radius: int, meters. Asks the router to consider all places within the given radius as potential candidates for route calculation. This can be either because it is not important which place is used, or because it is unknown. Radiuses wider than 200 meters are not supported. Option cannot be combined with snapRadius.

  • radiusPenalty: int, percentage 0-10000. Penalty as percentage: Used in conjunction with the radius parameter. Router will match the waypoint within the specified radius and apply a penalty to candidates based on their air distance to the waypoint. This penalty is proportional to the given percentage, where 100 is just the cost of the air distance, and 200 is twice the cost of the air distance. The penalty must be chosen so that, when multiplied by the radius, the result is less than or equal to 7200. Regardless, only values up to and including 10000 will be accepted. This means that a maximum penalty of 3600% is allowed for a radius of 200m, 7200% for 100m and 10000% for 72m and less. Higher values will result in an error response. radiusPenalty cannot be combined with snapRadius. Alpha: This parameter is in development. It may not be stable and is subject to change.

  • snapRadius: int, meters. Instructs the router to match the waypoint, within the specified radius, to the most "significant" road. In contrast to the regular radius parameter, snapRadius sorts potential candidates in order of "significance". For example, a highway is more significant on a zoomed-out map than a national road, a national road is more significant than a city road, etc. Hence, snapRadius cannot be combined with radius or radiusPenalty parameters. The typical use case for snapRadius is when selecting a waypoint on a zoomed-out view of a map on a drag-and-drop interface. The expectation on such UIs is that only roads that are visible at that zoom level are considered for matching and a large snapRadius would enable that.

  • minCourseDistance: int, meters. Instructs the routing service to try to find a route that avoids actions for the indicated distance. For example, if the origin is determined by a moving vehicle, the user might not have time to react to early actions. Values greater than 2000 meters will be capped at 2000 meters.

  • customizationIndex: int. Specifies the zero-based index into the list of customizations specified in the customizations parameter. The customization at that index must be an Extension Map. Providing a customizationIndex indicates the this waypoint is located within that Extension Map. Alpha: This customization API parameter is in development. It may not be stable and is subject to change.

  • segmentIdHint: string. Causes the router to try and match to the specified segment. Waypoint coordinates need to be on the segment, otherwise waypoint will be matched ignoring the segment hint This parameter can be used when the waypoint is too close to more than one segment to force matching to a specific one.

  • onRoadThreshold: int, meters. allows specifying a distance within which the waypoint could be considered as being on a highway/bridge/tunnel/sliproad. Within this threshold, the attributes of the segments do not impact the matching. Outside the threshold only segments which aren't one of highway/bridge/tunnel/sliproad can be matched.

Notes

  • origin currently does not support any WaypointOptions. They are available for via and destination waypoints.
  • Non-structural reserved characters in options' values need to be properly percent-encoded. Please refer to the Developer Guide for more details.
string
required

A location defining the destination of the trip.

For a description of the format and options for this parameter, please refer to the description of the origin parameter.

destination supports the same options as the origin parameter, with the following exceptions:

Additional waypoint options:

  • stopDuration: desired duration for the stop, in seconds. The section arriving at this via waypoint will have a wait post action reflecting the stopping time. The subsequent section will start at the arrival time of the former section + stop duration.
via
array of strings

A location defining a via waypoint.

A via waypoint is a location between origin and destination. There are two types of via waypoints:

  • passThrough=false (default) : The route will stop at the via waypoint, creating a new route section.
  • passThrough=true : The route will pass through the via waypoint.

Multiple waypoints can be specified by using multiple via parameters like via=...&via=..., in which case the route will traverse these waypoints sequentially in the order specified in the request.

For a description of the format and options for this parameter, please refer to the description of the origin parameter. via supports the same options as the origin parameter, with the following exceptions:

Additional waypoint options:

  • stopDuration: desired duration for the stop, in seconds. Must be less than 50000.

  • passThrough: boolean. Default value is false. Setting to true asks the router to avoid the following during route calculation:

    • Introducing a stop at the waypoint.
    • Splitting the route into sections.
    • Changing the direction of travel.

    The following scenarios are not supported for passThrough parameter:

    • Setting both stopDuration to a value greater than 0 and passThrough=true.

  • charging: Structured string denoting a user-planned charging stop.

    Format: charging=(power=<value>;current=<value>;voltage=<value>;supplyType=<value>;minDuration=<value>;maxDuration=<value>).

    The properties power, current, voltage and supplyType denote the characteristics of the chosen compatible connector at the station. These are all required. minDuration and maxDuration set the time bounds for the charging time. At least one of them is required. For most use cases we recommend to provide at least minDuration. The following are the specifications for the properties:

    • power: value in kW, type: number. Rated power of the connector.
    • voltage: value in V, type: number. Rated voltage of the connector.
    • current: value in A, type: number. Rated current of the connector.
    • supplyType: one of {"acSingle", "acThree", "dc"} for 1-phase AC, 3-phase AC and DC respectively, type: string.
    • minDuration: value in seconds, type: int. Minimum time the user expects to charge at the station, including chargingSetupDuration. This value takes precedence over the global maxChargingDuration.
    • maxDuration: value in seconds, type: int. Maximum time the user plans to charge at the station, including chargingSetupDuration. This value takes precedence over the global maxChargingDuration.

    For a user-planned charging stop, the following properties of the ev parameter are also required (see documentation for the ev parameter):

    • initialCharge
    • maxCharge
    • chargingCurve

    Notes:

    • This option is not supported for pass-through waypoints.
    • If makeReachable=true and minDuration is not provided (or if minDuration=0), route calculation may suggest not to charge on this station, for example, if a better station is available in the vicinity.
    • If stopDuration is provided then the total time at the stop is the higher of (stopDuration, chargingSetupDuration + chargingDuration).
    • If charging for minDuration would charge above maxCharge, the time spent charging is capped by maxCharge.
    • If stopDuration or minDuration exceed chargingSetupDuration + chargingDuration, the waiting post action duration is set to the remaining time.
    • If makeReachable=true is not set, the target charge is maxChargeAfterChargingStation, unless the charging time would be outside of the specified duration range. In such case, the nearest valid value is used.
    • In getRoutesByHandle requests, the target charge from the original route response is used, unless the charging time would be outside of the specified duration range. In such case, the nearest valid value is used.

  • currentWeightChange: Changes the value of vehicle[currentWeight] by this value. Enables the support of scenarios where the vehicle takes additional cargo or unloads its cargo along the route. Changes to the configuration of the vehicle, such as adding a trailer, aren't supported. Relative value in kilograms, beginning with either + or -. Available range: from -40000 to +40000 (inclusive).

    If this parameter is specified on any of the via waypoints or the request has the vehicle[currentWeight] set, the response contains the currentWeight value used for each section.

    When this parameter is provided, both vehicle[currentWeight] and vehicle[grossWeight] must also be provided.

    If the currentWeight value falls below 0 due to currentWeightChange, the system returns a critical violation notice, but a route is still calculated. The system returns notices only for negative values. Very low positive values are likely invalid, but don't trigger notices since they are greater than 0.

    The currentWeightChange value is stored in the RouteHandle at each waypoint and can't be changed in RouteHandle calculation requests.

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

date-time

Specifies the time of arrival 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 the local time at destination. When the optional timezone offset is not specified, time is assumed to be local. All Time values in the response are returned in the timezone of each location.

Note : The following features do not support the arrivalTime parameter:

  • EV Routing
  • Route Handle
  • Route Import
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
    • networkRestrictedTruck
Allowed:
integer
0 to 6
Defaults to 0

Number of alternative routes to return aside from the optimal route.

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.

The following properties are additionally required for the router to automatically enhance the route with charging stops

  • makeReachable set to true
  • chargingCurve
  • connectorTypes
  • maxChargeAfterChargingStation
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.
driver
object

Driver parameters to be used for calculating routes with automatically added rest stops.

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.

customizations
array of objects

Specifies a list of customizations to be used. The data provided by these customizations either replaces or augments the standard HERE map data. The provided credentials must authorize access to all of the customizations specified.

Alpha: This API is in development. It may not be stable and is subject to change.

customizations
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

Headers
string

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

Responses

Updated yesterday

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