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

Traffic Incident Viewport

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.

Request

Format

http(s)://<baseURL>/traffic/services/<versionNumber>/incidentViewport/<boundingBox>/<boundingZoom>/<overviewBox>/<overviewZoom>/<copyright>/<contentType>?key=<apiKey>[&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=<apiKey>

Parameters

The table below describes all of the parameters that can be used in a request. Parameters and values are case-sensitive. Required parameters must be used or the call will fail. Optional parameters, which are highlighted with [square brackets], 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.

Parameter Description Req'd? Type / Values Default Value
baseURL Base URL for calling TomTom services. Yes api.tomtom.com
versionNumber Version of the service to call.  The current version is 4. Yes 4
boundingBox Bounding box of the map viewport in 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 4092 pixels when rendered on the given zoom level.

Yes minY,minX,maxY,maxX
(See below for boxes crossing the 180° meridian)
boundingZoom Zoom level of the map viewport. Used to determine whether the view can be zoomed in. Yes 0 .. 22
overviewBox 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 boundingBox above.

Yes minY,minX,maxY,maxX
(See below for boxes crossing the 180° meridian)
overviewZoom Zoom level of the overview map. If there is no mini map, use the same zoom level as boundingZoom above. Yes 0 .. 22
copyright Determines what copyright information to return.

  • When true the copyright text is returned.
  • When false only the copyright index is returned.
Yes Boolean true
contentType 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.

Yes
  • xml
  • json
  • jsonp
apiKey Authorization key for access to the API. Yes String
[jsonp] Specifies the callback method. Only used where contentType is jsonp. No String

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.

Response

An XSD response schema is available for download.

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

<viewpResp xmlns="http://lbs.tomtom.com/services" maps="europe,hongkong,taiwan,vietnam,northamerica,middleeast,egypt,azores,southamerica,newzealand,australia,frenchguiana,indianocean,india,africa,world,southeastasia" version="1.0.22-mascoma">
	<trafficState trafficModelId="1400143970784" trafficAge="28320"/>
	<copyrightIds>
		&copy; 2014 GeoSmart^&copy; 2014 TomTom^&copy; 2014 Whereis
	</copyrightIds>
</viewpResp>

A typical response in JSON would be:

{
    "viewpResp":{
        "trafficState":{
            "@trafficAge":28320,
            "@trafficModelId":"1400143970784"
            },
	   "copyrightIds":"&copy; 2014 GeoSmart^&copy; 2014 TomTom^&copy; 2014 Whereis",
	   "@version":"1.0.22-mascoma",
       "@maps":"europe,hongkong,taiwan,vietnam,northamerica,middleeast,egypt,azores,southamerica,newzealand,australia,frenchguiana,indianocean,india,africa,world,southeastasia"
    }
}

Response Structure

Field Description
<viewpResp> Main response element.
Key attributes:

  • maps indicates the TomTom internal names for the map data used in the viewport
  • version indicates the software version that generated the response.
<trafficState> Traffic information.
Key attribute trafficModelId is the traffic model number needed for the Traffic Incidents Layer, and Traffic Incident Details API calls. It is updated every minute, and is valid for two minutes before it times out.
<copyrightIDs> Copyright information for the map viewport.
When /copyright 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.

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, usually due to malformed syntax
403 Forbidden: Supplied API key is not valid for this request
500 Internal Server Error