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

Additional Data


The Additional Data service allows you to request extra data for a set of entities, previously retrieved from an Search API request. The service supports the following additional data types:

  • geometry data, such as a city or country outline

Additional Data IDs retrieved from the Search API endpoint have a limited lifetime. Clients are expected to call the Additional Data API within a few minutes after having called the Search API request that returned these IDs. The service allows for batch requests up to 20 identifiers.

Request

Format

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

Parameters

The table below 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.

Parameter Description Req'd? Type / Values Default value Values
baseURL Base URL for calling the API. Yes api.tomtom.com
versionNumber Service version number. The current value is 2. Yes 2
ext Valid response format is JSON. Yes String json
geometries Comma-separated list of geometry UUIDs, previously retrieved from an Search API request. Yes String
key Your TomTom API Key. Yes String
[geometriesZoom] When the geometries parameter is provided, geometriesZoom defines the precision of the geometries. See table 1 for geometriesZoom values. No Integer 0..22

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

Response

Format

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

{
   "additionalData":[
      {
         "providerID":"00004145-3100-3c00-1110-000023c34641",
         "error":"The requested entity does not exist."
      },
      {
         "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
                           ]
                        ]
                     ]
                  },
               "id": "00004145-3100-3c00-0000-000023c34645"
               }
            ]
         }
      }
   ]
}
    

Response fields

The tables below describe 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.

Field Description Type / Values
Response
additionalData Root array element for actual additional data. AdditionalData[]
AdditionalData
providerID ID of the returned entity. String
error Reason for the failure to obtain data for this provider. String
geometryData Geometry data. Only present if "error" is not present. GeoJSON

Response codes

Code Meaning and possible causes
200 OK: additional data were retrieved and the body of the response contains requested data.
400 Bad request: one or more parameters(i.e. geometries, ext, geometriesZoom) were incorrectly specified
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.

Response headers

The table below lists HTTP response headers of particular interest to Additional Data service clients.

Header Description Values
Access-Control-Expose-Headers The Additional Data service whitelists response headers that browsers are allowed to access. Content-Length
Access-Control-Allow-Origin The Additional Data service allows cross-origin resource sharing. *
Content-Encoding The Additional Data service supports HTTP compression, if requested by the client. gzip
Cache-Control The Cache-Control general-header field is used to specify directives that must be obeyed by all caching mechanisms along the request/response chain. Supported by HTTP/1.1 clients. May not be supported by HTTP/1.0 clients. no-cache, no-transform
Pragma The Pragma general-header field is used to specify directives that might apply to any recipient along the request/response chain. Supported by HTTP/1.0 clients. no-cache