Calculate Route

A circle with a center point and a radius (in meters). The radius must be a positive integer with the maximum value of 135000.

A location or a circle.
Examples:

• 52.37245,4.89406
• circle(52.37245,4.89406,10000)

Comma-separated list of floats.

To be used in the POST data only.

Please refer to the

page.

The service version number.

Value: The current value is 1.

Locations through which the route is calculated. The following constraints apply:

• At least two locations must be provided.

• The first location in the sequence defines the origin and must be a location.

• The last location in the sequence defines the destination and must be a location.

• One or more optional intermediate generalizedLocations (known as waypoints in this context) may be provided:

  • The maximum allowed number of waypoints is 150.

  • A waypoint of type location results in an extra leg in the response, a waypoint of type circle does not.

  • Circle waypoints cannot be used when computeBestOrder is true.

Values: Colon-delimited generalizedLocations, with the constraints mentionned above.

Number of desired alternative routes to be calculated. The value provided:

• Must be an integer in the range 0-5.

• Using a value greater than 0 in conjunction with computeBestOrder set to true is not allowed.

• Fewer alternative routes may be returned if either fewer alternatives exist, or the requested number of alternatives is larger than the service can calculate.

When maxAlternatives is greater than 0, allows to specify the objective of computing alternative routes: finding routes that are significantly different than the reference route, or finding routes that are better than the reference route. Possible values are:

• anyRoute: returns alternative routes that are significantly different from the reference route.

• betterRoute: only returns alternative routes that are better than the reference route, according to the given planning criteria (set by routeType). If there is a road block on the reference route, then any alternative that does not contain any blockages will be considered a better route. The summary in the route response will contain information (see the planningReason parameter) about the reason for the better alternative.

Note: This optional parameter can only be used when reconstructing a route.

All alternative routes returned will follow the reference route (see the POST data parameters section) from the origin point of the calculateRoute request for at least this number of meters.

• Can only be used when reconstructing a route.

• The minDeviationDistance parameter cannot be used in conjunction with arriveAt.

All alternative routes returned will follow the reference route (see the POST data parameters section) from the origin point of the calculateRoute request for at least this number of seconds.

• Can only be used when reconstructing a route.

• The minDeviationTime parameter cannot be used in conjunction with arriveAt.

Largest index in the supportingPoints array (see the POST data parameters section) for which supportingPoints[supportingPointIndexOfOrigin] lies on or before the origin point.

The Routing API uses this index as a hint to disambiguate situations where the supportingPoints in the POST data are not planar, or where they come back close to the origin at a later point in the reconstructed route. In these cases, the supportingPointIndexOfOrigin can explicitly identify if the origin is meant to be on the later part of the route, or not.

• Can only be used when reconstructing a route.

• Cannot be used in conjunction with arriveAt.

Maximum value: Size of supportingPoints array - 1.

If specified, guidance instructions will be returned (if available). Possible values are:

• coded: returns raw instruction data without human-readable messages.

• text: returns raw instructions data with human-readable messages in plain text.

• tagged: returns raw instruction data with tagged human-readable messages to permit formatting.

Note:

The instructionsType parameter cannot be used in conjunction with routeRepresentation=none.

If alternative routes are requested, instructions will be generated for each route returned.

See the Tagged messages section for more information about tagged messages.

• coded
• text
• tagged

The language parameter determines the language of the guidance messages.

• Proper nouns (the names of streets, plazas, etc.) are returned in the specified language, or if that is not available, they are returned in an available language that is close to it.

• Allowed values are (a subset of) the IETF language tags described here.

• The currently supported languages are listed in the Supported languages section.

Re-orders the route waypoints with a fast heuristic algorithm to reduce the overall route length. Note that based on the heuristic nature of the algorithm, optimality is not guaranteed. Yields best results when used in conjunction with routeType shortest.

Possible boolean values are:

• true: compute a better order, if possible

  • Not allowed to be used in conjunction with a maxAlternatives value greater than 0.

  • Not allowed to be used in conjunction with circle waypoints.

  The response will include the reordered waypoint indices in the field optimizedWaypoints.

• false: use the locations in the given order.

  • Not allowed to be used in conjunction with routeRepresentation=none.

Specifies the representation of the set of routes provided as a response.

Possible values are:

• polyline: includes routes in the response.

• summaryOnly: as per polyline, but excluding the points elements for the routes in the response.

• none: only includes the optimized waypoint indices but does not include the routes in the response. This parameter value can only be used in conjunction with computeBestOrder=true.

• summaryOnly
• none

Specifies whether to return additional travel times using different types of traffic information (none, historic, live) as well as the default best-estimate travel time.

