Routing API 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 publicTransportTimeTable, publicTransport and all modes with enabled traffic. Other parameters can be left unspecified.

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

A 20 bytes Base64 URL-safe encoded string used for the authentication of the client application.

You must include an app_id with every request. To get an app_id assigned to you, please see Acquiring Credentials.

app_code

A 20 bytes Base64 URL-safe encoded string used for the authentication of the client application.

You must include an app_code with every request. To get an app_code assigned to you, please see Acquiring Credentials.

waypoint List of waypoints that define a route. The first element marks the start, the last the end point. 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 BoundingBox. Example with 2 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. List of LinkIdType. 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).

excludeZones Identifiers of zones which the route must not cross at any circumstances. Type: list of xs:unsignedLong.
excludezones=510,511
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. You can use now to specify the current time. Specify either departure or arrival, not both. Type: xs:dateTime.
departure=2013-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. 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.

Note: You can only use this parameter when mode is set to publicTransportTimeTable.
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 and additionally lines if publicTransport or publicTransportTimeTable mode is used. See also RouteAttributeType.

Enum [waypoints | summary | summaryByCountry | shape | boundingBox | legs | notes | lines | 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 | publicTransportLine | platform | roadName | nextRoadName | roadNumber | nextRoadNumber | signPost | notes | action | direction | freewayExit | freewayJunction | indices | baseTime | trafficTime | waitTime | boundingBox | roadShield | shapeQuality | nextManeuver | publicTransportTickets | 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 [shape | length | speedLimit | dynamicSpeedInfo | truckRestrictions | flags | roadNumber | roadName | timezone | nextLink | publicTransportLine | remainTime | remainDistance | maneuver | functionalClass | nextStopName | indices | consumption ]

lineAttributes Sequence of attribute keys of the fields that are included in public transport line elements. If not specified, defaults to lineForeground, lineBackground. See also PublicTransportLineAttributeType.

Enum [foreground | background | lineStyle | companyShortName | companyLogo | typeName | stops]

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
maxNumberOfChanges
Restricts number of changes in a public transport route to a given value. The parameter does not filter resulting alternatives. Instead, it affects route calculation so that only routes containing at most the given number of changes are considered. The provided value must be between 0 and 10. Type: xs:int.
maxnumberofchanges=3
avoidTransportTypes

Public transport types that shall not be included in the response route. Please refer to Enumeration Types for a list of supported values. Type: xs:list of PublicTransportTypeType.

walkTimeMultiplier Allows to prefer or avoid public transport routes with longer walking distances. A value > 1.0 means a slower walking speed and will prefer routes with less walking distance. The provided value must be between 0.01 and 100. Type: xs:double.
walktimemultiplier=2.0
walkSpeed Specifies speed which will be used by a service as a walking speed for pedestrian routing (meters per second). This parameter affects pedestrian, publicTransport and publicTransportTimetable modes. The provided value must be between 0.5 and 2. Type:SpeedType.
walkSpeed=1.25
walkRadius Allows the user to specify a maximum distance to the start and end stations of a public transit route. Only valid for publicTransport and publicTransportTimetable routes. The provided value must be between 0 and 6000.
combineChange Enables the change maneuver in the route response, which indicates a public transit line change. In the absence of this maneuver, each line change is represented with a pair of subsequent enter and leave maneuvers. We recommend enabling combineChange behavior wherever possible, to simplify client-side development.
combineChange=true
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 a vehicle. The provided value must be between 0 and 4. Defaults to 0.

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.

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 ]

truckrestrictions=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.

Example Request

https://route.cit.api.here.com/routing/7.2/calculateroute.xml
?app_id={YOUR_APP_ID}
&app_code={YOUR_APP_CODE}
&waypoint0=geo!52.5,13.4
&waypoint1=geo!52.5,13.45
&mode=fastest;car;traffic:disabled

Example Request for SummaryByCountry

https://route.cit.api.here.com/routing/7.2/calculateroute.xml
?app_id={YOUR_APP_ID}
&app_code={YOUR_APP_CODE}
&waypoint0=geo!50.8857,14.81589
&waypoint1=geo!50.8681536,14.8308207
&routeattributes=wp,sm,sh,sc
&mode=fastest;car

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>