WMS

Service version: 1
Last edit: 2023.08.01

Purpose

This is the TomTom Web Map Service (WMS) implementation. All of the calls in this service are compliant with the WMS 1.1.1 standard.

The service consists of:

  • GIS Software URL endpoint: This is suitable for entering required parameters into GIS applications.
  • GetCapabilities endpoint: This describes the available services.
  • GetMap endpoint: This is used to retrieve map tiles.

Run this endpoint

You can easily run this and other endpoints. Go to the TomTom API Explorer page and follow the directions.

Request data

GIS Software URL endpoint

This Maps WMS API endpoint can be provided for GIS software that manages the interaction with WMS services itself, such as ArcGIS and Quantum GIS. Specific requirements on where to enter this URL will vary by GIS software product. Check the GIS system's own help for details.

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}/map/{versionNumber}/wms/?key={Your_API_Key}

Example

get
Example request URL
https://api.tomtom.com/map/1/wms/?key={Your_API_Key}

curl command format

get
Request curl command
curl -XGET 'https://api.tomtom.com/map/1/wms/?key={Your_API_Key}'

Request parameters

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

  • Required parameters must be used or the call will fail.
  • Optional parameters may be used.

Note: There are no optional parameters in this endpoint.

Required parameters (GIS Software URL)

Description

baseURL


string

The base URL for calling TomTom services.


Value: api.tomtom.com

versionNumber


string

The version of the service to call.


Value: The current version is 1.

key


string

The authorization key for access to the API.


Value: Your valid API Key.

GetCapabilities endpoint

The GetCapabilities call is used to describe the different calls that are available through TomTom's implementation of version 1.1.1 of the Web Map Service.

HTTPS method: GET

See the following Request parameters section with the required and optional parameters tables for these values.

URL format

get
Request URL
https://{baseURL}/map/{versionNumber}/wms/?key={Your_API_Key}&service={service}&request={request}&version={version}

Example

get
Request example
https://api.tomtom.com/map/1/wms/?key={Your_API_Key}&service=WMS&request=GetCapabilities&version=1.1.1

curl command format

get
Request curl command
curl 'https://api.tomtom.com/map/1/wms/?key={Your_API_Key}&service=WMS&request=GetCapabilities&version=1.1.1'

Request parameters

In accordance with WMS standards, parameter labels are not case-sensitive, but case should be respected in parameter values.

  • Required parameters must be used or the call will fail.
  • 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.

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

Required parameters (GetCapabilities endpoint)

Description

baseURL


string

The base URL for calling TomTom services.


Value: api.tomtom.com

versionNumber


string

The version of the service to call.


Value: The current version is 1.

key


string

The authorization key for access to the API.


Value: Your valid API Key.

service


string

The service type.


Value: WMS

request


string

The request type.


Value: GetCapabilities

Optional parameters (GetCapabilities endpoint)

Description

version


float

The WMS service version.


Default value: 1.1.1

GetMap endpoint

The GetMap call implements the Web Map Service 1.1.1 standard to access TomTom map tiles. This service is described in the meta-data provided by the GetCapabilities call's response.

HTTPS method: GET

See the following Request parameters section with the required and optional parameters tables for these values.

URL format

get
Request URL
https://{baseURL}/map/{versionNumber}/wms/?key={Your_API_Key}&request={request}&bbox={boundingBox}&srs={srs}&width={width}&height={height}&format={format}&layers={layers}&styles={styles}&service={service}&version={version}

Example

get
Request example
https://api.tomtom.com/map/1/wms/?key={Your_API_Key}&service=WMS&version=1.1.1&request=GetMap&bbox=1.355233,42.982261,24.980233,56.526017&srs=EPSG:4326&width=1305&height=748&layers=basic
&styles=&format=image/png

curl command format

get
Request curl command
curl 'https://api.tomtom.com/map/1/wms/?key={Your_API_Key}&service=WMS&version=1.1.1&request=GetMap&bbox=1.355233,42.982261,24.980233,56.526017&srs=EPSG:4326&width=1305&height=748&layers=basic&styles=&format=image/png'

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.
  • 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 (GetMap endpoint)

Description

baseURL


string

The base URL for calling TomTom services.


Value: api.tomtom.com

versionNumber


string

The version of the service to call.