Possible values are:

• none: do not compute additional travel times.

• all: compute travel times for all types of traffic information, specifying all results in the fields:

  • noTrafficTravelTimeInSeconds
  • historicTrafficTravelTimeInSeconds
  • liveTrafficIncidentsTravelTimeInSeconds
  
  

  being included in the summaries in the route response.

The directional heading of the vehicle, in degrees starting at true North and continuing in a clockwise direction.

• North is 0 degrees.
• East is 90 degrees.
• South is 180 degrees.
• West is 270 degrees.

Specifies which of the section types is reported in the route response. sectionType can be specified multiple times (e.g., ...&sectionType=tollRoads&sectionType=tollVignettes&...).

Possible values are:

• carTrain: sections of the route that are car trains.

• ferry: sections of the route that are ferries.

• tunnel: sections of the route that are tunnels.

• motorway: sections of the route that are motorways.

• pedestrian: sections of the route that are only suited for pedestrians.

• tollRoad: sections of the route that require a toll to be payed.

• tollVignette: sections of the route that require a toll vignette to be present.

• country: sections indicating which countries the route is in.

• travelMode: sections in relation to the request parameter travelMode.

• traffic: sections of the route that contain traffic information.

• carpool: sections of the route that require use of carpool (HOV/High Occupancy Vehicle) lanes.

• urban: sections of the route that are located within urban areas.

• unpaved: sections of the route that are unpaved.

• lowEmissionZone: sections of the route that are located within low-emission zones.

• carTrain
• country
• ferry
• motorway
• pedestrian
• tollRoad
• tollVignette
• traffic
• tunnel
• carpool
• urban
• unpaved
• lowEmissionZone

Specifies a list of margins in kilowatt-hours (kWh) for computing reachableRouteOffsets.

• Can only be used when all of constantSpeedConsumptionInkWhPerHundredkm, maxChargeInkWh, and currentChargeInkWh are specified.

• The items in the list must be in strictly decreasing order.
• The list is restricted to exactly one item.

An array of point objects, to be used as input for route reconstruction.

An array of pointWaypoint objects, to be used to represent waypoints in a route reassessment request.

• If specified, the array must not be empty.

Contains one waypointSourceType and one supportingPointIndex object.

Denotes the source of the waypoint. Possible values:

• User_Defined: a waypoint that was explicitly defined by the user.

An index into the supportingPoints array that denotes the location of the waypoint on the reference route.

• Must be inside supportingPoints array boundaries.

An array of reassessmentParameterSet objects, to be used as input for route reassessment.

• Route reassessment provides information on how some properties of the route would be different with different input values (note that reassessment does not affect the shape of the route). For example, route reassessment can be used to quantify the impact of air conditioning use on total power consumption.

• If specified, the array must contain exactly one entry.

• A reassessmentParameterSet object is a set of parameters used together to reassess the planned route. Such an object must contain at least one parameter; currently the only supported parameter is auxiliaryPowerInkW.

The request may return more than one route.

Each object has at least a summary field and a legs field. It may contain other fields depending on the request parameters.

The summary of a route, or of a route leg.

The summary object may be extended with new fields in the future; clients should ignore fields they do not recognize.

• Included if reassessmentParameterSets is specified.

• Each object in the array corresponds to the entry with the same index in reassessmentParameterSets (see the POST data parameters) and contains the results of a reassessment using the corresponding reassessmentParameterSet.

• The objects describe particular aspects of the route as a whole. Their values may differ from those reported in the route summary.

• If the reassessmentParameterSet contains auxiliaryPowerInkW, then the corresponding object may contain the following fields (see individual field descriptions for details):

  • batteryConsumptionInkWh
  • reachableRouteOffsets

• The objects in this array may be extended with new fields in the future; clients should ignore fields they do not recognize.

A description of a part of a route, comprised of an array of points.

• Contains the summary and points fields.

• Each additional waypoint provided in the request will result in an additional leg in the returned route.

Each object in the array is a location on the surface of the globe defined by its latitude and longitude fields.

This array is available inside routeobjects.

• Contains one or more section objects.

• The structure of section objects is given below.

Index of the first point (offset 0) in the route this section applies to (only included for a routeRepresentation polyline).

Index of the last point (offset 0) in the route this section applies to (only included for a routeRepresentation polyline).

A 3-character

country code.

Type of the incident.

• Can currently be JAM, ROAD_WORK, ROAD_CLOSURE, or OTHER.

• See the tec field for detailed information.

The effective speed of the incident in km/h, averaged over its entire length.

The magnitude of delay caused by the incident.

Possible values:

• 0: unknown

• 1: minor

