Routing API v7 Developer's Guide

Calculate Route

Use the calculateroute resource to return a route between two waypoints. The required parameters for this resource are app_id and app_code, two or more waypoints (waypoint0 and waypoint1, to waypointN) and mode (specifying how to calculate the route, and for what mode of transport). For some modes departure or arrival (if applicable) is required. This includes all modes with enabled traffic. Other parameters can be left unspecified.

../routing/7.2/calculateroute.{format}?<parameter>=<value>...

Parameter	Description
`apiKey`	A 43-byte Base64 URL-safe encoded string used for the authentication of the client application. As a logged in user, you can generate it at https://developer.here.com/projects. API Keys never expire but you can invalidate your API Keys at any time. You cannot have more than two API Keys for one app at the same time. You must include an `apiKey` with every request. For more information on authentication, see the Identity & Access Management Developer Guide.
`app_id`	A 20 bytes Base64 URL-safe encoded string used for the authentication of the client application. If you use the app ID/app code option, you need to include an `app_id` and `app_code` with every request. For more information on authentication, see the Identity & Access Management Developer Guide.
`app_code`	A 20 bytes Base64 URL-safe encoded string used for the authentication of the client application. If you use the app ID/app code option, you need to include an `app_id` and `app_code` with every request. For more information on authentication, see the Identity & Access Management Developer Guide.
`waypoint`	List of waypoints that define a route. The first element marks the startpoint, the last the endpoint. Waypoints in between are interpreted as via points. See also WaypointParameterType `waypoint0=geo!52.5,13.4`
`mode`	The routing mode determines how the route is calculated. See also RoutingModeType Type;TransportModes;TrafficMode;Feature `&mode=fastest;car;traffic:disabled;motorway:-2`
`requestId`	Clients may pass in an arbitrary string to trace request processing through the system. The `RequestId` is mirrored in the `MetaInfo` element of the response structure.
`avoidAreas`	Areas which the route must not cross. Array of up to 20 BoundingBox-es. Example with two bounding boxes: `avoidareas=52.517100760, 13.3905424488; 52.5169701849, 13.391808451! 52.517000760, 13.3700424488; 52.5168701849, 13.371308451`
`avoidLinks`	Links which the route must not cross. The list of LinkIdTypes. `LinkIdType` is a `xs:string` with the following regular expression restrictions: `[*-+]\d+` `avoidlinks=-53623477`
`avoidSeasonalClosures`	The optional avoid seasonal closures boolean flag can be specified to avoid usage of seasonally closed links: `avoidseasonalclosures=true` Examples of seasonally closed links are roads that may be closed during the winter due to weather conditions or ferries that may be out of operation for the season (based on past closure dates).
`avoidTurns`	List of turn types that the route should avoid. Defaults to empty list. For details on the available values, see the description of the `TurnType` enumeration type. Enum [ `difficult` ] Note: Currently, truck routing is the only mode that supports the `avoidTurns` option. Note: The route always avoids u-turns on single-digitized roads, also when you don't specify the `avoidTurns` parameter. The exceptions are dead ends and single-digitized roads where u-turns are explicitly permitted by a road sign.
`allowedZones`	Identifiers of zones where routing engine should not take zone restrictions into account (for example in case of a special permission to access a restricted environmental zone). Allowed zones are also not considered in evaluation of the `excludezonetypes` parameter. Type: list of `xs:unsignedLong`. To obtain identifiers of relevant zones use the `getroutingzones` resource. `licenseplate=lastcharacter:5&allowedzones=167772378 // ignore license plate rules in Indonesia Odd/Even scheme zones excludezonetypes=vignette&allowedzones=508 // disable all roads where any vignette applies except vignette in Austria`
`excludeZones`	Identifiers of zones which the route must not cross under any circumstances. Type: list of `xs:unsignedLong`. To obtain identifiers of relevant zones use the `getroutingzones` resource. `excludezones=510,511`
`excludeZoneTypes`	List of zone types which the route must not cross under any circumstances. See RoutingZoneTypeType for supported zone types. `excludezonetypes=vignette,congestionPricing`
`excludeCountries`	Countries that must be excluded from route calculation. Type: list of `common:CountryCodeType`. `excludecountries=AUT,CHE`
`departure`	Time when travel is expected to start. Traffic speed and incidents are taken into account when calculating the route, where applicable (note that in case of a past departure time the historical traffic is limited to one year). You can use `now` to specify the current time. Specify either `departure` or `arrival`, not both. Type: `xs:dateTime`. `departure=2018-07-04T17:00:00+02` When the optional timezone offset is not specified time is assumed to be local.
`arrival`	Time when travel is expected to end. Traffic speed and incidents are taken into account when calculating the route, where applicable. Specify either `departure` or `arrival`, not both. Type: `xs:dateTime`. `arrival=2013-07-04T17:00:00+02` When the optional timezone offset is not specified, the time is assumed to be the local.
`alternatives`	Maximum number of alternative routes that will be calculated and returned. Alternative routes can be unavailable, thus they are not guaranteed to be returned. If at least one via point is used in a route request, returning alternative routes is not supported. `0` stands for "no alternative routes", i.e. only best route is returned. Type: `xs:integer`. `alternatives=3`
`metricSystem`	Defines the measurement system used in instruction text. When imperial is selected, units used are based on the language specified in the request. Defaults to metric when not specified. xs:string. Enum [`imperial` \| `metric`]
`viewBounds`	If the view bounds are given in the request then only route shape points which fit into these bounds will be returned. The route shape beyond the view bounds is reduced to the points which are referenced by links, legs or maneuvers. A common use case for this is the drag and drop scenario where the client is only interested in a rough visual update of the route in the currently visible bounds. See also BoundingBox. `viewbounds=37.7902858,-122.4027371; 37.7890649,-122.3993039`
`resolution`	Specifies the resolution of the view and a possible snap resolution in meters per pixel in the response. You must specify a whole, positive integer. If you specify only one value, then this value defines the view resolution only. You can use snap resolution to adjust waypoint links to the resolution of the client display. `resolution=viewresolution:snapresolution resolution=300:300`
`instructionFormat`	Defines the representation format of the maneuver's instruction text. InstructionFormatType `instructionformat`=Enum [ `text` \| `html`]
`language`	A list of languages for all textual information, the first supported language is used. If there are no matching supported languages the response is an error. Defaults to en-us. See Languages for a list of supported languages.
`jsonAttributes`	Flag to control JSON output. Combine parameters by adding their values. See also JSON Representation. `jsonattributes=9`
`jsonCallback`	Name of a user-defined function used to wrap the JSON response.
`representation`	Define which elements are included in the response as part of the data representation of the route. See also RouteRepresentationModeType. Enum [ `overview` \| `display` \| `dragNDrop` \| `navigation` \| `linkPaging` \| `turnByTurn` ]
`routeAttributes`	Define which attributes are included in the response as part of the data representation of the route. Defaults to `waypoints`, `summary`, `legs` It is strongly advised to always request `notes` in order to be informed in case any restrictions were violated in the calculated route. See also RouteAttributeType. Enum [ `waypoints` \| `summary` \| `summaryByCountry` \| `shape` \| `boundingBox` \| `legs` \| `notes` \| `routeId` \| `groups` \| `tickets` \| `incidents` \| `zones` ]
`legAttributes`	Define which attributes are included in the response as part of the data representation of the route legs. Defaults to `maneuvers`, `waypoint`, `length`, `travelTime`. See also RouteLegAttributeType. Enum [ `waypoint` \| `maneuvers` \| `links` \| `length` \| `travelTime` \| `shape` \| `indices` \| `boundingBox` \| `baseTime` \| `trafficTime` \| `summary` ]
`maneuverAttributes`	Define which attributes are included in the response as part of the data representation of the route maneuvers. Defaults to `position`, `length`, `travelTime`. See also ManeuverAttributeType Enum [ `position` \| `shape` \| `travelTime` \| `length` \| `time` \| `link` \| `platform \|` `roadName` \| `nextRoadName` \| `roadNumber` \| `nextRoadNumber` \| `signPost` \| `notes` \| `action` \| `direction` \| `freewayExit` \| `freewayJunction` \| `indices` \| `baseTime` \| `trafficTime` \| `waitTime \|` `boundingBox` \| `roadShield` \| `shapeQuality` \| `nextManeuver` \| `startAngle` ]
`linkAttributes`	Define which attributes are included in the response as part of the data representation of the route links. Defaults to `shape`, `speedLimit`, . See also RouteLinkAttributeType. Enum [ `consumption` \| `dynamicSpeedInfo` \| `flags` \| `functionalClass` \| `indices` \| `length` \| `maneuver` \| `nextLink` \| `nextStopName` \| `remainDistance` \| `remainTime` \| `roadName` \| `roadNumber` \| `shape` \| `speedLimit` \| `timeDependentRestriction` \| `timezone` \| `truckRestrictions` ]
`generalizationTolerances`	Specifies the desired tolerances for generalizations of the base route geometry. Tolerances are given in degrees of longitude or latitude on a spherical approximation of the Earth. One meter is approximately equal to 0:00001 degrees at typical latitudes. Type: `xs:list` of `xs:double`. `generalizationtolerances=0.1,0.01`
`vehicleType`	Specifies type of vehicle engine and average fuel consumption, which can be used to estimate CO2 emission for the route summary (RouteSummaryType). See also VehicleType `vehicletype=diesel,5.5`
`licensePlate`	Specifies fragments of vehicle's license plate number. The `lastcharacter` is currently the only supported fragment type. The license plate parameter enables evaluation of license plate based vehicle restrictions like odd/even scheme in Indonesia. Fragment types [ `lastcharacter` ] `licensePlate=lastcharacter:5` Note: Currently, data on license plate based restrictions are available only for certain environmental zones in Indonesia and Philippines.
`truckType`	Truck routing only, specifies the vehicle type. Defaults to `truck`. Enum [`truck \| tractorTruck`] Note: Relevant for restrictions that apply exclusively to tractors with semi-trailers (observed in North America). Such restrictions are taken into account only in case of the `truckType` set to `tractorTruck` and the trailers count greater than 0 (for example `&truckType=tractorTruck&trailersCount=1`). The truck type is irrelevant in case of restrictions common for all types of trucks.
`trailersCount`	Truck routing only, specifies number of trailers pulled by the vehicle. The provided value must be between `0` and `4`. Defaults to `0`.
`axleCount`	Truck routing only, specifies number of axles on the vehicle. The provided value must be between `2` and `254`. Defaults to `2`.
`shippedHazardousGoods`	Truck routing only, list of hazardous materials in the vehicle. Please refer to the enumeration type HazardousGoodTypeType for available values. Note the value `allhazardousGoods` does not apply to the request parameter. Enum [`explosive \| gas \| flammable \| combustible \| organic \| poison \| radioActive \| corrosive \| poisonousInhalation \| harmfulToWater \| other`]
`limitedWeight`	Truck routing only, vehicle weight including trailers and shipped goods, in tons. The provided value must be between `0` and `1000`.
`weightPerAxle`	Truck routing only, vehicle weight per axle in tons. The provided value must be between `0` and `1000`.
`weightsPerAxleGroup`	Truck routing only, semicolon-separated list of vehicle weights per distinct axle groups in tons. Each weight-per-axle-group item consists of a `TruckAxleGroupType` (see TruckAxleGroupType for available types) and a weight value. The provided weight value must be between `0` and `1000`. See Weight Per Axle Group for details. AxleGroupType:WeightValue;AxleGroupType:WeightValue;... `&weightsPerAxleGroup=single:10;tandem:15`
`height`	Truck routing only, vehicle height in meters. The provided value must be between `0` and `50`.
`width`	Truck routing only, vehicle width in meters. The provided value must be between `0` and `50`.
`length`	Truck routing only, vehicle length in meters. The provided value must be between `0` and `300`.
`tunnelCategory`	Truck routing only, specifies the tunnel category to restrict certain route links. The route will pass only through tunnels of a less strict category. Enum [ `B \| C \| D \| E` ] `tunnelcategory=C`
`truckRestrictionPenalty`	Truck routing only, specifies the penalty type on violated truck restrictions. Defaults to `strict`. Refer to the enumeration type TruckRestrictionPenaltyType for details on available values. Note that the route computed with the penalty type `soft` will use links with a violated truck restriction if there is no alternative to avoid them. The route violating truck restrictions is then indicated with dedicated route and maneuver notes in the response as demonstrated in this example. Enum [ `strict \| soft` ] `truckRestrictionPenalty=soft&routeattributes=notes` Note: The value `soft` can be used only when the route notes are enabled (see the options RouteAttributeType of the `routeAttributes` request parameter). Note: The route returned with the route note of the type `violation` and the text `truckRestriction` may be travelled only at own responsibility. While driving such route extra care has to be taken as it may result in a vehicle or a road infrastructure damage.
`returnElevation`	If set to true, all shapes inside routing response will consist of 3 values instead of 2. Third value will be elevation. If there are no elevation data available for given shape point, elevation will be interpolated from surrounding points. In case there is no elevation data available for any of the shape points, elevation will be 0.0. If `jsonattributes=32`, elevation cannot be returned. `returnelevation=true`
`consumptionModel`	If you request information on consumption, you must provide a consumption model. The possible values are `default` and `standard`. When you specify the value `standard`, you must provide additional information in the query parameter `customconsumptiondetails` `consumptionmodel=default` `consumptionmodel=standard`
`customConsumptionDetails`	Provides vehicle specific information for use in the consumption model. This information can include such things as the amount of energy consumed while travelling at a given speed. For details on the consumption model see Standard consumption model.
`speedProfile`	Specifies the speed profile variant for a given routing mode. The speed profile affects travel time estimation as well as roads evaluation when computing the fastest route. Note that computed routes might differ depending on a used profile. See SpeedProfileType for details. Enum [ `default \| fast` ] `speedProfile=fast` Note: Currently, truck routing is the only mode that supports the `speedProfile` parameter.

