Long Distance EV Routing

Latitude, longitude pair (in EPSG:4326 projection), with the following constraints:

• Latitude values must be in the range [-90, +90].

• Longitude values must be in the range [-180, +180].

Example: 52.37245,4.89406

A location represented as a JSON object to be used in the POST data only. The object should contain the two fields latitude and longitude each containing a number, and expressed in the same reference frame and with the same constraints as for the location type. Example: {"latitude": 52.37245, "longitude": 4.89406}

A date and time specified in RFC 3339 format with an optional time zone offset. Examples:

• 2023-12-19T16:39:57
• 2023-12-19T16:39:57-08:00

Comma-separated speedInkmh,consumptionInkWhPerHundredkm pairs with the following constraint: The speedInkmh values must be in the range [0.0, 255.0]. Example: 15.5,8.0

Comma-separated list of floats. Example: 1.23,0

Avoids toll roads.

Avoids motorways.

Avoids ferries.

Avoids unpaved roads.

Avoids routes that require use of carpool (HOV/High Occupancy Vehicle) lanes.

Avoids using the same road multiple times.

Avoids crossing country borders.

Avoids tunnels.

Avoids car trains.

Avoids low-emission zones.

• Small_Paddle_Inductive
• Large_Paddle_Inductive
• IEC_60309_1_Phase
• IEC_60309_3_Phase
• IEC_62196_Type_1_Outlet
• IEC_62196_Type_2_Outlet
• IEC_62196_Type_3_Outlet
• IEC_62196_Type_1_Connector_Cable_Attached
• IEC_62196_Type_2_Connector_Cable_Attached
• IEC_62196_Type_3_Connector_Cable_Attached
• Combo_to_IEC_62196_Type_1_Base
• Combo_to_IEC_62196_Type_2_Base
• Type_E_French_Standard_CEE_7_5
• Type_F_Schuko_CEE_7_4
• Type_G_British_Standard_BS_1363
• Type_J_Swiss_Standard_SEV_1011
• China_GB_Part_2
• China_GB_Part_3
• IEC_309_DC_Plug
• AVCON_Connector
• Tesla_Connector
• NEMA_5_20
• CHAdeMO
• SAE_J1772
• TEPCO
• Better_Place_Socket
• Marechal_Socket
• Standard_Household_Country_Specific

• Battery_Exchange
• Charge_100_to_120V_1_Phase_at_8A
• Charge_100_to_120V_1_Phase_at_10A
• Charge_100_to_120V_1_Phase_at_12A
• Charge_100_to_120V_1_Phase_at_13A
• Charge_100_to_120V_1_Phase_at_16A
• Charge_100_to_120V_1_Phase_at_32A
• Charge_200_to_240V_1_Phase_at_8A
• Charge_200_to_240V_1_Phase_at_10A
• Charge_200_to_240V_1_Phase_at_12A
• Charge_200_to_240V_1_Phase_at_12A
• Charge_200_to_240V_1_Phase_at_20A
• Charge_200_to_240V_1_Phase_at_32A
• Charge_200_to_240V_1_Phase_above_32A
• Charge_200_to_240V_3_Phase_at_16A
• Charge_200_to_240V_3_Phase_at_32A
• Charge_380_to_480V_3_Phase_at_16A
• Charge_380_to_480V_3_Phase_at_32A
• Charge_380_to_480V_3_Phase_at_63A
• Charge_50_to_500V_Direct_Current_at_62A_25kW
• Charge_50_to_500V_Direct_Current_at_125A_50kW
• Charge_200_to_450V_Direct_Current_at_200A_90kW
• Charge_200_to_480V_Direct_Current_at_255A_120kW
• Charge_Direct_Current_at_20kW
• Charge_Direct_Current_at_50kW
• Charge_Direct_Current_above_50kW

• Direct_Current
• Alternating_Current_1_Phase
• Alternating_Current_3_Phase

• No_Payment
• Subscription
• Direct

Specifies the MIME type of the request body. Value: application/json

Requests that the response be compressed. Value: gzip

Specifies the compression used for the request body. Currently, only gzip is supported. If not specified, no compression is assumed. This is equal to specifying identity. Values:

• identity
• gzip

Specifies an identifier for the request.

• The value should be unique for each request.

• The value must match the regular expression '^[a-zA-Z0-9-_\.]{1,100}$'.

• If specified, the same value is sent back in the similar-named response header. Otherwise, a generated value may be sent back.

Base URL for calling the API. Values:

• api.tomtom.com: The default global API endpoint.

