Maps SDK for Web
Class TrafficIncidents
Provides current traffic incidents in given region, on given zoom level with given style using the TomTom's Traffic API - Traffic Incidents Details
The current road situation is updated every minute. Please use the TrafficModelId service in conjunction with your request to get traffic incidents aligned with other services.
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:
The SDK provides a Promise polyfill for browsers (IE<9) without native ECMAScript 6 support.
The final response from this service is a GeoJSON object.
Constructor
TrafficIncidents([options])
Parameters
Name | Description | Required | Type/Values | Default |
---|---|---|---|---|
options | No | Object | None | |
options.key | An API Key issued from Developer Portal | No | String | None |
options.zoomLevel | A zoom level of the current map view <0, 18> . This option is required.
|
No | Number | None |
options.boundingBox | The area to extract incidents from. Conversion objects are described in the boundingBox function. | No | Object | Array | String | None |
options.style | Style name, needs to be one of "s1" , "s2" , "s3" , "night" .
This needs to match the style of your raster traffic tiles to match traffic tubes with traffic icons.
|
No | String | None |
options.language | ISO 639-1 language code of the incidentCause and description | No | String | "en" |
options.trafficModelID | Valid, not older than two minutes, traffic model ID. | No | Number | -1 |
options.expandCluster | Should service include details of incidents that are clustered | No | Boolean | false |
options.originalPosition | Should service include original incidents' position | No | Boolean | false |
options.protocol | Protocol's type | No | "http" | "https" | None |
options.preserveCluster | Determines if clusters should be preserved when requesting for details of all the incidents | No | Boolean | false |
Example
function callbackFn(response) {
console.log(response);
}
tomtom.trafficIncidents()
.key("<Your API key>")
.boundingBox("0,0,1,1")
.style("s1")
.zoomLevel(12)
.go(callbackFn);
Methods
boundingBox([newValue]): Object | Number[] | Object[] | String Chainable
Sets or returns the value of the boundingBox
option.
The bounding box is an area within the search results needs to limit to. If it is omitted then the whole world will be taken into consideration.
In case the area specified exceeds the world boundaries the following actions will be taken depending of which side was exceeded:
- Latitudes: the exceeded values will be replaced with their maximun.
- Longitudes: The service will split the area into two (or more) valid bounding boxes and will execute a search request for each one and them merge the responses into a single result.
This method is able to convert a number of popular formats into the bounding box.
The supported formats are listed below:
{minLon: 0, minLat: 0, maxLon: 1, maxLat: 1}
Plain object with the keys minLon, minLat, maxLon, maxLat.L.LatLngBounds
Leaflet's L.LatLngBounds object.[0, 0, 1, 1]
An array of numbers describing the bounding box following the order: minLon, minLat, maxLon, maxLat.ol.Extent
Open Layers extent object.[ol.Coordinate, ol.Coordinate]
An array of two open layers coordinate objects with the order: southWest, northEast.[[0, 0], [1, 1]]
A two-dimensional array with two indexes [southWest, northEast], each one with latitude and longitude values."0,0,1,1"
Comma separated string with numbers in the order: minLon, minLat, maxLon, maxLat.[{lon: 0, lat: 0},{lon: 1, lat: 1}]
A one-dimensional array with two objects in the order: southWest, northEast and each object with alat
andlon
keys.[{lng: 0, lat: 0},{lng: 1, lat: 1}]
A one-dimensional array with two objects in the order: southWest, northEast and each object with alat
andlon
keys.[L.LatLng, L.LatLng]
A one-dimensional array with two L.LatLng instances in the order: southWest and northEast.google.maps.LatLngBounds
Google Maps bounds object.google.maps.LatLngBoundsLiteral
Google Maps bounds object.[LatLng, LatLng]
array of two google.maps.LatLng.[LatLngLiteral, LatLngLiteral]
array of two google.maps.LatLngLiteral.
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();
expandCluster([newValue]): Boolean Chainable
Sets or returns the value of the expandCluster
option.
Tells the service to list all traffic incidents in a cluster separately.
When is enabled the clusters in the response will be represented as geometry collections and the cluster coordinates will appear as clusterCoordinates parameters.
Enabling this feature is useful when the user wants to obtain details of the incidents that are being clustered or wants to perform a client-side clustering.
Parameters
Name | Description | Required | Type/Values | Default |
---|---|---|---|---|
newValue | Should service include details of incidents that are clustered | No | Boolean | 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
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.
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
language([newValue]): String Chainable
Sets or returns the value of the language
option.
Expects an ISO 639-1 language code for the incidentCause
and description
fields in the response.
English is the default language.
The supported languages are: ca
, cs
, da
, de
, en
, es
, fi
, fr
, hu
,
it
, nl
, no
, pl
, pt
, sk
, sv
, tr
.
There is a conversion mechanism in place that will (ignoring the case) try to match the user input with a valid language.
For example: for the French language the following options are possible: "fr", "fre", "fr-fr", "fr_fr", "french".
Parameters
Name | Description | Required | Type/Values | Default |
---|---|---|---|---|
newValue | Language code, a conversion mechanism will be applied. | 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
originalPosition([newValue]): Boolean Chainable
Sets or returns the value of the originalPosition
option.
Return the original position of the incident (originalPosition
attribute) as well as the one
shifted to the beginning of the traffic tube.
Parameters
Name | Description | Required | Type/Values | Default |
---|---|---|---|---|
newValue | Should service include original incidents' position | No | Boolean | 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
preserveCluster([newValue]): Boolean Chainable
Sets or returns the value of the preserveCluster
option.
Tells the service to keep all traffic incidents clustered when receiving a list of all traffic incidents in a cluster separately.
This allows to get all the incidents details while remaining in clusters.
Parameters
Name | Description | Required | Type/Values | Default |
---|---|---|---|---|
newValue | Should service keep clusters data | No | Boolean | 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
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
style([newValue]): String Chainable
Sets or returns the value of the style
option.
The style that will be used to render the traffic tile in the Maps API. This will have an effect on the coordinates of traffic incidents in the reply.
Parameters
Name | Description | Required | Type/Values | Default |
---|---|---|---|---|
newValue | Style name, needs to be on of 's1', 's2', 's3', 'night'. This needs to match style of your raster traffic tiles to match traffic tubes with traffic icons. | 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
trafficModelID([newValue]): Number Chainable
Sets or returns the value of the trafficModelID
option.
Number referencing the traffic model to use. This can be obtained from the the TrafficModelId service.
It is updated every minute, and is valid for two minutes before it times out.
If a wrong Traffic Model ID is specified, the correct one will be returned by the interface.
The default value of -1
will always invoke the most recent traffic model. Nevertheless it is
a good practice to use the value obtained from the service as this will guarantee an alignment
with the raster traffic layer.
Parameters
Name | Description | Required | Type/Values | Default |
---|---|---|---|---|
newValue | Valid, not older than two minutes, traffic model ID. | 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
zoomLevel([newValue]): Number Chainable
Sets or returns the value of the zoomLevel
option.
The zoom level of currently displayed map. It is needed as the style (visibility, clustering, etc...) depends on current zoom level.
Parameters
Name | Description | Required | Type/Values | Default |
---|---|---|---|---|
newValue | Zoom level from 0 to 18
|
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