Maps Web SDK
Class ReachableRange
| Category | Services |
Calculate reachable range implementation using using the TomTom's Reachable Range API.
Allows to make route request using the TomTom's Calculate Reachable Range API Documentation.
The Calculate Reachable Range service calculates a set of locations that can be reached from the origin point, subject to the available fuel or energy budget that is specified in the request.
The information returned is a polygon boundary in counterclockwise orientation and the precise polygon center (the result of map-matching the origin point).
Constructor
ReachableRange([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.origin | Point from which the range calculation should start. | No | Array | String | None |
| options.fuelBudgetInLiters | Fuel budget in liters that determines maximal range which can be travelled using the specified Combustion Consumption Model. Required if vehicleEngineType is combustion. | No | Number | None |
| options.energyBudgetInkWh | Electric energy budget in kilowatt hours (kWh) that determines maximal range which can be travelled using the specified Electric Consumption Model. Required if vehicleEngineType is electric. | No | Number | None |
| options.key | The API key to be used. | No | String | global API key |
| options.routeType | The type of route requested. | No | String | None |
| options.traffic | consider all available traffic information during routing determining the route. | No | String | None |
| options.departAt | The date and time of departure from the origin point response | No | String | None |
| options.travelMode | The mode of travel for the requested route | No | String | None |
| options.hilliness | Degree of hilliness for thrilling route | No | String | None |
| options.windingness | Level of turns for thrilling route | No | String | None |
| options.protocol | Protocol's type, one of "http" or "https". | No | String | None |
Example
tomtom.reachableRange({
origin: '51.776667,19.454722',
fuelBudgetInLiters: 5,
constantSpeedConsumptionInLitersPerHundredkm: ["10,20", "15,30"],
})
.go()
.then(function(rangeData) {
console.log(L.geoJson(rangeData));
})
.catch(function(error) {
console.error(error);
});
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.
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 cannot be used.
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.
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.
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.
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.
key([newValue]): String Chainable
Sets or returns the API key to be used in calls made by this service instance.
Setting a key for each instance of this class is not needed if the key was already setted globally using the tomtom.searchKey() function.
A valid API key is required to make use of the Online Search services. It can be issued from TomTom's Developer Portal.
Parameters
| Name | Description | Required | Type/Values | Default |
|---|---|---|---|---|
| newValue | key API Key valid for requested service | No | String | None |
Throws
If the given argument cannot be converted to a valid value
Returns
The same service instance or the current option value if no argument was given
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.
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([newValue]): String Chainable
Sets or returns the protocol option value to be used in the calls.
Represents the type of protocol used to perform service call.
Parameters
| Name | Description | Required | Type/Values | Default |
|---|---|---|---|---|
| newValue | Protocol type | No | "http" | "https" | None |
Throws
If the given argument cannot be converted to a valid value
Returns
The same service instance or the current option value if no argument was given
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.
traffic([traffic]): Boolean Chainable
A setter and getter for 'traffic' attribute. Possible values: true (do consider all available traffic information during routing) false (ignore 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
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 mode of travel 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 wight 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.
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.