Developer

Incident Viewport

Service version: 4
Last edit: 2022.08.15

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 response will contain map version information, as well as the most recent 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. Go to the TomTom API Explorer page and follow the directions.

Request data

HTTPS method: GET

  • Constants and parameters enclosed in curly brackets { } must be replaced with their values.
  • Please see the following Request parameters section with the required and optional parameters tables for their values. The generic request format is as follows.

URL format

get
Request URL
https://{baseURL}/traffic/services/{versionNumber}/incidentViewport/{boundingBox}/{boundingZoom}/{overviewBox}/{overviewZoom}/{copyright}/{contentType}?key={Your_API_Key}&jsonp={jsonp}

Example

get
Request 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={Your_API_Key}

curl command format

get
Request curl command
curl '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={Your_API_Key}'

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.

Required parameters

Description

baseURL
string

The base URL for calling TomTom services.
Values:

versionNumber
string

Version of the service to call.
Value: The current value is 4.

boundingBox
float

Bounding box of the map viewport in an EPSG:900913 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 EPSG:900913 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

Description

jsonp
string

Specifies the callback method. It is only used where the contentType parameter value is jsonp.
Value: jsonp

Maximum bounding box

In EPSG:900913 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.

Request headers

The following table lists HTTP request headers of particular interest to clients of the Traffic Incident Viewport endpoint. Note: There are no required headers in this endpoint.

Optional headers

Description

Tracking-ID

Specifies an identifier for the request. It can be used to trace a call. The value must match the regular expression '^[a-zA-Z0-9-]{1,100}$'. An example of the format that matches this regular expression is a UUID (e.g., 9ac68072-c7a4-11e8-a8d5-f2801f1b9fd1 ). For details check RFC 4122. If specified, it is replicated in the Tracking-ID response header. It is only meant to be used for support and does not involve tracking of you or your users in any form.
Value: <string>

Response data

Successful response

The Incident Viewport API endpoint for a valid single request returns a response in XML, JSON, or JSONP format.

XML response body example

The following XML code block demonstrates a successful response from the API server. Note: An XSD response schema is available for download.

The XML response of the preceding sample request would look like this:

XML response body
1<viewpResp xmlns=&quot;http://lbs.tomtom.com/services&quot; maps=&quot;world&quot; version=&quot;traffic-service 2.0.004&quot;>
2  <trafficState trafficModelId=&quot;1400143970784&quot; trafficAge=&quot;28320&quot;/>
3  <copyrightIds>
4    https://www.tomtom.com/en_gb/thirdpartyproductterms/
5  </copyrightIds>
6</viewpResp>

A typical response in JSON would be:

JSON response body
1{
2  "viewpResp": {
3    "trafficState": {
4      "@trafficAge": 28320,
5      "@trafficModelId": "1400143970784"
6    },
7    "copyrightIds": "https://www.tomtom.com/en_gb/thirdpartyproductterms/",
8    "@version": "traffic-service 2.0.004",
9    "@maps": "world"
10  }
11}

Response field structure

The following table describes all of the XML/JSON element fields that can appear in a response. The types of the fields refer to a JSON response.

Field

Description

<viewpResp>
string

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 in calls to Traffic Incident services.

  • trafficAge: The elapsed time (in seconds) from the Traffic Model ID creation.

<copyrightIDs>
string

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.

Error response

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 is returned.

Error response field structure

Field

Description

detailedError{}
object

Main object of the error response.

code
string

One of a server-defined set of error codes.

message
string

A human-readable description of the error code.
Error response example - JSON
1{
2  "errorResponse": {
3    "@errorCode": 400,
4    "@description": "Error validating overviewBbox: ",
5    "@version": "traffic-service 4.0.010"
6  },
7  "detailedError": {
8    "code": "INVALID_REQUEST",
9    "message": "Error validating overviewBbox: "
10  }
11}
Error response example - XML
1<errorResponse description="Error validating overviewBbox: "errorCode"="400" version="traffic-service 4.0.010">
2  <detailedError>
3    <code>INVALID_REQUEST</code>
4    <message>Error validating overviewBbox: </message>
5  </detailedError>
6</errorResponse>

Response codes

Code

Meaning & possible causes

200

OK

400

Bad request

403

Forbidden: The supplied API Key is not valid for this request.

404

Not Found: The requested resource cannot be found.

405

Method Not Allowed: The provided HTTP request method is known by the server, but is not supported by the target resource.

429

Too Many Requests: Too many requests were sent in a given amount of time for the supplied API Key.

500

Internal Server Error

503

Service currently unavailable: The service is currently unavailable.

596

Service Not Found: Unknown version of the service.

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

Indicates that cross-origin resource sharing (CORS) is allowed.
Value: *

Allow

Lists the set of supported HTTP methods. The header is sent in case a 405 HTTP response code is returned.
Value: GET, HEAD

Cache-Control

Contains directives for a caching mechanism.
Values: <private, no-cache, no-store, max-age=0, must-revalidate>

Content-Length

Contains information about the size of the response body.
Value: <decimal number>

Content-Type

Indicates the media type of the resource returned.
Value:

  • <application/json; charset=utf-8>

  • <application/javascript; charset=utf-8>

  • <text/xml; charset=utf-8>

Date

Contains the date and time when the message was originated.
Value: <http-date>

Tracking-ID

An identifier for the request. If the Tracking-ID header was specified in the request, it is replicated in the response. Otherwise, it is generated automatically by the service. For details check RFC 4122. It is only meant to be used for support and does not involve tracking of you or your users in any form.
Value: <string>