Maps SDK for Web
Class MatrixRouting
Matrix routing service implementation using using the TomTom's Routing API - Matrix Routing.
The Routing API - Matrix Routing service allows calculation of a matrix of route summaries for a set of routes which are defined with origin and destination locations.
For every given origin this service calculates the cost of routing from that origin to every given destination. The set of origins and the set of destinations can be thought of as the column and row headers of a table and each cell in the table contains the costs of routing from the origin to the destination for that cell.
The following costs are computed for each route:
- Travel times
- Distances
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 have two options for receive the response:
Constructor
MatrixRouting([options], [computeTravelTimeFor])
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 | An API Key issued from Developer Portal | No | String | global API key |
options.origins | A set of origin locations represented by coordinates (lat, lon). At least one origin is required. | No | Array | None |
options.destinations | A set of destination locations represented by coordinates (lat, lon). At least one destination is required. | Yes | Array | None |
options.routeType | The type of route requested. | No | String | 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. The possible values are documented here. | No | String | None |
options.avoid | Specifies something that the route calculation should try to avoid when determining the route. The possible values are documented here. | No | String | None |
options.departAt | The date and time of departure from the origin point | No | String | None |
options.arriveAt | The date and time of arrival at the destination point response | No | String | None |
options.hilliness | Degree of hilliness for thrilling route. The possible values are documented here. | No | String | 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. One of "combustion" or "electric" | 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. The possible values are documented here. | 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. The possible values are documented here. | No | String | None |
options.protocol | Protocol's type, one of "http" or "https". | No | String | None |
computeTravelTimeFor | Setting to all provides additional information regards travel times. | No | String | None |
Example
var origins = [
{ point: { latitude: 51.63685, longitude: 19.4171 } },
{ point: { latitude: 51.63685, longitude: 19 } }
];
var destinations = [
{ point: { latitude: 52.23498, longitude: 21.00849 } },
{ point: { latitude: 52.63685, longitude: 18 } }
];
function callbackFn(routeGeoJson) {
console.log(routeGeoJson);
}
var request = tomtom.matrixRouting({
origins: origins,
destinations: destinations,
traffic: true
});
request.go()
.then(callbackFn);
Methods
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.
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.
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();
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 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.
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.
destinations([destinations]): String Chainable
A setter and getter for 'destinations' attribute. A set of destination locations represented by points (lat,lon). At least one destination is required.
Parameters
Name | Description | Required | Type/Values | Default |
---|---|---|---|---|
destinations | A set of origin locations represented by points (lat,lon). | 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.
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();
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.
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 Search API 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
origins([origins]): String Chainable
A setter and getter for 'origins' attribute. A set of origin locations represented by points (lat,lon). At least one origin is required.
Parameters
Name | Description | Required | Type/Values | Default |
---|---|---|---|---|
origins | A set of origin locations represented by points (lat,lon). | 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.
routeType([routeType]): String Chainable
A setter and getter for routeType
attribute.
Represent 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.
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.