• 2: moderate

• 3: major

• 4: undefined, used for road closures and other indefinite delays

These values correspond to the values of the response field ty of the Online Traffic Incident Details.

Details of the traffic event. It uses the definitions in the

standard. It can contain the effectCode and causes fields.

The effect on the traffic flow. Contains a value in the tec001:EffectCode table, as defined in the

standard. Can be used to color-code traffic events according to severity.

Each object in the array describes one cause of the traffic event.

• It can contain mainCauseCode and subCauseCode fields.

• It can be used to define iconography and descriptions.

The main cause of the traffic event. Contains a value in the tec002:CauseCode table, as defined in the

standard.

The subcause of the traffic event. Contains a value in the sub cause table defined by the mainCauseCode, as defined in the

standard.

The estimated travel time in seconds. Note that even when traffic=false, travelTimeInSeconds still includes the delay due to traffic.

The delay in seconds compared to free-flow conditions according to real-time traffic information.

The portion of the route or leg, expressed in meters, that is affected by traffic events which cause the delay.

The estimated travel time in seconds calculated as if there are no delays on the route due to traffic conditions (e.g., congestion). Included if requested using the computeTravelTimeFor parameter.

The estimated travel time in seconds calculated using time-dependent historic traffic data. Included if requested using the computeTravelTimeFor parameter.

The estimated travel time in seconds calculated using real-time speed data. Included if requested using the computeTravelTimeFor parameter.

The distance (in meters) from the origin point of the calculateRoute request to the first point where this route forks off from the reference route.

• If the route is identical to the reference route, then this field is set to the length of the route.

• Included in all alternative (but not reference) route summary fields.

The travel time (in seconds) from the origin point of the calculateRoute request to the first point where this route forks off from the reference route.

• If the route is identical to the reference route, then this field is set to the estimated travel time of the route.

• Included in all alternative (but not reference) route summary fields.

The coordinates of the first point following the origin point of the calculateRoute request where this route forks off from the reference route.

• If the route is identical to the reference route, then this field is set to the coordinates of the last point on the route.

• Included in all alternative (but not reference) route summary fields.

The estimated fuel consumption in liters using the Combustion Consumption Model. Included if:

• The vehicleEngineType is set to combustion .

• The constantSpeedConsumptionInLitersPerHundredkm is specified.

• The value will be non-negative (i.e., positive).

The estimated electric energy consumption in kilowatt hours (kWh) using the Electric Consumption Model.

• Included if:

  • vehicleEngineType is set to electric.

  • constantSpeedConsumptionInkWhPerHundredkm is specified.

• The value of batteryConsumptionInkWh includes the recuperated electric energy and can therefore be negative (which indicates gaining energy).

• If both maxChargeInkWh and currentChargeInkWh are specified, recuperation will be capped to ensure that the battery charge level never exceeds maxChargeInkWh.

• If neither maxChargeInkWh nor currentChargeInkWh are specified, unconstrained recuperation is assumed in the consumption calculation.

This field is included if chargeMarginsInkWh is specified. It is not present in the leg summary field. Each object in the array corresponds to an entry in chargeMarginsInkWh, and describes the reachable point on the route with respect to the charge margin specified there. Effectively, the farthest the vehicle can go on the route on its current charge, without depleting the battery beyond the specified margin.

• Objects in the array contain the following fields:

  • chargeMarginInkWh: the charge margin this reachable point is calculated for.

  • point: location of the reachable point defined as a latitude longitude pair.

  • pointIndex: largest index in the polyline of the route for which points[pointIndex] lies on or before point.

  • routeOffsetInMeters: the distance from the start of the route to the reachable point.

• Note that:

  • If currentChargeInkWh is less than or equal to chargeMarginInkWh, routeOffsetInMeters is zero.

  • routeOffsetInMeters is at most lengthInMeters.

  • Charging stops are ignored in the computation so that e.g., live traffic is used as if driving past any charging station.

A description of an optimized sequence of waypoints. It shows the index from the user-provided waypoint sequence for the original and optimized list. For instance, a response:

1{
2  "optimizedWaypoints": [
3    {
4      "providedIndex": 0,
5      "optimizedIndex": 1
6    },
7    {
8      "providedIndex": 1,
9      "optimizedIndex": 2
10    },
11    {
12      "providedIndex": 2,
13      "optimizedIndex": 0
14    }
15  ]
16}

means that:

• The original sequence is [0, 1, 2].

• The optimized sequence is [1, 2, 0].

Since the index starts by 0 the original is "first, second, third", while the optimized is "second, third, first".

The estimated departure time for the route or leg. Specified as a dateTime.