Value: The current version is 1.

key


string

The authorization key for access to the API.


Value: Your valid API Key.

request


string

The request type.


Value: GetMap

srs


string

A projection used in describing the bbox (bounding box).

  • EPSG:3857 is recommended, particularly at higher zoom levels.

  • Note that EPSG:3857 is functionally equivalent to EPSG:900913/EPSG:3785

Values:

bbox


float

The bounding box in the projection stated in srs.
Value: minLon,minLat,maxLon,maxLat

width


integer

The width of the resulting image, in pixels.


Maximum value: 2048

height


integer

The height of the resulting image, in pixels.


Maximum value: 2048

format


string

The image format to be returned.


Values:

  • image/jpeg

  • image/png

layers


string

The map layers requested. Currently only the **basic** layer is available.


Value: basic

styles


string

The map styles to be returned.

  • This parameter is present for forward compatibility.
  • It must be used and left blank.


Value: Leave this blank: currently, no styles are available.

Optional parameters (GetMap endpoint)

Description

service


string

The service type.


Value: WMS

version


float

The WMS service version.


Default value: 1.1.1

Host Name Cycling

Most web browsers have a default limitation on the number of active connections that can be allowed to each host. This means if map tiles are being loaded via the api.tomtom.com host name, they will be loaded one at a time. A trick that can be used to get around this limitation is to cycle through the hosts we have created as aliases. These host names are:

  • a.api.tomtom.com
  • b.api.tomtom.com
  • c.api.tomtom.com
  • d.api.tomtom.com

By cycling through these four different host names, the web browser will be tricked into retrieving four map tiles at a time rather than just one. This will significantly speed up the performance of map rendering.

For instance, if four map tiles are being requested at zoom level one, you would request the first one as:

get
Request URL using a.api.tomtom.com
https://a.api.tomtom.com/traffic/map/4/tile/flow/relative/1/0/0.pbf?key={Your_API_Key}

The second would be:

get
Request URL using b.api.tomtom.com
https://b.api.tomtom.com/traffic/map/4/tile/flow/relative/1/0/0.pbf?key={Your_API_Key}

and so on up until d.api.tomtom.com. When more than four tiles are being requested, start back again at a.api.tomtom.com.

Request headers

The following data table lists HTTP Request headers of particular interest to clients of the Maps WMS API 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.


Value: <string>

Response data

GIS Software URL endpoint

If this URL is entered correctly, WMS calls will operate within the software. If the GIS software is reporting errors on WMS calls, the causes may be as described in the following Response codes section.

GetCapabilities endpoint

Responses will use the response codes listed in the following table, and implement the WMS 1.1.1 exception document type definition. A full schema of the 1.1.1 WMS GetCapabilities call is available online.

The following response XML code block is an example of a successful response returned by this specific call. For the meanings and use of the different elements, please refer to the schema.

