Developer

WMTS

Service version: 1
Last edit: 2023.08.01

Purpose

The Web Map Tile Service (WMTS) is the Open Geospatial Consortium (OGC)'s standard for delivering rectangular map tiles via RESTful web services. It consists of two key service calls: GetCapabilities and GetTile.

GetCapabilities

The "GetCapabilities" call documented here implements the 1.0.0 version of the WMTS standard. It returns an XML structure containing metadata on both the company hosting the service (in this case, TomTom) and the various layers that the service offers. That metadata is sufficient to allow calling systems to construct calls to Tomtom's Map Display API Raster Tile endpoint that retrieves individual raster map tiles for a given geographic extent, zoom level, and layer type.

GetTile

Because the TomTom WMTS services follow the OGC WMTS specification, it is then easy to use these services via third party tools such as Esri's ArcGIS Online. While less flexible than the WMS API, WMTS "GetTile" calls are tailored for speed. They retrieve single map tiles and do not aggregate tiles in order to deliver a single composited map image.

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}/map/{versionNumber}/wmts/apiKey={Your_API_Key}/{wmtsVersion}/WMTSCapabilities.xml

Example

get
Request example
https://api.tomtom.com/map/1/wmts/apiKey={Your_API_Key}/1.0.0/WMTSCapabilities.xml

curl command format

get
Request curl command
curl 'https://api.tomtom.com/map/1/wmts/apiKey={Your_API_Key}/1.0.0/WMTSCapabilities.xml'

Request parameters

The following table describes all 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.

Note: There are no optional parameters in this endpoint.

Required parameters

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.

apiKey


string

The authorization key for access to the API.


Value: Your valid API Key.

wmtsVersion


float

The version of the WMTS service.


Value: 1.0.0

Request headers

The following data table lists HTTP request headers of particular interest to clients of the Maps WMTS 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

A full schema (XSD) for the response is available from openGIS. The following XML code block is a partial example of a successful response. For the meanings and use of the different elements, please refer to the schema.

Response body (XML)

XML response body
1<?xml version="1.0" encoding="UTF-8"?>
2<Capabilities xmlns="http&#058;//www.opengis.net/wmts/1.0" xmlns&#058;ows="http&#058;//www.opengis.net/ows/1.1" xmlns&#058;xlink="http&#058;//www.w3.org/1999/xlink" xmlns&#058;xsi="http&#058;//www.w3.org/2001/XMLSchema-instance" xmlns&#058;gml="http&#058;//www.opengis.net/gml" xsi&#058;schemaLocation="http&#058;//www.opengis.net/wmts/1.0 http&#058;//schemas.opengis.net/wmts/1.0/wmtsGetCapabilities_response.xsd"version="1.0.0">
3  <ows&#058;ServiceIdentification>
4    <ows&#058;Title>TomTom Web Map Tile Service</ows&#058;Title>
5    <ows&#058;ServiceType>OGC WMTS</ows&#058;ServiceType>
6    <ows&#058;ServiceTypeVersion>1.0.0</ows&#058;ServiceTypeVersion>
7    <ows&#058;Fees>none</ows&#058;Fees>
8    <ows&#058;AccessConstraints>none</ows&#058;AccessConstraints>
9  </ows&#058;ServiceIdentification>
10

11  <ows&#058;ServiceProvider>
12    <ows&#058;ProviderName>TomTom International B.V.</ows&#058;ProviderName>
13    <ows&#058;ProviderSite xlink&#058;href="https&#058;//www.tomtom.com"/>
14    <ows&#058;ServiceContact>
15      (...contact information for support of the service...)
16    </ows&#058;ServiceContact>
17  </ows&#058;ServiceProvider>
18

19  <ows&#058;OperationsMetadata>
20    <ows&#058;Operation name="GetCapabilities">
21      (...metadata on the GetCapabilities call)
22    </ows&#058;Operation>
23    <ows&#058;Operation name="GetTile">
24      (...metadata on the GetTile call)
25    </ows&#058;Operation>
26  </ows&#058;OperationsMetadata>
27

