WMS

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.

You can easily run this and other endpoints.

1. Go to the TomTom API Explorer page.
2. Click an endpoint.
   1. Click Try it out.
   2. Enter/select all required parameter values and any optional parameter values.
   3. At the bottom of the form, click Execute.
3. Review the Response.

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:

https://baseURL/map/versionNumber/wms/?key=Your_API_Key

Example

https://api.tomtom.com/map/1/wms/?key=Your_API_Key

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.
• If there is a default value that will be assumed when an optional parameter is not used, it is shown in the table.

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.

https://baseURL/map/versionNumber/wms/?key=Your_API_Key&service=service&request=request&version=version

Example

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

curl command

curl -XGET '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.

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.

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

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

curl -XGET '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'

▲ Return to top

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.

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="https://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="https://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="https://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.

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

Error response example

JSON format

{
  "detailedError" : {
    "code" : "BAD_REQUEST",
    "message" : "Bad request",
    "details": [
      {
        "code": "INVALID_PARAM",
        "message": "Invalid request value GetMap1. Supported request value is 'GetMap'",
        "target": "request"
      }
    ]
  }
}

XML format

<?xml version="1.0" encoding="ISO-8859-1" ?>
<ServiceExceptionReport version="1.1.1">
  <ServiceException code="MALFORMED_REQUEST">Invalid request value GetMap1. Supported request value is 'GetMap'</ServiceException>
</ServiceExceptionReport>

▲ Return to top

HTTP response codes

HTTP Response headers

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