The estimated arrival time for the route or leg. Specified as a dateTime.

This contains guidance related fields. This field is present only when guidance was requested and is available.

A set of attributes describing a maneuver, e.g., "Turn right", "Keep left", "Take the ferry", "Take the motorway", "Arrive".

This groups a sequence of instruction elements which are related to each other.

• The sequence range is constrained with firstInstructionIndex and lastInstructionIndex.

• When human-readable text messages are requested for guidance ( instructionType=text or tagged), then the instructionGroup has a summary message returned when available.

Each object in the array represents an effective parameter or a data used when calling the Calculate Route API. Each object has fields key and value both containing a string describing the input and its value.

The original HTTP status code as listed in the response codes (note: included for content type jsonp only).

The reason for a better route proposal. Can currently be:

• Blockage in case the reference route contains road blockages. The returned value is implementation-defined in case both reasons for a better proposal are applicable to the same route.

• Better_Proposal in case the alternative type is better then the reference route, according to the given planning criteria (set by routeType).

This field is included in the response only if the route is requested with alternativeType=betterRoute. This field is not present in the leg summary field.

The distance from the start of the route to the point of the instruction.

The estimated travel time up to the point corresponding to

.

Location of the maneuver. Example:

1"point":{
2  "latitude":52.36965,
3  "longitude":4.70208
4}

The index of the point in the array of polyline points.

Equivalent to startPointIndex and endPointIndex in sections:

• Largest index in the polyline of the route for which points[pointIndex] lies on or before point .

• In particular you may assume that point lies on points[pointIndex] or on the route segment described by points[pointIndex] and points[pointIndex+1].

The type of instruction, e.g., a turn or a change of road form.

• TURN
• ROAD_CHANGE
• LOCATION_DEPARTURE
• LOCATION_ARRIVAL
• DIRECTION_INFO
• LOCATION_WAYPOINT

This lists the road number of the next significant road segment after the maneuver, or of the road that has to be followed.

Example:

"roadNumbers":["E34","N205"]

A string telling the number(s) of a highway exit taken by the current maneuver. If an exit has multiple exit numbers, numbers will be separated by "," and possibly aggregated by "-", e.g., "10, 13-15".

The street name of the next significant road segment after the maneuver, or of the street that should be followed.

The text on a signpost which is most relevant to the maneuver, or to the direction that should be followed.

The 3-character

country code.

A subdivision (e.g., state) of the country, represented by the second part of an

code. This is only available for some countries like the US, Canada, and Mexico.

The type of the junction where the maneuver takes place. For larger roundabouts, two separate instructions are generated for entering and leaving the roundabout.

• REGULAR
• ROUNDABOUT
• BIFURCATION

Indicates the direction of an instruction. If junctionType indicates a turn instruction:

• -180 = U-turn

• [-179, -1] = Left turn

• 0 = Straight on (a '0 degree' turn)

• [1, 179] = Right turn

If junctionType indicates a bifurcation instruction:

• <0 - keep left

• >0 - keep right

It is possible to optionally combine the instruction with the next one. This can be used to build messages like "Turn left and then turn right".

• true
• false

Indicates left-hand vs. right-hand side driving at the point of the maneuver.

• LEFT
• RIGHT

A code identifying the maneuver (e.g., "Turn right"). See the following Maneuver codes section.

A human-readable message for the maneuver combined with the message from the next instruction. See the following example of a combined message section.

Contains the response section type.

The COUNTRY sections span between country border crossings, from the departure, or to the destination.

• The section additionally contains countryCode.

• If the route has disjointed parts in the same country, there will be several sections with the same countryCode.

• If no country can be assigned to a part of the route, as for example in international waters, there may be no country section for this part.

  • A TOLL_VIGNETTE section additionally contains a countryCode since toll vignettes are often specific to a country.

  • A TRAFFIC section may additionally contain any of the following: simpleCategory, effectiveSpeedInKmh, delayInSeconds, magnitudeOfDelay, tec.

  • TRAVEL_MODE sections cover the whole route. Each section's travel mode is reported in travelMode .

  • CARPOOL sections contain parts of the route that are only open to HOV (high-occupancy vehicles) at the time of traversal. Roads with at least one unrestricted lane are not part of a CARPOOL section.

This field is either set to the value given to the request parameter travelMode, if this travel mode is possible, or to other which indicates that the given mode of transport is not possible in this section. This field can only be used within sections of type TRAVEL_MODE.

This is the legacy version of detailedError.
The description field has the same content as the message field in detailedError.

This object provides a representation of the error message. It contains a code and a message field.

The original HTTP status code as listed in response codes (included for content type jsonp only).