Maps SDK for Web
Class Routing
It allows to calculate a route between two locations using the TomTom's Routing API - Calculate Route;
Parameters can be passed to the constructor or provided via convenient methods that can be chained until the method go performs the actual call.
The call is asynchronous therefore the user has two options to receive the response:
- Passing a callback function.
- Use the Promise returned by the go method to handle the response.
The SDK provides a Promise polyfill for browsers (IE<9) without native ECMAScript 6 support.
The types used in routing service
-
point - latitude, longitude pair (in EPSG4326 projection), with the following constraints:
- Latitude values must be in the range -90..+90 inclusive.
- Longitude values must be in the range -180..+180 inclusive.
- Example: 52.37245,4.89406
-
circle - A circle with a center point and a radius (in meters).
- The radius must be a positive integer with the maximum value of 20050000.
- Note that larger integer values will not be rejected but lowered to the maximum value.
- Example: circle(52.37245,4.89406,10000)
-
location - A point or a circle.
- Example: 52.37245,4.89406 circle(52.37245,4.89406,10000)
-
dateTime - A date and time specified in RFC-3339 format with an optional time zone offset.
- Example: 1996-12-19T16:39:57 1996-12-19T16:39:57-08:00
Constructor
Routing([options])
Parameters
Name | Description | Required | Type/Values | Default |
---|---|---|---|---|
options | Options to be passed to the routing call, or Array of such options objects to perform batch request. | No | Object | None |
options.key | The API key to be used. | No | String | global API key |
options.callback | Callback function to use in case of success | No | Function | None |
options.fail | Callback function to use in case of failure | No | Function | default |
options.accelerationEfficiency | Specifies the efficiency of converting chemical energy stored in fuel to kinetic energy when the vehicle accelerates (i.e. KineticEnergyGained/ChemicalEnergyConsumed). | No | Number | None |
options.allowVignette | List of 3-character ISO 3166-1 alpha-3 country codes of countries in which toll roads with vignettes are allowed. | No | Array | None |
options.alternativeType | Specifies the alternative type of the calculated alternatives compared to the reference route. | No | String | None |
options.arriveAt | The date and time of arrival at the destination point | No | String | None |
options.auxiliaryPowerInkW | Specifies the amount of power consumed for sustaining auxiliary systems, in kilowatts (kW). | No | Number | None |
options.auxiliaryPowerInLitersPerHour | Specifies the amount of fuel consumed for sustaining auxiliary systems of the vehicle, in liters per hour. It can be used to specify consumption due to devices and systems such as AC systems, radio, heating, etc. | No | Number | None |
options.avoid | Specifies something that the route calculation should try to avoid when determining the route. | No | String | None |
options.avoidAreas | A list of shapes to avoid for planning routes. See more | No | Array | None |
options.avoidVignette | List of 3-character ISO 3166-1 alpha-3 country codes of countries in which all toll roads with vignettes are to be avoided. | No | Array | None |
options.computeBestOrder | Re-order the route waypoints to reduce the route length | No | Boolean | None |
options.computeTravelTimeFor | Setting this to all provides additional information regards travel times. | No | String | None |
options.constantSpeedConsumptionInLitersPerHundredkm | Colon-delimited list of CombustionConstantSpeedConsumptionPairs, e.g. array of such pairs "60,7". | No | Array | None |
options.constantSpeedConsumptionInkWhPerHundredkm | Colon-delimited list of ElectricConstantSpeedConsumptionPairs, e.g. array of such pairs "60,7". | No | Array | None |
options.currentChargeInkWh | Specifies the current electric energy supply in kilowatt hours (kWh). | No | Number | None |
options.currentFuelInLiters | Current supply of fuel in liters. | No | Number | None |
options.decelerationEfficiency | Specifies the efficiency of converting kinetic energy to saved (not consumed) fuel when the vehicle decelerates (i.e. ChemicalEnergySaved/KineticEnergyLost). | No | Number | None |
options.departAt | The date and time of departure from the origin point | No | String | None |
options.downhillEfficiency | Specifies the efficiency of converting potential energy to saved (not consumed) fuel when the vehicle loses elevation (i.e. ChemicalEnergySaved/PotentialEnergyLost). | No | Number | None |
options.fuelEnergyDensityInMJoulesPerLiter | Specifies the amount of chemical energy stored in one liter of fuel in megajoules (MJ). It is used in conjunction with the Efficiency parameters for conversions between saved or consumed energy and fuel. | No | Number | None |
options.hilliness | Degree of hilliness for thrilling route | No | String | None |
options.instructionsType | If specified, guidance instructions will be returned (if available) | No | String | None |
options.language | The language parameter determines the language of the guidance messages | No | String | None |
options.locations | Locations through which the route is calculated | No | String | Array | None |
options.maxAlternatives | Number of desired alternative routes to be calculated | No | Number | None |
options.maxChargeInkWh | Specifies the maximum electric energy supply in kilowatt hours (kWh) that may be stored in the vehicle's battery. | No | Number | None |
options.minDeviationDistance | At least how far in meters the alternative routes have to follow the reference route | No | Number | 0 |
options.minDeviationTime | At least how far in time (seconds) the alternative routes have to follow the reference route | No | Number | 0 |
options.protocol | Protocol's type, one of "http" or "https". | No | String | None |
options.report | Specifies which data should be reported for diagnosis purposes. Possible values:
|
No | String | None |
options.routeRepresentation | Specifies the representation of the set of routes provided as response | No | String | None |
options.routeType | The type of route requested. | No | String | None |
options.sectionType | Specifies which section types are reported in the route response. See more | No | String[] | "travelMode" |
options.supportingPoints | Array of supporting points used for constructing the route. See more | No | Array | None |
options.traffic | Determines if traffic data should be used to calculate the route | No | Boolean | None |
options.travelMode | The travel mode for the requested route | No | String | None |
options.uphillEfficiency | Specifies the efficiency of converting chemical energy stored in fuel to potential energy when the vehicle gains elevation (i.e. PotentialEnergyGained/ChemicalEnergyConsumed). | No | Number | None |
options.vehicleAxleWeight | The vehicle axle weight in kg. | No | Number | None |
options.vehicleCommercial | True if vehicle is used for commercial purposes. | No | Boolean | None |
options.vehicleEngineType | The vehicle engine type. | No | String | None |
options.vehicleHeight | The vehicle height in m. | No | Number | None |
options.vehicleLength | The vehicle length in meters. | No | Number | None |
options.vehicleLoadType | The array of truck cargo classification. | No | Array | String | None |
options.vehicleMaxSpeed | The maximal allowed vehicle speed in km/h. | No | Number | None |
options.vehicleWeight | The vehicle weight in kg. | No | Number | None |
options.vehicleWidth | The vehicle width in m. | No | Number | None |
options.windingness | Level of turns for thrilling route. | No | String | None |
Example
tomtom.routing()
.locations('52.3,4.8:52.37,4.87')
.go()
.then(function(routeGeoJson) {
console.log(routeGeoJson);
});
Methods
accelerationEfficiency([accelerationEfficiency]): Number Chainable
A setter and getter for 'accelerationEfficiency' attribute.
Specifies the efficiency of converting chemical energy stored in fuel to kinetic energy when the vehicle accelerates (i.e. KineticEnergyGained/ChemicalEnergyConsumed). ChemicalEnergyConsumed is obtained by converting consumed fuel to chemical energy using fuelEnergyDensityInMJoulesPerLiter.
Parameters
Name | Description | Required | Type/Values | Default |
---|---|---|---|---|
accelerationEfficiency | No | Number | None |
Throws
if the given argument cannot be converted to a valid value
Returns
Method returns the service instance allowing chaining or current value if argument is omitted.
allowVignette([newValue]): String | String[] Chainable
A getter and setter for the 'allowVignette' attribute.
List of 3-character ISO 3166-1 alpha-3 country codes of countries in which toll roads with vignettes are allowed. Specifying allowVignette with some countries X is equivalent to specifying avoidVignette with all countries but X. Specifying allowVignette with an empty list is the same as avoiding all toll roads with vignettes. It is an error to specify both avoidVignette and allowVignette.
Parameters
Throws
If the given argument cannot be converted into a valid value
Returns
The same service instance or the current option value if no argument was given
alternativeType([alternativeType]): String Chainable
A setter and getter for 'alternativeType' attribute.
Specifies the alternative type of the calculated alternatives compared to the reference route. Possible values are:
- anyRoute: allow any alternative route to be returned regardless of how it compares to the reference route in terms of optimality.
- betterRoute: returns an alternative route only if it is better than the reference route according to the given planning criteria.
Can only be used when reconstructing a route.
Parameters
Name | Description | Required | Type/Values | Default |
---|---|---|---|---|
alternativeType | anyRoute or betterRoute value. | No | String | None |
Throws
if the given argument is not one of the accepted values described above
Returns
Method returns the service instance allowing chaining or current value if argument is omitted.
arriveAt([arriveAt]): String Chainable
A setter and getter for 'arriveAt' attribute.
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 will be assumed to be that of the destination point. The arriveAt value must be in the future. The arriveAt parameter cannot be used in conjunction with departAt.
Parameters
Name | Description | Required | Type/Values | Default |
---|---|---|---|---|
arriveAt | The properly formatted date with time value. Date cannot be in the past. | No | String | None |
Throws
if the given argument cannot be converted to a valid value
Returns
Method returns the service instance allowing chaining or language if argument is omitted.
auxiliaryPowerInkW([auxiliaryPowerInkW]): Number Chainable
A setter and getter for 'auxiliaryPowerInkW' attribute.
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.
Parameters
Name | Description | Required | Type/Values | Default |
---|---|---|---|---|
auxiliaryPowerInkW | No | Number | None |
Throws
if the given argument cannot be converted to a valid value
Returns
Method returns the service instance allowing chaining or current value if argument is omitted.
auxiliaryPowerInLitersPerHour([auxiliaryPowerInLitersPerHour]): Number Chainable
A setter and getter for 'auxiliaryPowerInLitersPerHour' attribute.
Specifies the amount of fuel consumed for sustaining auxiliary systems of the vehicle, in liters per hour. It can be used to specify consumption due to devices and systems such as AC systems, radio, heating, etc.
Parameters
Name | Description | Required | Type/Values | Default |
---|---|---|---|---|
auxiliaryPowerInLitersPerHour | No | Number | None |
Throws
if the given argument cannot be converted to a valid value
Returns
Method returns the service instance allowing chaining or current value if argument is omitted.
avoid([avoid]): Array Chainable
A setter and getter for 'avoid' attribute.
Specifies something that the route calculation should try to avoid when determining the route. Can be specified multiple times. Possible values:
- tollRoads: avoids toll roads.
- motorways: avoids motorways.
- ferries: avoids ferries.
- unpavedRoads: avoids unpaved roads.
- carpools: avoids routes that require use of carpool (HOV/ High Occupancy Vehicle) lanes.
- alreadyUsedRoads: avoids using the same road multiple times.
Most useful in conjunction with routeType=thrilling.
Parameters
Throws
if the given argument cannot be converted to a valid value
Returns
Method returns the service instance allowing chaining or street number value if argument is omitted.
avoidAreas([areas]): String Chainable
A getter and setter for the 'avoidAreas' attribute.
A list of shapes to avoid for planning routes. Supported shapes include rectangles. Can contain one of each supported shapes element.
Parameters
Name | Description | Required | Type/Values | Default |
---|---|---|---|---|
areas | A list of shapes to avoid for planning routes. | No | Object[] | None |
Throws
if the given argument cannot be converted to a valid value
Returns
Method returns the service instance allowing chaining or converted locations value if argument is omitted.
Example
tomtom.routing().locations('52.37173,4.91015:52.36357,4.898046255')
.avoidAreas([{
southWestCorner: {latitude: 52.36391, longitude:4.90106},
northEastCorner: {latitude: 52.36554, longitude:4.90767}
}]);
Supported point formats:
- 'lat,lon'
- {lat:111, lon:111}
- {lat:111, lng:111}
- {latitude:111, longitude:111}
- {x:111, y:111}
- {lat: function(), lng:function()}
avoidVignette([newValue]): String | String[] Chainable
A getter and setter for the 'avoidVignette' attribute.
List of 3-character ISO 3166-1 alpha-3 country codes of countries in which all toll roads with vignettes are to be avoided. Toll roads with vignettes in countries not in the list are unaffected. It is an error to specify both avoidVignette and allowVignette.
Parameters
Throws
If the given argument cannot be converted into a valid value
Returns
The same service instance or the current option value if no argument was given
callback([newValue]): Function Chainable
Sets or gets the value of the option callback
.
This callback function will be called only after the go method successfully complete its task.
Its first and unique argument passed to the callback will be the result of the request.
Parameters
Name | Description | Required | Type/Values | Default |
---|---|---|---|---|
newValue | The new callback function | No | Function | None |
Throws
If the given argument is not a function
Returns
The same service instance or the current callback function if no argument was given
Example
function callbackFn(results) {
console.log(results);
}
tomtom.fuzzySearch()
.query("pizza")
.callback(callbackFn)
.go();
computeBestOrder([computeBestOrder]): Boolean Chainable
A setter and getter for 'computeBestOrder' attribute.
Allows to reorder the route waypoints to reduce the route length. Yields best results when used in conjunction with routeType shortest. Possible values:
- true (compute a better order, if possible; not allowed to be used in conjunction with maxAlternatives value greater than 0; not allowed to be used in conjunction with circle waypoints). The response will include the optimized waypoint indices. This feature can be used with a maximum of 20 route waypoints.
- false (use the locations in the given order). Not allowed to be used in conjunction with routeRepresentation none.
Parameters
Name | Description | Required | Type/Values | Default |
---|---|---|---|---|
computeBestOrder | Flag to reorder the route waypoints to reduce the route length | No | Boolean | None |
Throws
if the given argument cannot be converted to a valid value
Returns
Method returns the service instance allowing chaining or language if argument is omitted.
computeTravelTimeFor([computeTravelTimeFor]): String Chainable
A setter and getter for 'computeTravelTimeFor' attribute.
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:
- 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 and liveTrafficIncidentsTravelTimeInSeconds being included in the summaries in the route response.
Parameters
Name | Description | Required | Type/Values | Default |
---|---|---|---|---|
computeTravelTimeFor | Setting to all provides additional information regards travel times. | No | String | None |
Throws
if the given argument cannot be converted to a valid value
Returns
Method returns the service instance allowing chaining or current value if argument is omitted.
constantSpeedConsumptionInkWhPerHundredkm([constantSpeedConsumptionInkWhPerHundredkm]): Array Chainable
A setter and getter for 'constantSpeedConsumptionInkWhPerHundredkm' attribute.
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).
Parameters
Name | Description | Required | Type/Values | Default |
---|---|---|---|---|
constantSpeedConsumptionInkWhPerHundredkm | Colon-delimited list of ElectricConstantSpeedConsumptionPairs, e.g. array of such pairs "60,7". | No | Array | None |
Throws
if the given argument cannot be converted to a valid value
Returns
Method returns the service instance allowing chaining or current value if argument is omitted.
constantSpeedConsumptionInLitersPerHundredkm([constantSpeedConsumptionInLitersPerHundredkm]): Array Chainable
A setter and getter for 'constantSpeedConsumptionInLitersPerHundredkm' attribute.
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 l/100km).
Parameters
Name | Description | Required | Type/Values | Default |
---|---|---|---|---|
constantSpeedConsumptionInLitersPerHundredkm | Colon-delimited list of CombustionConstantSpeedConsumptionPairs, e.g. array of such pairs "60,7". | No | Array | None |
Throws
if the given argument cannot be converted to a valid value
Returns
Method returns the service instance allowing chaining or current value if argument is omitted.
currentChargeInkWh([currentChargeInkWh]): Number Chainable
A setter and getter for 'currentChargeInkWh' attribute.
Specifies the current electric energy supply in kilowatt hours (kWh).
Parameters
Name | Description | Required | Type/Values | Default |
---|---|---|---|---|
currentChargeInkWh | No | Number | None |
Throws
if the given argument cannot be converted to a valid value
Returns
Method returns the service instance allowing chaining or current value if argument is omitted.
currentFuelInLiters([currentFuelInLiters]): Number Chainable
A setter and getter for 'currentFuelInLiters' attribute.
Specifies the current supply of fuel in liters.
Parameters
Name | Description | Required | Type/Values | Default |
---|---|---|---|---|
currentFuelInLiters | No | Number | None |
Returns
Method returns the service instance allowing chaining or current value if argument is omitted.
decelerationEfficiency([decelerationEfficiency]): Number Chainable
A setter and getter for 'decelerationEfficiency' attribute.
Specifies the efficiency of converting kinetic energy to saved (not consumed) fuel when the vehicle decelerates (i.e. ChemicalEnergySaved/KineticEnergyLost). ChemicalEnergySaved is obtained by converting saved (not consumed) fuel to energy using fuelEnergyDensityInMJoulesPerLiter.
Parameters
Name | Description | Required | Type/Values | Default |
---|---|---|---|---|
decelerationEfficiency | No | Number | None |
Throws
if the given argument cannot be converted to a valid value
Returns
Method returns the service instance allowing chaining or current value if argument is omitted.
departAt([departAt]): String Chainable
A setter and getter for 'departAt' attribute.
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 will be assumed to be that of the origin point. The departAt value must be in the future. The departAt parameter cannot be used in conjunction with arriveAt.
Parameters
Name | Description | Required | Type/Values | Default |
---|---|---|---|---|
departAt | The properly formatted date with time or 'now' value. Date cannot be in the past. | No | String | None |
Throws
if the given argument cannot be converted to a valid value
Returns
Method returns the service instance allowing chaining or language if argument is omitted.
downhillEfficiency([downhillEfficiency]): Number Chainable
A setter and getter for 'downhillEfficiency' attribute.
Specifies the efficiency of converting potential energy to saved (not consumed) fuel when the vehicle loses elevation (i.e. ChemicalEnergySaved/PotentialEnergyLost). ChemicalEnergySaved is obtained by converting saved (not consumed) fuel to energy using fuelEnergyDensityInMJoulesPerLiter.
Parameters
Name | Description | Required | Type/Values | Default |
---|---|---|---|---|
downhillEfficiency | No | Number | None |
Throws
if the given argument cannot be converted to a valid value
Returns
Method returns the service instance allowing chaining or current value if argument is omitted.
energyBudgetInkWh(energyBudgetInkWh): String Chainable
Getter and setter for energyBudgetInkWh.
Parameters
Name | Description | Required | Type/Values | Default |
---|---|---|---|---|
energyBudgetInkWh | Electric energy budget in kilowatt hours (kWh) that determines maximal range which can be travelled using the specified Electric Consumption Model. | Yes | Number | None |
Throws
if the given argument cannot be converted to a valid value
Returns
Method returns the service instance allowing chaining or current value if argument is omitted.
fail([newValue]): Function Chainable
Sets or gets the value of the option fail
.
This function is called when an error occurs (e.g. invalid values or a communication error).
The callback will receive just one argument which is the error description.
This parameter will be ignored if the callback function is not defined and therefore the
go method will return a Promise that will be rejected if an error occurs.
If you don't specificy a failure callback, the default behavior in case of encounter a problem is to
throw an error.
Parameters
Name | Description | Required | Type/Values | Default |
---|---|---|---|---|
newValue | The new callback function | No | Function | None |
Throws
If the given argument is not a function
Returns
The same service instance or the current callback function if no argument was given
Example
function successCallback(results) {
console.log(results);
}
function failureCallback(error) {
console.log(error);
}
tomtom.fuzzySearch()
.query("pizza")
.callback(successCallback)
.fail(failureCallback)
.go();
fuelBudgetInLiters(fuelBudgetInLiters): String Chainable
Getter and setter for fuelBudgetInLiters.
Parameters
Name | Description | Required | Type/Values | Default |
---|---|---|---|---|
fuelBudgetInLiters | Fuel budget in liters that determines maximal range which can be travelled using the specified Combustion Consumption Model. Required if vehicleEngineType is combustion. | Yes | Number | None |
Throws
if the given argument cannot be converted to a valid value
Returns
Method returns the service instance allowing chaining or current value if argument is omitted.
fuelEnergyDensityInMJoulesPerLiter([fuelEnergyDensityInMJoulesPerLiter]): Number Chainable
A setter and getter for 'fuelEnergyDensityInMJoulesPerLiter' attribute.
Specifies the amount of chemical energy stored in one liter of fuel in megajoules (MJ). It is used in conjunction with the *Efficiency parameters for conversions between saved or consumed energy and fuel. For example, energy density is 34.2 MJ/l for gasoline, and 35.8 MJ/l for Diesel fuel.
Parameters
Name | Description | Required | Type/Values | Default |
---|---|---|---|---|
fuelEnergyDensityInMJoulesPerLiter | No | Number | None |
Throws
if the given argument cannot be converted to a valid value
Returns
Method returns the service instance allowing chaining or current value if argument is omitted.
go([success], [fail]): Promise | Null
Executes a predefined asynchronous task using the current configuration and then execute one of the callback functions based on the success of the result. It receives two optional arguments. The first one is a callback function that will be used when the task is successfully completed. The second one is another callback function that will be used only in case of failure. Both arguments are shortcuts for the callback and fail methods respectively.
Parameters
Name | Description | Required | Type/Values | Default |
---|---|---|---|---|
success | The callback function to be called on case of success | No | Function | None |
fail | The callback function to be called on case of failure. If a success callback was not given this argument will be ignored. In that case the returned Promise should be used to handle the failures. | No | Function | None |
Returns
If the success callback is omitted (and wasn't defined one yet) this function will return a Promise
Example
All the ways of using this method:
// Defining callbacks as function arguments
tomtom.fuzzySearch()
.query("pizza")
.go(successCallback, failureCallback);
// Defining callbacks using setters methods
tomtom.fuzzySearch()
.query("pizza")
.callback(successCallback)
.fail(failureCallback)
.go();
// Using the returned Promise
tomtom.fuzzySearch()
.query("pizza")
.go()
.then(successCallback)
.catch(failureCallback);
The SDK provides a Promise polyfill for browsers (IE<9) without native ECMAScript 6 support.
hilliness([hilliness]): String Chainable
A setter and getter for 'hilliness' attribute.
Degree of hilliness for thrilling route. Possible values: low, normal, high This parameter can only be used in conjunction with routeType thrilling.
Parameters
Name | Description | Required | Type/Values | Default |
---|---|---|---|---|
hilliness | The level of hilliness on a thrilling route. | No | String | None |
Throws
if the given argument cannot be converted to a valid value
Returns
Method returns the service instance allowing chaining or language if argument is omitted.
instructionsType([instructionsType]): String Chainable
A setter and getter for 'instructionsType' attribute.
If specified, guidance instructions will be returned (if available).
Possible values:
- 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 that the instructionsType parameter cannot be used in conjunction with routeRepresentation=none. If alternative routes are requested, instructions will be generated for each route returned.
Parameters
Name | Description | Required | Type/Values | Default |
---|---|---|---|---|
instructionsType | If a street number is sent in along with the request, the response may include the side of the street (Left/Right) and also an offset position for that street number. | No | String | None |
Throws
if the given argument cannot be converted to a valid value
Returns
Method returns the service instance allowing chaining or street number value if argument is omitted.
language([language]): String Chainable
A setter and getter for 'language' attribute.
The language parameter determines the language of the guidance messages. It does not affect proper nouns (the names of streets, plazas, etc.) It has no effect when instructionsType=coded. Allowed values are (a subset of) the IETF language tags described here. The currently supported languages are listed in the supported languages section:
Parameters
Name | Description | Required | Type/Values | Default |
---|---|---|---|---|
language | The language value | No | String | None |
Throws
if the given argument cannot be converted to a valid value
Returns
Method returns the service instance allowing chaining or language if argument is omitted.
locations([locations]): String Chainable
A setter and getter for 'locations' attribute.
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 of type point.
- The last location in the sequence defines the destination and must be of type point.
- One or more optional intermediate locations (known as waypoints) may be provided:
- The maximum allowed number of waypoints is 50, reduced to 20 when computeBestOrder is true.
- A point waypoint results in an extra leg in the response, a circle waypoint does not.
- Circle waypoints cannot be used when computeBestOrder is true.
The points or circles that will be used to calculate the route. Following input types are allowed:
- string with Colon-delimited locations. For example: '52.50931,13.42936:52.50274,13.43872'.
- array containing locations location can be defined as string,object or array
Parameters
Throws
if the given argument cannot be converted to a valid value
Returns
Method returns the service instance allowing chaining or converted locations value if argument is omitted.
maxAlternatives([maxAlternatives]): Number Chainable
A setter and getter for 'maxAlternatives' attribute.
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 Default value is 0, Maximum value is 5
Parameters
Name | Description | Required | Type/Values | Default |
---|---|---|---|---|
maxAlternatives | To restrict maximum alternative routes to be calculated. | No | Number | None |
Throws
if the given argument cannot be converted to a valid value
Returns
Method returns the service instance allowing chaining or maxAlternatives value if argument is omitted.
maxChargeInkWh([maxChargeInkWh]): Number Chainable
A setter and getter for 'maxChargeInkWh' attribute.
Specifies the maximum electric energy supply in kilowatt hours (kWh) that may be stored in t he vehicle's battery.
Parameters
Name | Description | Required | Type/Values | Default |
---|---|---|---|---|
maxChargeInkWh | No | Number | None |
Throws
if the given argument cannot be converted to a valid value
Returns
Method returns the service instance allowing chaining or current value if argument is omitted.
minDeviationDistance([newValue]): Number Chainable
Sets or gets the value of the minDeviationDistance option.
Defines at least how far in meters the alternative routes have to follow the reference route.
This option cannot be used in conjunction with arriveAt.
Parameters
Name | Description | Required | Type/Values | Default |
---|---|---|---|---|
newValue | Meters represented as a positive integer number | No | Number | None |
Throws
If the given argument cannot be converted into a valid value
Returns
The same service instance or the current option value if no argument was given
minDeviationTime([newValue]): Number Chainable
Sets or gets the value of the minDeviationTime option.
Defines at least how far in time (seconds) the alternative routes have to follow reference route.
This option cannot be used in conjunction with arriveAt.
Parameters
Name | Description | Required | Type/Values | Default |
---|---|---|---|---|
newValue | Seconds represented as a positive integer number | No | Number | None |
Throws
If the given argument cannot be converted into a valid value
Returns
The same service instance or the current option value if no argument was given
origin(origin): ReachableRange | String Chainable
Point from which the range calculation should start.
Parameters
Name | Description | Required | Type/Values | Default |
---|---|---|---|---|
origin | Point from which the range calculation should start. | Yes | String | None |
Throws
if the given argument cannot be converted to a valid value
Returns
Method returns the service instance allowing chaining or current value if argument is omitted.
protocol([protocol]): String Chainable
A setter and getter for 'protocol' attribute.
Represents type of protocol used to perform service call.
Parameters
Name | Description | Required | Type/Values | Default |
---|---|---|---|---|
protocol | Protocol type, one of http or https. | No | String | None |
Throws
If the given argument cannot be converted to a valid value.
Returns
Method returns the service instance allowing chaining or <em>protocol</em> value if argument is omitted.
report([report]): String Chainable
A setter and getter for 'report' attribute.
Specifies which data should be reported for diagnosis purposes.
Possible values: 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.
Parameters
Name | Description | Required | Type/Values | Default |
---|---|---|---|---|
report | Level of verbose answer from service, useful for debugging purposes. | No | String | None |
Throws
if the given argument cannot be converted to a valid value
Returns
Method returns the service instance allowing chaining or language if argument is omitted.
routeRepresentation([routeRepresentation]): String Chainable
A setter and getter for 'routeRepresentation' attribute.
Specifies the representation of the set of routes provided as response. Possible values:
- polyline includes routes in the response.
- none includes only the optimized waypoint indices but does not include the routes in the response.
- summaryOnly includes only route summary in the response
This parameter value none can only be used in conjunction with computeBestOrder true.
Parameters
Name | Description | Required | Type/Values | Default |
---|---|---|---|---|
routeRepresentation | Allows the routing response to omit the actual route and give only the best ordered waypoints. | No | String | None |
Throws
if the given argument cannot be converted to a valid value
Returns
Method returns the service instance allowing chaining or language if argument is omitted.
routeType([routeType]): String Chainable
A setter and getter for 'routeType' attribute. The type of route requested. Notes on specific values:
- fastest returns the fastest route.
- shortest returns the shortest route by distance.
- eco routes balance economy and speed.
- thrilling routes include interesting or challenging roads and use as few motorways as possible. You can choose the level of turns included and also the degree of hilliness. See the hilliness and windingness parameters for how to set this. There is a limit of 900 km on routes planned with routeType=thrilling
Default value is fastest
Parameters
Name | Description | Required | Type/Values | Default |
---|---|---|---|---|
routeType | Route type to be used during route calculation. | No | String | None |
Throws
if the given argument cannot be converted to a valid value
Returns
Method returns the service instance allowing chaining or route type value if argument is omitted.
sectionType([sectionType]): String[] Chainable
A getter and setter for the 'sectionType' attribute.
Specifies which of the section types is reported in the route response.
Possible values:
- carTrain: car or train sections in the route
- ferry: ferry sections
- tunnel: tunnel sections
- motorway: motorway sections
- tollRoad: payed toll sections
- pedestrian: sections which are suited for pedestrians only
- tollVignette: sections which require a toll vignette to be present
- country: returns country sub sections in the route
- travelMode: sections in relation to the request parameter travelMode
- traffic: returns traffic sub sections in the route, values include: JAM, ROAD_WORK, ROAD_CLOSURE and OTHER
Default value is travelMode.
Parameters
Name | Description | Required | Type/Values | Default |
---|---|---|---|---|
sectionType | Array of section types | No | String[] | None |
Throws
If the given argument cannot be converted into a valid value
Returns
The same service instance or the current option value if no argument was given
supportingPoints([locations]): String Chainable
A getter and setter for the 'supportingPoints' attribute.
Can be used to set supporting points for constructing (or reconstructing) a route and for calculating alternative routes to a base route. The provided sequence of supporting points is used as input for route reconstruction.
Pseudo examples:
- If the base route is A > B and we include a supporting point C, the result will be A > C > B;
- Supporting points can be used to reconstruct entirely a route you previously had: Let's illustrate the problem. To go from A > B you received A > C > D > E > B. If later, you try to generate the same route (A > B) you might get different middle points, so if you need to generate the exact same route you previously had you can do something like routing().locations(A, B).supportingPoints(C, D, E)
You can use one of the following input formats to define the supporting points:
- String: '52.3,4.8' or '52.3,4.8:52.37,4.87'
- String[]: ['52.3,4.8:52.37,4.87', '52.3,4.8:52.37,4.87']
- Object: {lat: 52.3, lon: 4.8} or {lat: 53.3, lng: 5.8} or {x: 53.3, y: 5.8} or {latitude: 53.3, longitude: 5.8}
- Object[]: [{lat: 52.3, lon: 4.8}] or [{lat: 53.3, lng: 5.8}]
How 'Supporting Points' differ from 'Waypoints?' - Waypoints are points where the calculated route will go through, but the resulting route might be different from search to search, the waypoints order might not be necessarilly respected when calculating the best route, and finally, there is a limit to the number of waypoints you can use in a route calculation. Supporting points can be used to contruct a previous route entirely, or parts of it, using the previous generated points, meaning that there is no limit to the number of points, and the order of these points will be respected.
For more information please refer to the Routing API Docs
Parameters
Throws
if the given argument cannot be converted to a valid value
Returns
Method returns the service instance allowing chaining or converted locations value if argument is omitted.
Example
tomtom.routing()
.locations('52.3,4.8:52.37,4.87')
.supportingPoints('52.33357,4.852')
.go()
.then(function(routeGeoJson) {
console.log(routeGeoJson);
});
timeBudgetInSec(timeBudgetInSec): String Chainable
Getter and setter for timeBudgetInSec.
Parameters
Name | Description | Required | Type/Values | Default |
---|---|---|---|---|
timeBudgetInSec | Time budget in seconds that determines maximal range which can be travelled using driving time. The consumption parameters will only affect eco-routes and thereby indirectly the driving time. | Yes | Number | None |
Throws
if the given argument cannot be converted to a valid value
Returns
Method returns the service instance allowing chaining or current value if argument is omitted.
traffic([traffic]): Boolean Chainable
A setter and getter for 'traffic' attribute.
Possible values:
- true (just considers all available traffic information during routing)
- false (ignores current traffic data during routing). Note that although the current traffic data is ignored during routing, the effect of historic traffic on effective road speeds is still incorporated.
Default is true
Parameters
Name | Description | Required | Type/Values | Default |
---|---|---|---|---|
traffic | Boolean flag determines if traffic data should be used to calculate the route. | No | Boolean | None |
Throws
if the given argument cannot be converted to a valid value
Returns
Method returns the service instance allowing chaining or traffic value if argument is omitted.
travelMode([travelMode]): String Chainable
A setter and getter for 'travelMode' attribute.
The travel mode for the requested route.
Possible values: car, truck, taxi, bus, van, motorcycle, bicycle, pedestrian
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
Parameters
Name | Description | Required | Type/Values | Default |
---|---|---|---|---|
travelMode | The primary mean of transportation to be used while routing. | No | String | None |
Throws
if the given argument cannot be converted to a valid value
Returns
Method returns the service instance allowing chaining or language if argument is omitted.
uphillEfficiency([uphillEfficiency]): Number Chainable
A setter and getter for 'uphillEfficiency' attribute.
Specifies the efficiency of converting chemical energy stored in fuel to potential energy when the vehicle gains elevation (i.e. PotentialEnergyGained/ChemicalEnergyConsumed). ChemicalEnergyConsumed is obtained by converting consumed fuel to chemical energy using fuelEnergyDensityInMJoulesPerLiter.
Parameters
Name | Description | Required | Type/Values | Default |
---|---|---|---|---|
uphillEfficiency | No | Number | None |
Throws
if the given argument cannot be converted to a valid value
Returns
Method returns the service instance allowing chaining or current value if argument is omitted.
vehicleAxleWeight([vehicleAxleWeight]): Number Chainable
A setter and getter for 'vehicleAxleWeight' attribute.
Weight per axle of the vehicle in kg. A value of 0 means that weight restrictions per axle are not considered during route planning. This parameter is currently only considered for travelMode truck.
Parameters
Name | Description | Required | Type/Values | Default |
---|---|---|---|---|
vehicleAxleWeight | The vehicle axle weight in kg. | No | Number | None |
Throws
if the given argument cannot be converted to a valid value
Returns
Method returns the service instance allowing chaining or current value if argument is omitted.
vehicleCommercial([vehicleCommercial]): String Chainable
A setter and getter for 'vehicleCommercial' attribute.
Vehicle is used for commercial purposes and thus may not be allowed to drive on some roads. This parameter is currently only considered for travelMode truck.
Parameters
Name | Description | Required | Type/Values | Default |
---|---|---|---|---|
vehicleCommercial | True if vehicle is used for commercial purposes. | No | Boolean | None |
Throws
if the given argument cannot be converted to a valid value
Returns
Method returns the service instance allowing chaining or current value if argument is omitted.
vehicleEngineType([vehicleEngineType]): String Chainable
A setter and getter for 'vehicleEngineType' attribute.
Engine type of the vehicle. This parameter is currently only considered for travelMode truck. Valid options are: combustion, electric
Parameters
Name | Description | Required | Type/Values | Default |
---|---|---|---|---|
vehicleEngineType | The vehicle engine type. | No | String | None |
Throws
if the given argument cannot be converted to a valid value
Returns
Method returns the service instance allowing chaining or current value if argument is omitted.
vehicleHeading([vehicleHeading]): Number Chainable
A setter and getter for 'vehicleHeading' attribute.
The directional heading of the vehicle in degrees starting at true North and continuing in clockwise direction. North is 0 degrees, east is 90 degrees, south is 180 degrees, west is 270 degrees. Possible values 0-359.
Parameters
Name | Description | Required | Type/Values | Default |
---|---|---|---|---|
vehicleHeading | The angle in which the vehicle is heading. | No | Number | None |
Throws
if the given argument cannot be converted to a valid value
Returns
Method returns the service instance allowing chaining or current value if argument is omitted.
vehicleHeight([vehicleHeight]): Number Chainable
A setter and getter for 'vehicleHeight' attribute.
Height of the vehicle in meters. A value of 0 means that height restrictions are not considered during route planning. This parameter is currently only considered for travelMode truck.
Parameters
Name | Description | Required | Type/Values | Default |
---|---|---|---|---|
vehicleHeight | The vehicle height in m. | No | Number | None |
Throws
if the given argument cannot be converted to a valid value
Returns
Method returns the service instance allowing chaining or current value if argument is omitted.
vehicleLength([vehicleLength]): Number Chainable
A setter and getter for 'vehicleLength' attribute.
Length of the vehicle in meters. A value of 0 means that length restrictions are not considered during route planning. This parameter is currently only considered for travelMode truck.
Parameters
Name | Description | Required | Type/Values | Default |
---|---|---|---|---|
vehicleLength | The vehicle length in m. | No | Number | None |
Throws
if the given argument cannot be converted to a valid value
Returns
Method returns the service instance allowing chaining or current value if argument is omitted.
vehicleLoadType([vehicleLoadType]): Array Chainable
A setter and getter for 'vehicleLoadType' attribute.
Types of cargo that may be classified as hazardous materials and restricted from some roads. Available vehicleLoadType values are US Hazmat classes 1 through 9, plus generic classifications for use in other countries.
Use these for routing in US
- USHazmatClass1 Explosives
- USHazmatClass2 Compressed gas
- USHazmatClass3 Flammable liquids
- USHazmatClass4 Flammable solids
- USHazmatClass5 Oxidizers
- USHazmatClass6 Poisons
- USHazmatClass7 Radioactive
- USHazmatclass8 Corrosives
- USHazmatClass9 Miscellaneous
Use these for routing in all other countries
- otherHazmatExplosive Explosives
- otherHazmatGeneral Miscellaneous
- otherHazmatHarmfulToWater Harmful to water
This parameter is currently only considered for travelMode truck.
Parameters
Throws
if the given argument cannot be converted to a valid value
Returns
Method returns the service instance allowing chaining or current value if argument is omitted.
vehicleMaxSpeed([vehicleMaxSpeed]): Number Chainable
A setter and getter for 'vehicleMaxSpeed' attribute.
Maximum speed of the vehicle in km/hour. A value of 0 means that an appropriate value for the vehicle will be determined and applied during route planning. A non-zero value may be overridden during route planning. This parameter is currently only considered for travelMode truck.
Parameters
Name | Description | Required | Type/Values | Default |
---|---|---|---|---|
vehicleMaxSpeed | The maximal allowed vehicle speed in km/h. | No | Number | None |
Throws
if the given argument cannot be converted to a valid value
Returns
Method returns the service instance allowing chaining or current value if argument is omitted.
vehicleWeight([vehicleWeight]): Number Chainable
A setter and getter for 'vehicleWeight' attribute.
Weight of the vehicle in kg. A value of 0 means that weight restrictions are not considered during route planning. This parameter is currently only considered for travelMode truck.
Parameters
Name | Description | Required | Type/Values | Default |
---|---|---|---|---|
vehicleWeight | The vehicle weight in kg. | No | Number | None |
Throws
if the given argument cannot be converted to a valid value
Returns
Method returns the service instance allowing chaining or current value if argument is omitted.
vehicleWidth([vehicleWidth]): Number Chainable
A setter and getter for 'vehicleWidth' attribute.
Width of the vehicle in meters. A value of 0 means that width restrictions are not considered during route planning. This parameter is currently only considered for travelMode truck.
Parameters
Name | Description | Required | Type/Values | Default |
---|---|---|---|---|
vehicleWidth | The vehicle width in m. | No | Number | None |
Throws
if the given argument cannot be converted to a valid value
Returns
Method returns the service instance allowing chaining or current value if argument is omitted.
windingness([windingness]): String Chainable
A setter and getter for 'windingness' attribute.
Level of turns for thrilling route. Possible values: low, normal, high This parameter can only be used in conjunction with routeType thrilling.
Parameters
Name | Description | Required | Type/Values | Default |
---|---|---|---|---|
windingness | The level of windingness on a thrilling route. | No | String | None |
Throws
if the given argument cannot be converted to a valid value
Returns
Method returns the service instance allowing chaining or language if argument is omitted.