28  <Contents>
29    <!-- Basic Map -->
30    <Layer>
31      <ows&#058;Title>TomTom Map &mdash; Standard</ows&#058;Title>
32      <ows&#058;WGS84BoundingBox crs="urn&#058;ogc&#058;def&#058;crs&#058;OGC&#058;2:84">
33        <ows&#058;LowerCorner>-180 -85</ows&#058;LowerCorner>
34        <ows&#058;UpperCorner>180 85</ows&#058;UpperCorner>
35      </ows&#058;WGS84BoundingBox>
36      <ows&#058;Identifier>ttms</ows&#058;Identifier>
37      <Style isDefault="true">
38        <ows&#058;Identifier>map/1/tile/basic/main</ows&#058;Identifier>
39      </Style>
40      <Format>image/png</Format>
41      <TileMatrixSetLink>
42        <TileMatrixSet>google900913</TileMatrixSet>
43      </TileMatrixSetLink>
44      <ResourceURL format="image/png" template="https&#058;//a.api.tomtom.com/{Style}/{TileMatrix}/{TileCol}/{TileRow}.png?key=apiKey" resourceType="tile"/>
45      <ResourceURL format="image/png" template="https&#058;//b.api.tomtom.com/{Style}/{TileMatrix}/{TileCol}/{TileRow}.png?key=apiKey" resourceType="tile"/>
46      <ResourceURL format="image/png" template="https&#058;//c.api.tomtom.com/{Style}/{TileMatrix}/{TileCol}/{TileRow}.png?key=apiKey" resourceType="tile"/>
47      <ResourceURL format="image/png" template="https&#058;//d.api.tomtom.com/{Style}/{TileMatrix}/{TileCol}/{TileRow}.png?key=apiKey" resourceType="tile"/>
48    </Layer>
49    <Layer>
50      (...metadata on additional layers...)
51      <Layer>
52

53        <TileMatrixSet>
54          <ows&#058;Identifier>google900913</ows&#058;Identifier>
55          <ows&#058;BoundingBox crs="urn&#058;ogc&#058;def&#058;crs&#058;EPSG&#058;6.18:3:3857">
56            <ows&#058;LowerCorner>20037508.3428 -20037508.3428</ows&#058;LowerCorner>
57            <ows&#058;UpperCorner>-20037508.3428 20037508.3428</ows&#058;UpperCorner>
58          </ows&#058;BoundingBox>
59          <ows&#058;SupportedCRS>urn&#058;ogc&#058;def&#058;crs&#058;EPSG&#058;6.18&#058;3&#058;3857</ows&#058;SupportedCRS>
60          <WellKnownScaleSet>urn&#058;ogc&#058;def&#058;wkss&#058;OGC&#058;1.0&#058;vGoogleMapsCompatible</WellKnownScaleSet>
61          <TileMatrix>
62            <ows&#058;Identifier>0</ows&#058;Identifier>
63            <ScaleDenominator>559082264.029</ScaleDenominator>
64            <TopLeftCorner>-20037508.3428 20037508.3428</TopLeftCorner>
65            <TileWidth>256</TileWidth>
66            <TileHeight>256</TileHeight>
67            <MatrixWidth>1</MatrixWidth>
68            <MatrixHeight>1</MatrixHeight>
69          </TileMatrix>
70          (...metadata on further matrixes...)
71        </TileMatrixSet>
72      </Contents>
73

74  <ServiceMetadataURL xlink:href="https&#058;//api.tomtom.com/map/1/wmts/apiKey/1.0.0/GetCapabilities.xml"/>
75</Capabilities>

Error response

The Map Display API WMTS service for an invalid request returns a response body in plain text or JSON format. The plain text 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

Malformed syntax

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 format - JSON
1{
2  "detailedError": {
3    "code": "BAD_REQUEST",
4    "message": "Malformed syntax"
5  }
6}

Response codes

Code

Meaning & possible causes

200

OK

400

Bad request : Probably malformed syntax.

403

Unauthorized : The supplied API Key is not valid for this 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 WMTS service.

Response headers

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

Header

Description

Access-Control-Allow-Origin

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


Value: *

Cache-Control

Contains directives for a caching mechanism.


Values: public , max-age=<decimal number>

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: text/xml; charset=utf-8

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>