• kr-api.tomtom.com: The region-specific endpoint for South Korea. See the Region-specific content documentation.

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 locations (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.

Values: Colon-delimited locations, with the constraints mentioned above.

The only possible value for the Long Distance EV Routing service is json.

Authorization key to access the API. Value: Your valid API Key.

This parameter has been deprecated. It may be removed in the future. Only allowed value: electric

Specifies the current electric energy supply in kilowatt hours (kWh). Minimum value: 0.0
Maximum value: The vehicle's battery capacity defined by given maxChargeInkWh.

The battery level upon arrival at the destination of the resulting route will be at least this much. Minimum value: 0.0
Maximum value: Less than the vehicle's battery capacity defined by given maxChargeInkWh.

The desired minimum battery charge level upon arrival at each charging station. However, the remaining charge at the first charging stop may be lower. See minChargeAtFirstChargingStopInkWh for more information. Minimum value: 0.0
Maximum value: 0.5 × maxChargeInkWh

Specifies which data should be reported for diagnostic purposes. A possible value is: effectiveSettings.

• Reports the effective parameters or data used when calling the API.

• In the case of defaulted parameters, the default will be reflected where the parameter was not specified by the caller.

Default value: effectiveSettings

The date and time of departure from the origin point.

• Departure times apart from now must be specified as a dateTime.

• When a time zone offset is not specified, it is assumed to be that of the origin point.

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

Default value: now
Other value: dateTime

The date and time of arrival at the destination point.

• It must be specified as a dateTime.

• When a time zone offset is not specified, it is assumed to be that of the destination point.

The arriveAt parameter cannot be used in conjunction with:

• departAt
• minDeviationDistance
• minDeviationTime
• supportingPointIndexOfOrigin

Value: dateTime

Specifies the type of optimization used when calculating routes. The only possible value in the Long Distance EV Routing service is fastest. Route calculation is optimized by travel time, while keeping the routes sensible. For example, the calculation may avoid shortcuts along inconvenient side roads or long detours that only save very little time.

The only possible value for the Long Distance EV Routing service is true. With this value, all the available traffic information during routing will be considered.
Depending on availability, the Routing API takes road closures and road works into account that are up to 60 days in the future.

Specifies something that the route calculation should try to avoid when determining the route. The avoid can be specified multiple times (e.g., ...&avoid=motorways&avoid=ferries&...). Possible values are listed under Avoid parameter possible values.

Specifies something that the route calculation should try to prefer when determining the route. Possible value:

• handsFreeDriving: Prefer stretches that allow for hands-free driving.

  • If this parameter is set, then handsFreeDrivingCapability must also be set.

Specifies the hands-free driving capability of the vehicle. The available hands-free driving data is matched against handsFreeDrivingCapability in order to filter for the subset of data that applies to the specific capability of the vehicle.

• The value must match the regular expression '^[a-zA-Z0-9-:]{1,100}$'.

The mode of travel for the requested route.

• Note that the requested travelMode may not be available for the entire route.

• Where the requested travelMode is not available for a particular section, the travelMode field of the response for that section will be set to "other".

• Full restriction data is not available in all areas.

Default value: car
Other values:

• truck
• bus
• van
• motorcycle

Maximum speed of the vehicle in kilometers/hour.

• Must have a value in the range [0, 250].

• A value of 0 means that an appropriate value for the vehicle will be determined and applied during route planning.

Default value: 0

Weight of the vehicle in kilograms.

• This is required if any of the accelerationEfficiency, decelerationEfficiency, uphillEfficiency, downhillEfficiency parameters are set.

• It must be strictly positive with a minimum value 1 when used in the context of the Electric Consumption model.

• Weight restrictions are considered.

Default value: 0

Weight per axle of the vehicle in kilograms. A value of 0 means that weight restrictions per axle are not considered.
Default value: 0

Number of axle of the vehicle. A value of 0 means that the number of axle restrictions is not considered.
Default value: 0

Length of the vehicle in meters, including the length of any additional equipment, e.g., trailers, bike racks, etc. A value of 0 means that length restrictions are not considered. Fractional digits are rounded to the closest centimeter while rounding up on a tie.
Default value: 0

Width of the vehicle in meters. A value of 0 means that width restrictions are not considered. Fractional digits are rounded to the closest centimeter while rounding up on a tie.
Default value: 0

Height of the vehicle in meters. A value of 0 means that height restrictions are not considered. Fractional digits are rounded to the closest centimeter while rounding up on a tie.
Default value: 0

Vehicle is used for commercial purposes and thus may not be allowed to drive on some roads.
Default value: false

Specifies types of cargo that may be classified as hazardous materials and are restricted from some roads. The vehicleLoadType parameter can be specified multiple times (e.g.,

or

). Available values are:

• US Hazmat classes 1 through 9
• Generic classifications for use in other countries.

Use these values for routing in the USA:

• USHazmatClass1: Explosives

• USHazmatClass2: Compressed gas

• USHazmatClass3: Flammable liquids

• USHazmatClass4: Flammable solids

• USHazmatClass5: Oxidizers

• USHazmatClass6: Poisons

• USHazmatClass7: Radioactive

• USHazmatClass8: Corrosives

• USHazmatClass9: Miscellaneous

Use these values for routing in all other countries:

• otherHazmatExplosive: Explosives

• otherHazmatGeneral: Miscellaneous

• otherHazmatHarmfulToWater: Harmful to water

Notes: The vehicleLoadType and vehicleAdrTunnelRestrictionCode parameters are independent; please provide both if applicable.

If vehicleAdrTunnelRestrictionCode is specified, the vehicle is subject to ADR tunnel restrictions.

• Vehicles with code B are restricted from roads with ADR tunnel categories B, C, D, and E.

• Vehicles with code C are restricted from roads with ADR tunnel categories C, D, and E.

• Vehicles with code D are restricted from roads with ADR tunnel categories D and E.

• Vehicles with code E are restricted from roads with ADR tunnel category E.

• If vehicleAdrTunnelRestrictionCode is not specified, no ADR tunnel restrictions apply.

Notes: The vehicleAdrTunnelRestrictionCode and vehicleLoadType parameters are independent; please provide both if applicable. Values (specify at most one):

• B
• C
• D
• E

Reference: European Agreement Concerning the International Carriage of Dangerous Goods by Road (ADR), United Nations, 2019, section 1.9.5 and chapter 8.6

Specifies the route calculation should try to avoid ETC-transponder-only toll roads when determining the route if a vehicle does not have an ETC transponder. Possible values are:

• all: Do not avoid ETC-transponder-only toll roads.
• none: Avoids ETC-transponder-only toll roads.

If this parameter is not specified, ETC-transponder-only toll roads are not avoided.

Specifies the precision of coordinates in the response. Possible values are:

• default: All coordinates are rounded to 5 digits after the decimal point. Default precision coordinates are targeted towards clients that are sensitive to response sizes. This should be sufficient for most applications.

• full: All coordinates are rounded to 7 digits after the decimal point. Full precision coordinates are targeted towards applications that require precise polyline visualization at high zoom levels.

Default value: default
Other value: full

Specifies how to reconstruct a given polyline or individual legs. Note: this parameter can only be used when a route or legs are provided as part of the request by using supportingPoints or encodedPolyline. For a description of supportingPoints and encodedPolyline see the Post Data section of this document. Possible values are:

• normal: Some leeway is allowed when the provided polyline doesn't exactly match the road network, such that a most sensible route is reconstructed. Use this option in case the given polyline comes from a third party source such as a recorded track, a different routing service, or user input. Please consider using the track mode, it is newer and gives better results.

• strict: Reconstruct the given route as close as possible to the given polyline. This might mean that some driving restrictions are violated in order to closely match the original route. Use this option when reconstructing a route previously received from this service.

• track: This mode provides flexibility when the provided route polyline does not align well with the road network, allowing the reconstruction of the most sensible route. The input polyline may have inconsistencies such as gaps and loops. When reconstructing the route using track mode, the algorithm will try to respect the driving restrictions and consider traffic conditions. Use this mode when the given polyline originates from a third-party source such as a recorded track, a different routing service, or user input.

• update: Reconstruct the given route as close as possible to the provided route polyline, ignoring time-dependent driving and legal restrictions in order to keep the input polyline geometry stable. The input polyline is expected to be normalized, without any loops or gaps. Use this option to refresh dynamic data, as required during navigating along your route. Notice: The resulting reconstructed route tries to accurately follow the road network and might result in an illegal route due to potential violation of driving restrictions.

Note: In any of the modes, the algorithm might relax certain restrictions near the origin and destination to offer a more sensible route instead of a no-route-found. This ensures that routes planned with our service can be reconstructed.
Default value: normal
Other values:

• strict
• track
• update

In short, this table summarizes the differences between the modes and restrictions:

Specifies the preference of roadside on arrival to waypoints and destination. Stop on the road has to be set at least two meters to the preferred side, otherwise the behavior will default to anySide. Possible values are:

• anySide: Both sides of a road could be used to approach the waypoint and destination. When a vehicle arrives, a stop could be either on a left side or a right side.

• curbSide: Ensures a minimal number of road crossings at waypoints or the destination. When a vehicle arrives, a stop should be on the right for the right-side driving road or on a left for the left-side driving road.

Default value: anySide
Other value: curbSide

Number of desired alternative routes to be calculated. Fewer alternative routes may be returned if either fewer alternatives exist, or the requested number of alternatives is larger than the service can calculate. Default value: 0
Maximum value: 5

When maxAlternatives is greater than 0, it allows you to specify the objective of computing alternative routes and includes 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: The betterRoute value can only be used when reconstructing a reference route. Default value: anyRoute
Other values: betterRoute

All alternative routes returned will follow the reference route (see the POST data parameters section) from the origin point of the calculateLongDistanceEVRoute 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 calculateLongDistanceEVRoute 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 array of supportingPoints per route or in joined arrays of supportingPoints per leg (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.

Minimum value: 0
Maximum value: One less than the size of supportingPoints array.

Specifies the representation of the set of routes provided as a response. Possible values are:

• polyline: Includes routes in the response as polylines. The polylines are returned in the points fields in the response.

• encodedPolyline: Includes routes in the response in the encoded polyline format. The encoded polylines are returned in the encodedPolyline fields and their precisions in the encodedPolylinePrecision fields in the response.

• summaryOnly: As per polyline, but excluding the points fields for the routes in the response.

Default value: polyline
Other values:

• encodedPolyline
• summaryOnly

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.

Maximum value: 359
Other values: 0-359
Note: The vehicle heading is ignored when doing the base route reconstruction if reconstructionMode is set to strict or update.

Specifies which of the section types is reported in the route response. sectionType can be specified multiple times (e.g., ...&sectionType=tollRoad&sectionType=tollVignette&...). 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 paid.

• toll: sections of the route with the usage-based toll collection system (i.e., distance-based tolls, toll bridges and tunnels, weight-based tolls).

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

• roadShields: sections with road shield information. A road shield section contains roadShieldReferences, which is a list of references for the road shields (roadShieldReference). Please refer to the structure of a road shield reference object for further information.
  Notes: If this section type is requested, calculateRouteResponse contains the additional field roadShieldAtlasReference. Please refer to the notes about the road shield atlas for further information. The road shields are only available in these supported countries.

• speedLimit: Sections with legal speed limit information. maxSpeedLimitInKmh: The maximum legal speed limit in kilometers/hour. This can be time-dependent and/or vehicle-dependent.

  • Time can be set by either the departAt or the arriveAt request parameters. In the case of a time-dependent speed limit, the section will contain the speed limit effective at the time the planned route would enter this section.

  • Vehicle information can be set by adjusting the travelMode and vehicle* request parameters.

  • Requesting legal speed limits is only valid if travelMode is adjusted to be a motorized vehicle ( car, truck, bus, van, or motorcycle).

• handsFreeDriving: Sections of the route applicable for hands-free driving.

  • Note: If this parameter is set, then the parameter handsFreeDrivingCapability must also be set.

  • Note: If this parameter is set, and the parameter prefer=handsFreeDriving is not set, the response may contain hands-free sections, but the route will not prefer stretches that allow hands-free driving.

• importantRoadStretch: Sections with important stretches of road information. importantRoadStretch provides a set of street names and/or a set of road numbers that allow the driver to identify and distinguish the course of the route (from other potential routes).

Include toll payment types in the toll section. If a toll section has different toll payment types in its subsections, this toll section splits into multiple toll sections with the toll payment types. Possible values:

• all: Include toll payment types in the toll section.
• none: Do not include toll payment types in the toll section.

The value all must be used together with sectionType=toll. Default value: none

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.

Minimum value: 0
Maximum value: 0

Specifies the extended representation of the set of routes provided as a response. <extendedRouteRepresentation> can be specified multiple times (e.g., ...&extendedRouteRepresentation=distance&extendedRouteRepresentation=travelTime&extendedRouteRepresentation=consumption&... ). <extendedRouteRepresentation> can only be specified when contentType is json and routeRepresentation is polyline or encodedPolyline. Possible values are:

• distance: Includes distances to route polyline points in the response.

• travelTime: Includes travel times to route polyline points in the response.

• consumption: Includes consumption values to route polyline points in the response.

  • Can only be used when the constantSpeedConsumptionInkWhPerHundredkm is specified.

This feature allows EV drivers to manually choose the charging stops along their itinerary, while optimizing charging times for minimal Estimated Travel Time (ETT). Possible values are:

• automaticFastest: The service automatically generates charging stops that minimize the total ETT, including charging time.

• manualFastest: The service does not add charging stops to the route.

  • It calculates the fastest route visiting charging and non-charging waypoints, optimizing charging times at the former to minimize the total ETT, with respect of the minimal charge at charging stops and destination when possible.
  • Since no additional charging stops are added to the route, it may happen that arrival charges at waypoints and destination are below the corresponding minimal charge, or even null or negative.
  • When a charging stop or the destination is unreachable, the target charge at the previous charging stop, when it exists, is set to 100% of the vehicle's charge capacity.

Default value: automaticFastest
For both values, charging waypoints are specified by adding their coordinates in the locations part of the URL and their charging park IDs in the corresponding chargingWaypoints item of the post data.

The desired minimum battery charge level upon arrival at the first charging station. If this parameter is not provided, an internal formula determines its value to allow route calculations with low current charge.
Minimum value: 0.0
Maximum value: minChargeAtChargingStopsInkWh

Upon arrival at the destination, the minimum battery charge level may be reduced to this value if it allows the planning of a route without any charging stops. For example, if the driver has a personal home charger and sets the home as the destination, it could be okay to arrive there with a charge level lower than minChargeAtDestinationInkWh

The language parameter determines the language of the returned names of places in general and also of the messages and phonetic translations in guidance.

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

• The currently supported languages are listed on the Supported Languages page. The allowed values for the language parameter are the IETF language tags (or abbreviations in some cases) provided there.

A piecewise-constant function which maps a state of charge (SoC) of a battery to the maximum charging power supported for this state of charge. It is used to compute the charging times of the vehicle. It must contain zero to up to 20 (inclusive) JSON objects each containing the properties stateOfChargeInkWh and maxPowerInkW. The stateOfChargeInkWh of each entry in the curve defines the lower bound (included) of the half-open interval this maximum charging power applies to, with the possible exception of the interval corresponding to the lowest SoC, which is implicitly extended towards a state of charge of 0.
The following requirements must be fulfilled:

• stateOfChargeInkWh must be larger than or equal to zero.

• None of the stateOfChargeInkWh values from such an object may equal the stateOfChargeInkWh value of any other object.

• maxPowerInkW must be larger than zero.

If an empty curve is provided, the charging power will be limited solely by the maximum power of the specified connectors and the charging facility's supported charging power.

Must be a non-empty array of chargingConnector elements. No chargingConnector may be equivalent to another, where equivalent chargingConnector elements:

• have the same currentType

• share at least one element of plugTypes

• have an overlapping voltageRange

One of the values AC1, AC3 for single- or three-phase alternating current, or DC for direct current.

A non-empty list of plugType elements. See the plugType values table for possible values of plugType.

A constant time offset in seconds added to the computed charging time at each charging stop planned along the route. If not specified, the default value 60 applies. It must be larger than or equal to zero.

Optional efficiency factor applied to the power provided by a charging facility and the maximum charging power for each point of the battery charging curve. If not specified, the default value 1.0 applies. It must be larger than zero and smaller than or equal to one.

An optional base load considered when determining the available charging power. The base load is subtracted from the power provided by the charging facility prior to applying the efficiency factor. If not specified, the default value 0.0 applies. It must be larger than zero.

Sets an upper limit for the charging power. The resulting charging power is the minimum of the charging power supported by the respective charging facility and this value. It must be a positive number or zero, where 0 implies the power is only limited by the charging facility. If not specified, the default value of 0 applies.
Note: If a non-empty battery charging curve is specified, a potentially lower maximum charging power at a given state of charge according to the curve takes precedence over the maximum power specified here when calculating the predicted charging time.

Sets an upper limit for the voltage when charging. The resulting voltage is the minimum of the voltage supported by the respective charging facility and this value. It must be a positive number or zero, where 0 implies the voltage is only limited by the charging facility. If not specified, the default value of 0 applies.

Sets an upper limit for the current when charging. The resulting amperage is the minimum of the amperage supported by the respective charging facility and this value. It must be a positive number or zero, where 0 implies the amperage is only limited by the charging facility. If not specified, the default value of 0 applies.

Specifies a voltage range as a right-open interval for the connector, defaulting to the range [0, infinity) if not specified. It must contain the fields minVoltageInV and maxVoltageInV specifying minimal (included) and maximal (excluded) voltage values.

• minVoltageInV must be a positive number or zero.

• maxVoltageInV must be a number greater than minVoltageInV or 0, which is treated as infinity.

Note: Explicitly specifying the voltage range of a connector may be necessary when the vehicle supports multiple connectors with the same current type (typically DC) and plug type, with each connector supporting different maximum charging powers depending on the voltage.

A string matching a facilityType in the following facilityType values table.

A string matching a plugType in the following plugType values table.

A battery charge level in kWh.
Minimum value: 0 Maximum value: 100000.0

A time span in seconds. A non-negative integer.

A supporting point of a charging curve consisting of chargeInkWh and timeToChargeInSeconds such that the time it takes to charge the battery from 0kWh to chargeInkWh kWh is given by timeToChargeInSeconds.

A piecewise-linear function which maps a target charge level to the time it takes to charge an empty battery to this level, that is used to compute charging times of the vehicle.

• It is given by a sequence of at most 10 non-duplicate chargingCurveSupportPoints that are totally, increasingly ordered in timeToChargeInSeconds and chargeInkWh.

• The last chargeInkWh is maxChargeInkWh.

• The curve is given by connecting the given points in order after adding the first point:

  Creating a curve

  { "chargeInkWh": 0.0, "timeToChargeInSeconds": 0 }

  1{
  2    "chargeInkWh": 0.0,
  3    "timeToChargeInSeconds": 0
  4}

Contains one facilityType and one plugType which are compatible with the vehicle.

A non-empty list of at most 20 unique chargingConnections which result in the same charging curve.

Contains chargingConnections and a chargingCurve that describes the charging behavior of the vehicle using the specified charging connections.

A non-empty list of at most 10 chargingModes, which the vehicle is able to use to charge. Each chargingConnection appears in at most one chargingMode.

This is an array of strings. Each string should be a 3-character, ISO 3166-1, alpha-3 country code.

• The array describes the countries in which all toll roads with vignettes are to be avoided.

• Toll roads with vignettes in countries not in the array are unaffected.

Note: It is an error to specify both avoidVignette and allowVignette.

This is an array of strings. Each string should be a 3-character, ISO 3166-1, alpha-3 country code.

• The array describes the countries in which toll roads with vignettes are allowed.

• Specifying allowVignette with an array of countries is equivalent to specifying avoidVignette with the array of all countries other than those specified in allowVignette.

• Specifying allowVignette with an empty array is the same as avoiding all toll roads with vignettes.

Note: It is an error to specify both avoidVignette and allowVignette.

An array of point objects, to be used as input for route reconstruction. supportingPoints and encodedPolyline are alternative representation formats and cannot be used simultaneously. See the Route geometry representation formats section for further information.

A string in the Encoded polyline format representing the array of points to be used as input for route reconstruction. The precision used to encode the polyline must be set in the encodedPolylinePrecision field. supportingPoints and encodedPolyline are alternative representation formats and cannot be used simultaneously. See the Route geometry representation formats section for further information.

The precision used to encode the polyline in the encodedPolyline field.

• Must be 5 or 7.
• Must be paired with encodedPolyline.

An array of pointWaypoint objects, to be used to represent waypoints when reconstructing a route.

• If specified, the array must not be empty.

• If specified, all location waypoints in the routePlanningLocations will be ignored.

Contains one waypointSourceType and one supportingPointIndex object. See the pointWaypoints section for more details.

A list of one or more chargingWaypoint elements. Note that:

• Two consecutive chargingWaypoint elements should have waypointIndex values in ascending order.

• Two consecutive chargingWaypoint elements with consecutive waypointIndex values should not have the same chargingParkId.

A chargingWaypoint object describes charging stop details. It contains: a waypointIndex and a chargingParkId. The details, such as the charging park unique identifier (UUID), of all the charging stops in the locations list must be provided under this parameter. If the charging stop details are not provided then the location is considered as a non-charging waypoint. See the chargingWaypoints section for more details.

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.

An array of objects with the parameters for the computation of each leg. If the parameter is such that it is available for use in the query parameters, then its simultaneous use in the query parameters and in the POST data is prohibited, and such a request will be returned with an error. If the legs field is present in the POST data, then the number of elements in the array must be equal to the number of waypoints + 1. If there is no need to specify any parameters for some leg, then an empty object must be specified. In the context of calculateLongDistanceEvRoute it may only contain the routeStop field.

A non-empty list of UUIDs of charging parks to avoid in the route. You can specify up to 40 charging parks to be avoided. Every element must follow the format specified in RFC4122. This is a soft avoid, i.e., a route with avoided parks is returned if no other route can be found.

A list of unique preferred operators to use in the route. You can specify up to 20 preferred operators.

A list of unique operators to avoid in the route. You can specify up to 40 operators to be avoided. This is a soft avoid, i.e., a route with avoided operators is returned if no other route can be found.

A non-empty JSON array of unique Plug-and-Charge Providers. The charging parks with these providers are preferred if there is a connector available that supports Plug-and-Charge. You can specify up to 20 Plug-and-Charge preferred providers. Each string can be up to 40 letters long.

The name of the preferred Mobility Service Provider (MSP). It can be up to 40 characters long.

A non-empty JSON array of one or more preferredMSP elements. The specified Mobility Service Providers (MSPs) will be given a precedence over other MSPs during route search. The MSPs supported at a charging park can be seen in the response in the brand field of a chargingParkPaymentOption. Note that:

• The preferredMSP elements should be unique.

• The number of preferredMSP elements should not exceed 20.

Must contain a chargingParkId field. Please see Calculating Long Distance EV Route with a charging park as the final destination section for more details.

Specifies additional parameters for the stop at the end of the current leg. See route stop for details.

Specifies the waiting time at route stops (including charging time). It must be 0 in the last leg (the destination). Default value: 0

Specifies the entry points for the stop at the end of the current leg. The route to the stop is calculated based on these entry points. Entries with the same location are not allowed.

Latitude of the entry point. Required.

Longitude of the entry point. Required.

Denotes the source of the waypoint. Possible values:

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

• AUTO_GENERATED: a waypoint that was defined by the system (e.g., the charging stop that was provided as a result of the LDEV route enhancement).

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

• Must be inside supportingPoints array boundaries.

Specified if the waypoint is a charging stop. Must contain the fields chargingConnectionInfo, chargingParkUuid, chargingTimeInSeconds, and targetChargeInkWh.

• chargingConnectionInfo must contain chargingPlugType and may contain chargingCurrentType, chargingPowerInkW ,chargingVoltageInV, and chargingCurrentInA

A positive integer depicting the charging waypoint's index in the route planning locations list. Must be in the range 1-150.

A non-blank string depicting the ID of the charging park, which is at the index waypointIndex in the locations list. The user can retrieve this ID from the TomTom EV Search.

Specifies the speed-dependent component of consumption.

• Provided as an unordered list of speed/consumption-rate pairs.

• The list defines points on a consumption curve.

Consumption rates for speeds not in the list are found as follows:

• By linear interpolation, if the given speed lies in between two speeds in the list.

• By linear extrapolation otherwise, assuming a constant (ΔConsumption/ΔSpeed) determined by the nearest two points in the list.

The list must contain between 1 and 25 points (inclusive), and may not contain duplicate points for the same speed.

• If it only contains a single point, then the consumption rate of that point is used without further processing.

• Consumption specified for the largest speed must be greater than or equal to that of the penultimate largest speed. This ensures that extrapolation does not lead to negative consumption rates.

• Similarly, consumption values specified for the two smallest speeds in the list cannot lead to a negative consumption rate for any smaller speed. The minimum and maximum values described here refer to the valid range for the consumption values (expressed in kWh/100km).

Minimum value: 0.01
Maximum value: 100000.0

Specifies the maximum electric energy supply in kilowatt hours (kWh) that may be stored in the vehicle's battery. Note: Requires currentChargeInkWh to be set. Minimum value: currentChargeInkWh

Specifies the amount of power consumed for sustaining auxiliary systems, in kilowatts (kW). It can be used to specify consumption due to devices and systems such as AC systems, radio, heating, etc.
Minimum value: 0.0

Specifies the efficiency of converting electric energy to kinetic energy when the vehicle accelerates (i.e., KineticEnergyGained/ ElectricEnergyConsumed). Notes:

• It must be paired with decelerationEfficiency.
• It cannot be used with consumptionInkWhPerkmAltitudeGain or recuperationInkWhPerkmAltitudeLoss.

Minimum value: 0.0
Maximum value: 1/decelerationEfficiency

Specifies the efficiency of converting kinetic energy to electric energy when the vehicle decelerates (i.e., ElectricEnergyGained/ KineticEnergyLost). Notes:

• It must be paired with accelerationEfficiency.

• It cannot be used with consumptionInkWhPerkmAltitudeGain or recuperationInkWhPerkmAltitudeLoss.

Minimum value: 0.0
Maximum value: 1/accelerationEfficiency

Specifies the efficiency of converting electric energy to potential energy when the vehicle gains elevation (i.e., PotentialEnergyGained/ElectricEnergyConsumed). Notes:

• It must be paired with downhillEfficiency.

• It cannot be used with consumptionInkWhPerkmAltitudeGain or recuperationInkWhPerkmAltitudeLoss.

Minimum value: 0.0
Maximum value: 1/downhillEfficiency

Specifies the efficiency of converting potential energy to electric energy when the vehicle loses elevation (i.e, ElectricEnergyGained/PotentialEnergyLost). Notes:

• It must be paired with uphillEfficiency.

• It cannot be used with consumptionInkWhPerkmAltitudeGain or recuperationInkWhPerkmAltitudeLoss.

Minimum value: 0.0
Maximum value: 1/uphillEfficiency

Specifies the electric energy in kWh consumed by the vehicle through gaining 1000 meters of elevation. Notes:

• It must be paired with recuperationInkWhPerkmAltitudeLoss.

• It cannot be used with accelerationEfficiency, decelerationEfficiency, uphillEfficiency or downhillEfficiency.

Minimum value: recuperationInkWhPerkmAltitudeLoss
Maximum value: 500.0

Specifies the electric energy in kWh gained by the vehicle through losing 1000 meters of elevation. Notes:

• It must be paired with consumptionInkWhPerkmAltitudeGain.

• It cannot be used with accelerationEfficiency, decelerationEfficiency, uphillEfficiency or downhillEfficiency.

Minimum value: 0.0
Maximum value: consumptionInkWhPerkmAltitudeGain

The service whitelists response headers that browsers are allowed to access. Value: Content-Length

The service allows cross-origin resource sharing. Value: * (wildcard)

The service supports HTTP compression, if requested by the client. Value: gzip

The format of the response. The service supports specifying the desired response format. See the contentType parameter. Values:

• application/json; charset=utf-8
• application/javascript; charset=utf-8

The Cache-Control general-header field is used to specify directives that must be obeyed by all caching mechanisms along the request/response chain. It is supported by HTTP/1.1 clients. It may not be supported by HTTP/1.0 clients. Values:

• no-cache
• no-transform

The Pragma general-header field is used to specify directives that might apply to any recipient along the request/response chain. It is supported by HTTP/1.0 client. Value: no-cache

This is an identifier for the request. If Tracking-ID was specified in the request headers, it contains the same value. Otherwise it may contain a generated value.

This may be sent for deprecated features.

OK: A route or range was calculated and the body of the response contains the data for a successful response.

Bad request:

• One or more parameters were incorrectly specified.
• Some parameters are mutually exclusive.

• The points in the route request are not connected by the road network.

• The points in the request are not near enough to a road.

• A reachable range consistent with the given parameters could not be found.

Permission or authentication issues:

• Forbidden
• Not authorized
• Account inactive

Not Found: The requested resource could not be found, but it may be available again in the future.

Method Not Allowed: The client used a HTTP method other than GET or POST.

Request timeout: The client took too long to transmit the request.

Requested uri is too long.

Unsupported Media Type.

Too Many Requests: Too many requests were sent in a given amount of time for the supplied API Key.

An error occurred while processing the request. Please try again later. This can also indicate that the request reached an internal computation time threshold and timed out.

Internal network connectivity issue.

Service currently unavailable.

Internal network connectivity issue.

Service not found.

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.

• 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 field and may contain the points, encodedPolyline, and encodedPolylinePrecision 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. points and encodedPolyline are alternative representation formats. See the Route geometry representation formats section for further information.

A string in the encoded polyline format representing the array of points describing a part of a route. The precision used to encode the polyline is set in the encodedPolylinePrecision field. The precision reflects the selected coordinatePrecision, i.e., the precision is 5 with default, and 7 with full. points and encodedPolyline are alternative representation formats. See the Route geometry representation formats section for further information.

The precision used to encode the polyline in the encodedPolyline field.

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

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 magnitudeOfDelay

Details of the traffic event. It uses the definitions in the TPEG2-TEC standard. It can contain the effectCode and causes fields. A selection of TPEG2-TEC causes can be found in the Terms and definitions of Safety related message sets.

The effect on the traffic flow. Contains a value in the tec001:EffectCode table, as defined in the TPEG2-TEC 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 TPEG2-TEC standard. A selection of TPEG2-TEC causes can be found in the Terms and definitions of Safety related message sets.

The sub-cause of the traffic event. Contains a value in the sub cause table defined by the mainCauseCode, as defined in the TPEG2-TEC standard. A selection of TPEG2-TEC causes can be found in the Terms and definitions of Safety related message sets.

The estimated travel time in seconds.

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 calculateLongDistanceEVRoute 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 calculateLongDistanceEVRoute 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 calculateLongDistanceEVRoute 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 electric energy consumption in kilowatt hours (kWh) using the Electric Consumption Model.

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

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.

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 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 than the reference route, according to the given planning criteria (set by routeType).

• Out_Of_Range in case any stop of the reference route is unreachable.

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.

This field is included if extendedRouteRepresentation is used.

• It always contains entries for the first and the last point in the route.

• For any pair of consecutive entries in the progress array, progress for pointIndex values that are not explicitly present and are enclosed by said pair, can be linearly interpolated by summing up straight line distances of the leg points.

• The Haversine formula is precise enough to compute such distances.

A progress point object may contain the following members:

• pointIndex: index of the point (offset 0) in the route this object applies to.

• distanceInMeters: distance (in meters) from the start of the route to this point. This field is included if the extendedRouteRepresentation value distance is used.

• travelTimeInSeconds: travel time (in seconds) from the start of the route to this point. This field is included if the extendedRouteRepresentation value travelTime is used.

• batteryConsumptionInkWh: electric energy consumption (in kilowatt hours) from the start of the route to this point. This field is included if the extendedRouteRepresentation value consumption is used. See also the batteryConsumptionInkWh in summary section.

The index of the waypoint at the end of the leg that corresponds to:

• The index of this waypoint in the list of waypoints from the routePlanningLocations base path parameter in the request (the first waypoint has an index equal to 0).

• The index of this waypoint in the pointWaypoints field when reconstructing a route.

This field is not provided if the end of the leg corresponds to the destination or to a new charging waypoint that is not present in the request.

Contains the value of pauseTimeInSeconds, if it was specified for the corresponding leg. This field is not present in the route summary field.

Identifies the entry point that was used for the route at the end of the leg. This index corresponds to the position of this entry point in the list of entry points within the respective leg. The first entry point has an index equal to 0. This field is only present if the leg had entryPoints in the request.

The base URL of the Road Shields service to fetch the road shield atlas and metadata resources. Currently available resources are:

• sprite.png
• sprite.json

We recommend to cache the sprite atlas (sprite.png) and metadata (sprite.json) as it changes infrequently and is large compared to a typical road shield description. Please refer to the Road Shield service for further information. The returned road shield references correspond to the asset names in the Road Shield service.

The speed in km/h for the hands-free section.

The integer value of importance. The index starts from 0, and a lower value means higher importance. The index is needed for two reasons:

1. To understand which stretch is the most important (for example, if it is necessary to display a smaller number of stretches).
2. To group different sections that belong to the same stretch (since there may be gaps in one stretch for various reasons).

An object contains a text field with the name of a street.

An array of objects of type RoadNumber. All items are sorted in descending order of display priority. The RoadNumber object contains a text field with the road number.

A summary of a route or a route leg. The summary object may be extended with new fields in the future; clients should ignore fields they do not recognize. It contains the following:

• lengthInMeters
• travelTimeInSeconds
• trafficDelayInSeconds
• trafficLengthInMeters
• departureTime
• arrivalTime
• noTrafficTravelTimeInSeconds
• historicTrafficTravelTimeInSeconds
• liveTrafficIncidentsTravelTimeInSeconds
• batteryConsumptionInkWh
• deviationDistance
• deviationTime
• deviationPoint
• reachableRouteOffsets
• remainingChargeAtArrivalInkWh

• chargingInformationAtEndOfLeg, if it is a leg summary and the leg ends at a charging stop.

• totalChargingTimeInSeconds, if it is a route summary.

The estimated battery charge in kWh upon arrival at the end of the leg or the route.

The chargingInformationAtEndOfLeg object is contained in the leg summary if and only if the leg ends at a charging stop. It contains:

• targetChargeInkWh
• chargingTimeInSeconds
• chargingConnections
• chargingParkUuid

In addition, it may contain any of the following:

• chargingConnectionInfo
• chargingParkLocation
• chargingParkName
• chargingParkOperatorName
• chargingParkPowerInkW
• chargingStopType
• chargingParkPaymentOptions

The estimated time in seconds spent at the charging stop, allowing for some additional time needed to use the charging facility.

A list of chargingConnections, one of which should be used at this charging stop.

The chargingParkLocation object describes location details of this charging park. It may contain any of the following:

• coordinate
• street
• houseNumber
• city
• region
• postalCode
• countryCode

The country code of the charging park in the ISO 3166-1 alpha-2 format.

The chargingConnectionInfo object describes details of the charging connection which should be used at this charging stop. Its contents may differ if the request contains chargingModes or chargingParameters.
For requests having chargingModes:
It contains:

• chargingPlugType

In addition, it may contain any of the following:

• chargingVoltageInV
• chargingCurrentInA
• chargingCurrentType
• chargingPowerInkW

For requests having chargingParameters:
It contains:

• chargingPlugType
• chargingCurrentType
• chargingPowerInkW

In addition, it may contain any of the following:

• chargingVoltageInV
• chargingCurrentInA
• plugAndChargeSupport

An element of the currentType codes table.

Indicates if the selected charging connector supports Plug-and-Charge. Possible values are:

• SUPPORTED
• UNSUPPORTED

The element of the plugType codes table used for the charging process.

Indicates if the selected charging connector supports Plug-and-Charge. Possible values are:

• SUPPORTED
• UNSUPPORTED

A list of one or more chargingParkPaymentOption elements.

The chargingParkPaymentOption object describes payment options. It contains:

• method
• brands

An element of the paymentMethod codes table.

A list of brands that is associated with this charging park. This element is not included if there are no associated brands.

The source of the charging stop at the end of this leg.
Values:

• Auto_Generated for automatically added charging stops.

• User_Defined for user-specified waypoints. If a waypoint also includes charging data then it is considered as a user-chosen charging station and the most optimal charging times are chosen for all the charging stops in order to get the fastest possible route. This may result in some manually added charging waypoints to have zero charging time, i.e., charge at departure = charge at arrival.

The unique identifier of this charging park. This UUID can be used to check the availability of the charging park.

The estimated time spent at all charging stops in the route. The travelTimeInSeconds of the route includes the totalChargingTimeInSeconds value.

Contains one facilityType and one plugType which are compatible with the vehicle.

An element of the facilityType codes table.

A unique string id for search purposes.

An element of the plugType codes table.

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.

• When requested using includeTollPaymentTypes, a TOLL section optionally contains tollPaymentTypes.

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

• ROAD_SHIELDS sections contain an array of roadShieldReference objects. Please refer to the structure of a road shield reference object for further information.

• A HANDS_FREE_DRIVING section additionally contains the field: handsFreeDrivingSpeedInKmh. Note: If handsFreeDriving sections are requested, then handsFreeDrivingCapability must also be set.

• An IMPORTANT_ROAD_STRETCH section additionally contains the importantRoadStretchIndex field, and contains streetName or roadNumbers fields (or both).

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.

The tollPaymentTypes array appears in toll sections if includeTollPaymentTypes=all. Each element of tollPaymentTypes represents a toll payment type. This field can only be used within sections of type TOLL.
Possible toll payment types are:

• CASH_COINS_AND_BILLS: Cash can be used including coins and bills.

• CASH_BILLS_ONLY: Cash can be used, but bills only, e.g., 10 euros.

• CASH_COINS_ONLY: Cash can be used, but coins only, e.g., 20 cents.

• CASH_EXACT_CHANGE: Cash is used but the exact amount must be provided.

• CREDIT_CARD: Credit cards are accepted.

• DEBIT_CARD: Bank/debit cards are accepted.

• TRAVEL_CARD: Travel cards are accepted.

• ETC: Electronic toll collect either via camera or transponder.

• ETC_TRANSPONDER: Electronic toll collect via transponder.

• ETC_VIDEO_CAMERA: Electronic toll collect via camera.

• SUBSCRIPTION: Toll collect based on subscription.

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

This object describes a single road shield reference. It contains the following fields: