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

Additional Data

 

Service version: 2
Last edit: 2019.03.28

On this page

Purpose

The Additional Data service endpoint returns sets of coordinates that represent the outline of a city, country, or land area. The service supports batch requests of up to 20 identifiers.

Request data

HTTPS Method: GET

Generic URL format

GET https://<baseURL>/search/<versionNumber>/additionalData.<ext>?key=<Your_API_Key>&geometries=<geometryIds>&[geometriesZoom=<zoomLevel>]

curl command format

curl -XGET -H "Content-type: application/json" 'https://<baseURL>/search/<versionNumber>/additionalData.<ext>?key=<Your_API_Key>&geometries=<geometryIds>&[geometriesZoom=<zoomLevel>]'

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, which are highlighted with [square brackets], 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
Parameter Description
baseURL
string
Base URL for calling the API:
Value: api.tomtom.com
versionNumber
string
Service version number.
Value: The current value is 2.
ext
string
The response format of the API request. The valid response format is JSON.
Value: json
geometries
string
A comma-separated list of geometry Ids, previously retrieved from a Search Request.
Value: A comma-separated list of geometry Ids.
key
string
An API Key valid for the requested service.
Value: Your valid API Key.
Optional parameters
Parameter Description
[geometriesZoom]
integer
When the geometries parameter is provided, [geometriesZoom] defines the precision of the geometries.
Maximum value: 22
Other values: See the following Table 1 for the optional [geometriesZoom] parameter values.

Optional Parameter: [geometriesZoom]

Clients can use the optional [geometriesZoom] parameter to control the level of detail in the returned geometry data.

  • Requests with lower zoom levels return less detailed geometries, which are also smaller in data size.
  • If the [geometriesZoom] parameter is not provided, the level of detail for that given geometry will not be changed.
  • See the following Table 1 for possible [geometriesZoom] values and their level of detail represented as precision.
  • The [geometriesZoom] value is applied to all the geometries in the Response.
Table 1: Precision per zoom level
Value Precision Area
0 156 km Whole world
1 78 km -
2 39 km -
3 19 km -
4 10 km Continent
5 5 km -
6 2.5 km -
7 1.2 km -
8 600 m -
9 300 m  
10 150 m Country
11 75 m -
12 40 m -
13 20 m -
14 10 m Village or town
15 5 m -
16 2.5 m -
17 1.2 m Small road
18 0.6 m -
19 0.3 m -
20 0.15 m -
21 0.075 m -
22 0.0375 m -

▲ Return to top

Request Headers

Required headers
Note: There are no required headers in this endpoint.
Optional headers
Header Description
[If-None-Match] Provides the entity tag (ETag) of the requested resource as last received by the client.

  • Allows efficient updates of cached information with a minimum amount of transaction overhead.
  • The service can respond with a 304 (not modified) message if the data that would otherwise be provided has the same entity tag.

Value: Entity tag. Example: "F13887B89265DBD6F8E38C3A96F21EF0"

Return to top

Response data

Response body

The Response will be a JSON object with the following structure:

{
  "additionalData": [
    {
      "providerID": "00004145-3100-3c00-1110-000023c34641",
      "error": "Requested geometry not found"
    },
    {
      "providerID": "00004145-3100-3c00-0000-000023c34645",
      "geometryData": {
        "type": "FeatureCollection",
        "features": [
          {
            "type": "Feature",
            "properties": {},
            "geometry": {
              "type": "Polygon",
              "coordinates": [
                [
                  [
                    -58.618436,
                    -34.546888
                  ],
                  [
                    -58.618162,
                    -34.547092
                  ],
                  [
                    -58.617562,
                    -34.547538
                  ],
                  [
                    -58.616396,
                    -34.548406
                  ],
                  [
                    -58.615583,
                    -34.549011
                  ],
                  [
                    -58.612135,
                    -34.5516584
                  ],
                  [
                    -58.6114201,
                    -34.5526017
                  ],
                  [
                    -58.6108784,
                    -34.5530107
                  ],
                  [
                    -58.6105212,
                    -34.5532873
                  ],
                  [
                    -58.6098298,
                    -34.5537771
                  ],
                  [
                    -58.609559,
                    -34.553973
                  ],
                  [
                    -58.608954,
                    -34.5544455
                  ],
                  [
                    -58.6086543,
                    -34.5546817
                  ],
                  [
                    -58.607888,
                    -34.5552463
                  ],
                  [
                    -58.6077382,
                    -34.5553731
                  ],
                  [
                    -58.6068163,
                    -34.5561048
                  ],
                  [
                    -58.6060671,
                    -34.5566521
                  ],
                  [
                    -58.6053463,
                    -34.5571967
                  ],
                  [
                    -58.6045748,
                    -34.5577815
                  ],
                  [
                    -58.6039179,
                    -34.5582827
                  ],
                  [
                    -58.6037623,
                    -34.5584037
                  ],
                  [
                    -58.6031631,
                    -34.558905
                  ],
                  [
                    -58.6028692,
                    -34.5591125
                  ],
                  [
                    -58.618436,
                    -34.546888
                  ]
                ]
              ]
            },
            "id": "00004145-3100-3c00-0000-000023c34645"
          }
        ]
      }
    }
  ]
}

▲ Return to top

Response fields

The following table describes all of the fields that can appear in a Response. Fields are listed by the Response section they belong to and in the order that they appear in the Response.

Primary fields
Field Description
additionalData
array
Root array element for actual additional data.
additionalData[] array
Field Description
providerID
string
ID of the returned entity.
error
string
Reason for the failure to obtain data for this provider.
geometryData
object (GeoJSON)
Geometry data. Only present if an "error" is not present.

▲ Return to top

HTTP Response codes

The following table contains Response codes signifying successful and failed requests to an API server.

Response Code Meaning & possible causes
200 OK:

  • If the given geometry was found, the body of the Response will contain the data.
  • Otherwise, the Response will have the applicable error message.
304 Not Modified: The requested content did not change since the last request, as indicated by the value of the If-None-Match HTTP header field.
400 Bad request: One or more parameters (i.e., geometries, ext, geometriesZoom) were incorrectly specified or are out of range.
403 Permission, capacity, or authentication issues:

  • Forbidden
  • Not authorized
  • Account inactive
  • Account over queries per second limit
  • Account over rate limit
  • Rate limit exceeded
404 Not Found: The requested resource could not be found, but it may be available again in the future.
405 Method Not Allowed: The client used a HTTP method other than GET.
408 Request timeout.
414 Requested URI is too long.
500 An error occurred while processing the Request. Please try again later.
502 Internal network connectivity issue.
503 Service currently unavailable.
504 Internal network connectivity issue or a Request that has taken too long to complete.
596 Service not found.

▲ Return to top

Response headers

The following table contains HTTP Response headers of particular interest to Additional Data service clients.

Header Description
Access-Control-Allow-Origin Ensures that clients implementing the CORS security model are able to access the Response from this service.
Value: An asterisk "*" that signifies access to the TomTom API using the Access-Control-Allow-Origin (ACAO) header in its Response indicating which origin sites are allowed.
Access-Control-Expose-Headers The Additional Data service whitelists Response headers that browsers are allowed to access.
Value: Content-Length
Content-Encoding The Additional Data service supports HTTP compression, if requested by the client.
Value: gzip
Content-Type Indicates the format of the Response, as chosen by the client.
Format: type/subtype; charset=utf-8
Value: type/subtype; application/json
ETag Entity-tag of the served resource. Can be used by the client in the If-None-Match header field of subsequent requests in order to optimize the update procedure.
Value: Example: "F13887B89265DBD6F8E38C3A96F21EF0"

▲ Return to Top

You are here