WMS
Service version: 1
Last edit: 2019.10.21
On this page
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.
- Click an endpoint.
- Click Try it out.
- Enter/select all required parameter values and any optional parameter values.
- At the bottom of the form, click Execute.
- Review the Response.
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
URL format
For ease of viewing and identification:
- Required constants and parameters are shown in bold text.
- Optional parameters are shown in plain text.
The generic WMS URL format that can be used in GIS applications is as follows:
http|http://baseURL/map/versionNumber/wms/?key=Your_API_Key
Example
http://api.tomtom.com/map/1/wms/?key=Your_API_Key
curl command
curl -XGET 'http://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.
- 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 (GIS Software URL) | |
---|---|
Parameter | 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. |
Optional parameters | |
Note: There are no optional parameters in this endpoint. |
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
URL format
For ease of viewing and identification:
- Required constants and parameters are shown in bold text.
- Optional parameters are shown in plain text.
http|https://baseURL/map/versionNumber/wms/?key=Your_API_Key&service=service&request=request&version=version
Example
http://api.tomtom.com/map/1/wms/?key=Your_API_Key&service=WMS&request=GetCapabilities&version=1.1.1
curl command
curl -XGET 'http://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) | |
---|---|
Parameter | 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 | |
Parameter | 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
URL format
For ease of viewing and identification:
- Required constants and parameters are shown in bold text.
- Optional parameters are shown in plain text.
http|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
http://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
curl -XGET 'http://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) | |
---|---|
Parameter | 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).
|
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:
|
layers string |
The map layers requested. Currently only the basic layer is available.Value: basic |
styles string |
The map styles to be returned.
|
Optional parameters | |
Parameter | 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:
http://a.api.tomtom.com/traffic/map/4/tile/flow/relative/1/0/0.pbf?key=Your_API_Key
The second would be:
http://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.
HTTP Request headers
The following data table lists HTTP Request headers of particular interest to clients of the Maps WMS API endpoint.
Required headers | |
---|---|
Note: There are no required headers in this endpoint. | |
Optional headers | |
Header | Description | Tracking-Id |
Specifies an identifier for the Request.
|
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 HTTP 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.
<?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>&"/>
</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>&"/>
</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 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.
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:
|
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. |
HTTP 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:
|
Date |
Contains the date and time at which the message was originated. Value: <http-date> |
Tracking-Id |
An identifier for the Request.
|