Sorry, you need to enable JavaScript to visit this website.

Traffic Incident Viewport

 

Service version: 4
Last edit: 2019.02.21

On this page

Purpose

This service returns legal and technical information for the viewport described in the Request. It should be called by client applications whenever the viewport changes (for instance, through zooming, panning, going to a location, or displaying a route).

The Request should contain the bounding box and zoom level of the viewport whose information is needed.

  • The return will contain map version information, as well as the current Traffic Model ID and copyright IDs.
  • The Traffic Model ID returned by the Viewport Description is used by other services to retrieve last traffic information for further processing.

Run this endpoint

You can easily run this and other endpoints.

  1. Go to the TomTom API Explorer page.
  2. Click an endpoint.
    1. Click Try it out.
    2. Enter/select all required parameter values and any optional parameter values.
    3. At the bottom of the form, click Execute.
  3. Review the Response.

Request data

HTTPS method: GET

URL format

For ease of viewing and identification:

  • Required constants and parameters are shown in bold text.
  • Optional parameters are shown in plain text.
http(s)://baseURL/traffic/services/versionNumber/incidentViewport/boundingBox/boundingZoom/overviewBox/overviewZoom/copyright/contentType?key=*****&jsonp=jsonp

Example

https://api.tomtom.com/traffic/services/4/incidentViewport/-939584.4813015489,-23954526.723651607,14675583.153020501,25043442.895825107/2/-939584.4813015489,-23954526.723651607,14675583.153020501,25043442.895825107/2/true/xml?key=*****

curl command

curl -XGET 'https://api.tomtom.com/traffic/services/4/incidentViewport/-939584.4813015489,-23954526.723651607,14675583.153020501,25043442.895825107/2/-939584.4813015489,-23954526.723651607,14675583.153020501,25043442.895825107/2/true/xml?key=*****'

▲ Return to top

Request parameters

The following table describes the parameters that can be used in a request.

  • Required parameters must be used or the call will fail.
  • Parameters and values are case-sensitive.
  • Optional parameters may be used.
  • If there is a default value that will be assumed when an optional parameter is not used, it is shown in the table.
Required parameters
Parameter Description
baseURL
string
The base URL for calling TomTom services.
Value: api.tomtom.com
versionNumber
string
Version of the service to call.
Value: The current value is 4.
boundingBox
float
Bounding box of the map viewport in an EPSG900913 projection.

  • The maximum size of the bounding box that can be passed is dependent on the requested zoom level.
  • The width and height cannot exceed the square of a side of 16 tiles for a given zoom level.
  • See the Maximum bounding box section for details.

Value: minY,minX,maxY,maxX
See below for boxes crossing the 180° meridian.

boundingZoom
integer
The zoom level of the map viewport. Used to determine whether the view can be zoomed in.
Value: 0..22
overviewBox
float
Bounding box of the overview map in EPSG900913 projection.

  • Used in case the overview box/mini map has different copyright data than the main map.
  • If there is no mini map, use the same coordinates as in the preceding boundingBox parameter.

Value: minY,minX,maxY,maxX
See below for boxes crossing the 180° meridian.

overviewZoom
integer
Zoom level of the overview map. If there is no mini map, use the same zoom level as in the preceding boundingZoom parameter.
Value: 0..22
copyright
boolean
Determines what copyright information to return.

  • When true the copyright text is returned.
  • When false only the copyright index is returned.

Default value: true
Other value: false

contentType
string
The content type of the response structure.
If the content type is jsonp, a callback method must be specified at the end of the service call.
Values:

  • xml
  • json
  • jsonp
apiKey
string
The Authorization key for access to the API.
Value: Your valid API Key.
Optional parameters
Parameter Description
jsonp
string
Specifies the callback method.
It is only used where the contentType parameter value is jsonp.
Value: jsonp

▲ Return to top

Maximum bounding box

In EPSG900913 projection we use an extent of the world from -20037508.34 to 20037508.34 in each direction.

  • On each zoom level the world is divided into 2zoom x 2zoom tiles.
  • The maximum allowed size of the requested bounding box is a square of size 16 x 16 tiles.

For zoom level 5 and greater, the width and height cannot exceed 40075016.68 / 2zoom - 4.

Note that bounding boxes that cross the 180° meridian require special treatment.

  • For such boxes, the eastern maxX value will be negative, and thus less than the minX value west of the 180° meridian.
  • To address that, the value 40075016.6855874 should be added to the true maxX value before it is passed in the request.

▲ Return to top

Response data

Note: An XSD Response schema is available for download.

Response body

The XML Response of the preceding sample Request would look like this:

<viewpResp xmlns="http://lbs.tomtom.com/services" maps="world" version="1.0.22-mascoma">
	<trafficState trafficModelId="1400143970784" trafficAge="28320"/>
	<copyrightIds>
		https://www.tomtom.com/en_gb/thirdpartyproductterms/
	</copyrightIds>
</viewpResp>

A typical Response in JSON would be:

{
    "viewpResp":{
        "trafficState":{
            "@trafficAge":28320,
            "@trafficModelId":"1400143970784"
            },
	   "copyrightIds":"https://www.tomtom.com/en_gb/thirdpartyproductterms/",
	   "@version":"1.0.22-mascoma",
       "@maps":"world"
    }
}

Response field structure (XML)

The following data table describes all of the XML element fields that can appear in a Response.

XML Field Description
<viewpResp>
string/integer
The main response element. The key attributes are:

  • maps: Indicates the TomTom internal names for the map data used in the viewport
  • version: Indicates the software version that generated the Response.
<trafficState>
string/integer
Traffic information.

  • trafficModelId: The unique id called Traffic Model ID is used to traffic services calls.
    • It allows to obtain information from particular traffic updates.
    • Traffic Model ID is updated every minute, and is valid for two minutes before it times out.
  • trafficAge:
  • The elapsed time (in seconds) from the Traffic Model ID creation.
<copyrightIDs>
boolean
Copyright information for the map viewport.

  • When the copyright parameter value is true, this contains the full text of the copyright information that must be displayed with the tiles in the viewport.
  • When it is false, it indicates which copyright holders must be cited but does not list them out.

▲ Return to top

Errors

If there is an error in the supplied parameters or any other internal problem:

  • An error Response is generated in the requested format.
  • If the contentType parameter could not be parsed, XML will be returned.

HTTP Response codes

Code Meaning and Possible Causes
200 OK
400 Bad request
403 Forbidden: The supplied API Key is not valid for this request.
500 Internal Server Error
503 Service currently unavailable: The service is currently unavailable.
596 Service Not Found: Unknown version of the service.

▲ Return to top

HTTP Response headers

The following table lists HTTP Response headers of particular interest to clients of the Traffic Incident Viewport API endpoint.

Header Description
Access-Control-Allow-Origin The API allows cross-origin resource sharing (CORS).
Value: *
Cache-Control The API specifies directives for a caching mechanism.
Values: <private, no-cache, no-store, max-age=0, must-revalidate>
Content-Length The API contains information about the size of the Response body.
Value: <decimal number>
Content-Type The API indicates the media type of the resource returned.
Value: <text/xml; charset=utf-8>
Date The API contains the date and time at which the message was originated.
Value: <http-date>

▲ Return to top