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

PricingContact
Maps API
Get your key

WMS

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

The service consists of:

  • GIS Software URL - suitable for entering the required parameters into GIS applications
  • GetCapabilities call - describes the available services
  • GetMap call - to retrieve map tiles

 

Request

GIS Software URL

The Maps WMS API's 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.

Format

The generic WMS URL format that can be used in GIS applications is as follows:

<http|https>://<baseURL>/map/<versionNumber>/wms/?key=<apiKey>

Example

http://api.tomtom.com/map/1/wms/?key=<apiKey>

Parameters

Parameter Description Req'd? Type / Values Default Value
baseURL base URL for calling TomTom services Yes

api.tomtom.com

 —
/versionNumberNumber Version of the service to call. The current version is 1 Yes 1 —
key= Authorization key for access to the API Yes API Key —

 

GetCapabilities

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

Format

<http|https>://<baseURL>/map/<versionNumber>/wms/?key=<apiKey>&service=<service>&request=<request>[&version=<version>]

Example

http://api.tomtom.com/map/1/wms/?key=<apiKey>&service=WMS&request=GetCapabilities

Parameters

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

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 1 Yes 1 —
key= Authorization key for access to the API Yes API Key —
service= Service type Yes WMS —
request= Request type Yes GetCapabilities —
[version=] WMS service version No 1.1.1 1.1.1

 

GetMap

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.

Format

<http|https>://<baseURL>/map/<versionNumber>/wms/?key=<apiKey>&request=<request>&bbox=<boundingBox>&srs=<srs>&width=<width>&height=<height>&format=<format>&layers=<layers>&styles=<styles>[&service=<service>][&version=<version>]

Example

http://api.tomtom.com/map/1/wms/?key=<apiKey>&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

Parameters

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

Parameter Description Req'd? Type / Values Default Value
baseURL base URL for calling TomTom services Yes

api.tomtom.com
[a|b|c|d].api.tomtom.com
See the Host Name Cycling section for details on aliases.

 —
/versionNumber Version of the service to call. The current version is 1 Yes 1 —
key= Authorization key for access to the API Yes API Key —
request= Request type Yes GetMap —
srs= Projection used in describing the bbox
EPSG:3857 is recommended, particularly at higher zoom levels. (Note that EPSG:3857 is functionally equivalent to EPSG:900913/EPSG:3785)		 Yes —
bbox= Bounding box in the projection stated in srs Yes minLon,minLat,maxLon,maxLat —
width= Width of the resulting image, in pixels
Maximum value is 2048		 Yes Integer —
height= Height of the resulting image, in pixels
Maximum value is 2048		 Yes Integer —
format= Image format to be returned Yes
  • image/jpeg
  • image/png
 —
layers= Map layers requested
Currently only the basic layer is available		 Yes basic —
styles= Map styles to be returned
Currently, no styles are available. This parameter is present for forward compatibility; it must be used and left blank.		 Yes [leave blank] —
[service=] Service type No WMS WMS
[version=] WMS service version No 1.1.1 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 and 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 speed up performance of map rendering greatly.

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

http://a.api.tomtom.com/map/1/wms?key=&(further parameters)

The second would be:

http://b.api.tomtom.com/map/1/wms?key=&(further parameters)

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

For more information go here.

Response

GIS Software URL

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 Http Response Codes section below.

GetCapabilities

Responses will use the response codes listed below, 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. Below 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.

<?xml version="1.0" encoding="UTF-8" standalone="no" ?>
  <!DOCTYPE WMT_MS_Capabilities SYSTEM "http://schemas.opengis.net/wms/1.1.1/capabilities_1_1_1.dtd">
  <WMT_MS_Capabilities version="1.1.1">
          <Service>
                  <Name>OGC:WMS</Name>
                  <Title>TomTom WMS</Title>
                  <Abstract>The TomTom Web Map Server (WMS) provides and Open Geospatial Consortium (OGC) compliant Web Map Service interface as an online mapping service.</Abstract>
                  <OnlineResource xmlns:xlink="http://www.w3.org/1999/xlink" xlink:type="simple" xlink:href="http://api.tomtom.com/map/1/wms/?key=<apiKey>"/>
                  <ContactInformation>
                       (...contact information for support of the service)
                  </ContactInformation>
                  <Fees>none</Fees>
                  <AccessConstraints>none</AccessConstraints>
          </Service>
          <Capability>
                  <Request>
                          <GetCapabilities>
                                  <Format>application/vnd.ogc.wms_xml</Format>
                                  <DCPType>
                                          <HTTP>
                                                  <Get>
                                                          <OnlineResource xmlns:xlink="http://www.w3.org/1999/xlink" xlink:type="simple" xlink:href="http://api.tomtom.com/map/1/wms/?key=<apiKey>&amp;"/>
                                                  </Get>
                                          </HTTP>
                                  </DCPType>
                          </GetCapabilities>
                          <GetMap>
                                  <Format>image/jpeg</Format>
                                  <Format>image/png</Format>
                                  <DCPType>
                                          <HTTP>
                                                  <Get>
                                                          <OnlineResource xmlns:xlink="http://www.w3.org/1999/xlink" xlink:type="simple" xlink:href="http://api.tomtom.com/map/1/wms/?key=<apiKey>&amp;"/>
                                                  </Get>
                                          </HTTP>
                                  </DCPType>
                          </GetMap>
                  </Request>
                  <Exception>
                          <Format>application/vnd.ogc.se_xml</Format>
                  </Exception>
                  <Layer>
                          <Title>World Map</Title>
                          <SRS>EPSG:4326</SRS>
                          <SRS>EPSG:3857</SRS>
                          <SRS>EPSG:900913</SRS>
                          <LatLonBoundingBox minx="-180" miny="-85.0511287798" maxx="180" maxy="85.0511287798"/>
                          <BoundingBox SRS="EPSG:3857" minx="-20037508.34" miny="-20037508.34" maxx="20037508.34" maxy="20037508.34"/>
  
                          <Layer queryable="0" opaque="1">
                                  <Name>basic</Name>
                                  <Title>TomTom Map</Title>
                                  <BoundingBox SRS="EPSG:4326" minx="-180.0" miny="-85.0511287798" maxx="180.0" maxy="85.0511287798"/>
                                  <ScaleHint min="0" max="124000"/>
                          </Layer>
            </Layer>
          </Capability>
  </WMT_MS_Capabilities>

 

GetMap

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

 

Http Response Codes

Code Meaning and 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
  • unsupported or unrecognized parameter value
  • malformed bounding box requested
  • invalid map dimensions requested

This code is returned if the parameters of the WMS request were malformed. A detailed exception explanation is returned in a response in form of Service Exception Report.
401 Unauthorized: Supplied API key is not valid for the request
500 Internal Server Error: There is a problem with the TomTom WMS service

 

Response Headers

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

Header Description Values
Access-Control-Allow-Origin The Maps WMS API allows cross-origin resource sharing (CORS). *