Example Request

https://route.ls.hereapi.com/routing/7.2/calculateroute.xml
?apiKey={YOUR_API_KEY}
&waypoint0=geo!52.5,13.4
&waypoint1=geo!52.5,13.45
&mode=fastest;car;traffic:disabled

Note: This example uses a HERE API Key to authenticate your request. For the available authentication options, see the Identity & Access Management Developer Guide.

Example Request for SummaryByCountry

https://route.ls.hereapi.com/routing/7.2/calculateroute.xml
?apiKey={YOUR_API_KEY}
&waypoint0=geo!50.8857,14.81589
&waypoint1=geo!50.8681536,14.8308207
&routeattributes=wp,sm,sh,sc
&mode=fastest;car

Note: This example uses a HERE API Key to authenticate your request. For the available authentication options, see the Identity & Access Management Developer Guide.

Example Response for SummaryByCountry


<Route>

 . . . 

  <Summary>
    <Distance>2218</Distance>
    <TrafficTime>109</TrafficTime>
    <BaseTime>109</BaseTime>
    <Flags>motorway</Flags>
    <TravelTime>109</TravelTime>
  </Summary>

  <SummaryByCountry>
    <Distance>297</Distance>
    <TrafficTime>21</TrafficTime>
    <BaseTime>21</BaseTime>
    <Flags>motorway</Flags>
    <TravelTime>21</TravelTime>
    <Country>DEU</Country>
  </SummaryByCountry>
  <SummaryByCountry>
    <Distance>1471</Distance>
    <TrafficTime>58</TrafficTime>
    <BaseTime>58</BaseTime>
    <Flags>motorway</Flags>
    <TravelTime>58</TravelTime>
    <Country>POL</Country>
  </SummaryByCountry>
  <SummaryByCountry>
    <Distance>450</Distance>
    <TrafficTime>30</TrafficTime>
    <BaseTime>30</BaseTime>
    <Flags>motorway</Flags>
    <TravelTime>30</TravelTime>
    <Country>CZE</Country>
  </SummaryByCountry>
</Route>