Response body - XML
1<?xml version="1.0" encoding="UTF-8" standalone="no" ?>
2<!DOCTYPE WMT_MS_Capabilities SYSTEM "http://schemas.opengis.net/wms/1.1.1/capabilities_1_1_1.dtd">
3<WMT_MS_Capabilities version="1.1.1">
4 <Service>
5 <Name>OGC:WMS</Name>
6 <Title>TomTom WMS</Title>
7 <Abstract>The TomTom Web Map Server (WMS) provides and Open Geospatial Consortium (OGC) compliant Web Map Service interface as an online mapping service.</Abstract>
8 <OnlineResource xmlns:xlink="http://www.w3.org/1999/xlink" xlink:type="simple" xlink:href="https://api.tomtom.com/map/1/wms/?key=<apiKey>"/>
9 <ContactInformation>
10 (...contact information for support of the service)
11 </ContactInformation>
12 <Fees>none</Fees>
13 <AccessConstraints>none</AccessConstraints>
14 </Service>
15 <Capability>
16 <Request>
17 <GetCapabilities>
18 <Format>application/vnd.ogc.wms_xml</Format>
19 <DCPType>
20 <HTTP>
21 <Get>
22 <OnlineResource xmlns:xlink="http://www.w3.org/1999/xlink" xlink:type="simple" xlink:href="https://api.tomtom.com/map/1/wms/?key=<apiKey>&amp;"/>
23 </Get>
24 </HTTP>
25 </DCPType>
26 </GetCapabilities>
27 <GetMap>
28 <Format>image/jpeg</Format>
29 <Format>image/png</Format>
30 <DCPType>
31 <HTTP>
32 <Get>
33 <OnlineResource xmlns:xlink="http://www.w3.org/1999/xlink" xlink:type="simple" xlink:href="https://api.tomtom.com/map/1/wms/?key=<apiKey>&amp;"/>
34 </Get>
35 </HTTP>
36 </DCPType>
37 </GetMap>
38 </Request>
39 <Exception>
40 <Format>application/vnd.ogc.se_xml</Format>
41 </Exception>
42 <Layer>
43 <Title>World Map</Title>
44 <SRS>EPSG:4326</SRS>
45 <SRS>EPSG:3857</SRS>
46 <SRS>EPSG:900913</SRS>
47 <LatLonBoundingBox minx="-180" miny="-85.0511287798" maxx="180" maxy="85.0511287798"/>
48 <BoundingBox SRS="EPSG:3857" minx="-20037508.34" miny="-20037508.34" maxx="20037508.34" maxy="20037508.34"/>
49
50 <Layer queryable="0" opaque="1">
51 <Name>basic</Name>
52 <Title>TomTom Map</Title>
53 <BoundingBox SRS="EPSG:4326" minx="-180.0" miny="-85.0511287798" maxx="180.0" maxy="85.0511287798"/>
54 <ScaleHint min="0" max="124000"/>
55 </Layer>
56 </Layer>
57 </Capability>
58</WMT_MS_Capabilities>

GetMap endpoint

The response to a successful call will be the requested tile. Exception responses will use the response codes described in the following HTTP response codes section and implement the WMS 1.1.1 exception document type definition.

Error response

The Map Display API WMS service for an invalid request returns a response body in XML or JSON format. The XML format is returned by default. To have an error response returned in JSON format, application/json has to be specified in the Accept HTTP request header.

Plain text format

Bad request

Error response field structure

Field

Description

detailedError


object

Main object of the error response; JSON format only.

ServiceExceptionReport


object

Main object of the error response; XML format only.

code


string

One of a server-defined set of error codes.

message


string

A human-readable description of the error code; JSON format only.

ServiceException


string

A human-readable description of the error code; XML format only.

details


array

Optional field. Details about an error; JSON format only. Contains objects which have following properties:

  • code
  • message
  • target

target


string

Name of an invalid parameter; JSON format only.

version


string

WMS service version; XML format only.

Error response example - JSON
1{
2 "detailedError": {
3 "code": "BAD_REQUEST",
4 "message": "Bad request",
5 "details": [
6 {
7 "code": "INVALID_PARAM",
8 "message": "Invalid request value GetMap1. Supported request value is 'GetMap'",
9 "target": "request"
10 }
11 ]
12 }
13}
Error response format - XML
1<?xml version="1.0" encoding="ISO-8859-1" ?>
2<ServiceExceptionReport version="1.1.1">
3 <ServiceException code="MALFORMED_REQUEST">Invalid request value GetMap1. Supported request value is 'GetMap'</ServiceException>
4</ServiceExceptionReport>

Response codes

Code

Meaning & possible causes

200

OK

202

Accepted : Received by the interface, but there is a WMS exception in processing it. Possible causes include:

  • One or more required parameters is missing.
  • An unsupported or unrecognized parameter value.
  • A malformed bounding box was requested.
  • Invalid map dimensions were requested.

This code is returned if the parameters of the WMS request were malformed. A detailed exception explanation is returned in a response in the form of a Service Exception Report.

403

Unauthorized : The supplied API Key is not valid for the request.

429

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

500

Internal Server Error : There is a problem with the TomTom WMS service.

Response headers

The following table lists HTTP response headers of particular interest to clients of the Maps WMS API endpoint.

Header

Description

Access-Control-Allow-Origin

The Maps WMS API allows cross-origin resource sharing (CORS).


Value: *

Content-Length

Contains information about the size of the response body.


Value: <decimal number>

Content-Type

Indicates the media type of the resource returned.


Values:

  • image/png

  • image/jpeg

  • application/vnd.ogc.wms_xml

Date

Contains the date and time at which 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.
Value: <string>