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

Additional Data

 

Service version: 2.0
Last edit: 2019.02.01

On this page

Purpose

The Additional Data service allows you to request extra data for a set of entities, previously retrieved from a Search Request. The service supports the following additional data type: Geometry data, such as a city or country outline.

Additional Data IDs retrieved from the Search endpoint have a limited lifetime.

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

Run this endpoint

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.

▲ Return to top

Request data

HTTPS Method: GET

URL format

For identification purposes:

  • Required constants and parameters are shown in bold text.
  • Optional parameters are shown in plain text.
https://api.tomtom.com/search/2/additionalData.json?key=***** &geometries=00004631-3400-3c00-0000-0000673c4d2e%2C00004631-3400-3c00-0000-0000673c42fe&geometriesZoom=22

curl command

curl -v -XGET -H
'https://api.tomtom.com/search/2/additionalData.json?key=*****
&geometries=00004631-3400-3c00-0000-0000673c4d2e%2C00004631-3400-3c00-0000-0000673c42fe
&geometriesZoom=22'

▲ 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.
  • A parameter's data type is beneath its name.
  • If there is a default value that will be assumed when an optional parameter is not used, it is shown in the table.
  • The order of request parameters is not important.
Required parameters
Parameter Description
baseURL
string
Base URL for calling the API:
Value: api.tomtom.com
versionNumber
integer
Service version number.
Value: The current value is 2.
ext
string
Valid response formats.
Value: JSON, JSONP, JS, or XML.
geometries
string
Comma-separated list of geometry UUIDs, previously retrieved from a Search request.
Value: Comma-separated list of geometry UUIDs.
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.
Values: See the following section 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 data table for possible geometriesZoom values and their level of detail represented as precision.
  • The geometriesZoom value is applied to all the geometries in the response.
geometriesZoom values data
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

Response data

Response body

For illustrative purposes the example below is neatly indented and includes all possible Response fields.

  • Actual responses are more compact and the fields present will vary based on the result type and the data available.
  • See the following Response field section for more information.

The 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"
               }
            ]
         }
      }
   ]
}

▲ 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:

  • Additional data was retrieved.
  • The body of the response contains the 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 an HTTP method other than GET.
408 Request timeout: The request sent to the server took longer than it was prepared to wait.
414 Requested URI is too long: Indicates that the URI requested by the client is longer than the server is willing to interpret.
500 An error occurred while processing the request. Please try again later.
502 Internal network connectivity issue. Please try again later.
503 Service currently unavailable. Please try again later.
504 Internal network connectivity issue or a request that has taken too long to complete. Please try again later.
596 Service not found. Request contains an incorrect FQDN and/or path.

▲ Return to top

Response headers

The following data table contains response headers sent back from an API server.

Header Description
Access-Control-Expose-Headers The Additional Data service whitelists response headers that browsers are allowed to access.
Value: Content-Length
Access-Control-Allow-Origin The Additional Data service allows cross-origin resource sharing.
Value: *
Content-Encoding The Additional Data service supports HTTP compression, if requested by the client.
Value: 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.

Value: 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. It is supported by HTTP/1.0 clients.
Value: no-cache

▲ Return to Top