Developer

Additional Data

Service version: 1
Last edit: 2024.10.23
PUBLIC PREVIEW
TomTom Orbis Maps

Public Preview Notice

Important notes:

  • This TomTom Orbis Maps Search API document collection is in Public Preview. Go to the Public Preview - what is it? page to see what this means.
  • This API is powered by TomTom Orbis Maps.
  • See the TomTom Orbis Maps documentation for more information.

Purpose

The Geometries Data Provider 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.

Run this endpoint

You can easily run this and other endpoints. Go to the TomTom API Explorer page and follow the directions.

Request data

HTTPS Method: GET

For ease of viewing and identification:

  • Constants and parameters enclosed in curly brackets { } must be replaced with their values.
  • Please see the following Request parameters section with the required and optional parameters tables for their values. The generic request format is as follows.

Important note: Either the apiVersion parameter or TomTom-Api-Version header needs to be present.

get
URL request format
https://{baseURL}/maps/orbis/places/additionalData.{ext}?key={Your_API_Key}&apiVersion={apiVersion}&geometries={geometryIds}&geometriesZoom={zoomLevel}
get
URL request example
https://api.tomtom.com/maps/orbis/places/additionalData.json?key={Your_API_Key}&apiVersion=1&geometries=00004631-3400-3c00-0000-0000673c4d2e,00004631-3400-3c00-0000-0000673c42fe
get
curl command request example
curl 'https://api.tomtom.com/maps/orbis/places/additionalData.json?key={Your_API_Key}&apiVersion=1&geometries=00004631-3400-3c00-0000-0000673c4d2e,00004631-3400-3c00-0000-0000673c42fe'

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 parametersDescription

baseURL
string

Base URL for calling the API.
Value: api.tomtom.com

ext
string

The response format of the API request. The valid response format is JSON.
Value: json

geometries
string

Comma-separated list of geometry Ids, previously retrieved from a Search request.
Value: Comma-separated list of geometry Ids.
Maximum number of Ids: 20

key
string

An API Key valid for the requested service.
Value: Your valid API Key.

Optional parametersDescription

apiVersion
string

Service version. If the TomTom-Api-Version header is not present the apiVersion parameter is required.
Value: A service version value. The current value is 1.

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.

Table 1: Precision per zoom level

ValuePrecisionArea
0156 kmWhole world
178 km-
239 km-
319 km-
410 kmContinent
55 km-
62.5 km-
71.2 km-
8600 m-
9300 m 
10150 mCountry
1175 m-
1240 m-
1320 m-
1410 mVillage or town
155 m-
162.5 m-
171.2 mSmall road
180.6 m-
190.3 m-
200.15 m-
210.075 m-
220.0375 m-

Request headers

Optional headersDescription
TomTom-Api-Version

Service version. If the apiVersion parameter is not present the TomTom-Api-Version header is required.
Value: A service version value. The current value is 1.

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: An entity tag.
Example: F13887B89265DBD6F8E38C3A96F21EF0

Tracking-ID

Specifies an identifier for the request. It can be used to trace a call.

  • The value must match the regular expression '^[a-zA-Z0-9-]{1,100}$'.
  • An example of the format that matches this regular expression is a UUID: (e.g., 9ac68072-c7a4-11e8-a8d5-f2801f1b9fd1).
  • For details check RFC 4122.
  • If specified, it is replicated in the Tracking-ID response header.
  • It is only meant to be used for support and does not involve tracking of you or your users in any form.

Value: An identifier for the request.

Response data

Response body

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

1{
2  "additionalData": [
3    {
4      "providerID": "00004145-3100-3c00-1110-000023c34641",
5      "error": "Requested geometry not found"
6    },
7    {
8      "providerID": "00004145-3100-3c00-0000-000023c34645",
9      "geometryData": {
10        "type": "FeatureCollection",
11        "features": [
12          {
13            "type": "Feature",
14            "properties": {},
15            "geometry": {
16              "type": "Polygon",
17              "coordinates": [
18                [
19                  [-58.618436, -34.546888],
20                  [-58.618162, -34.547092],
21                  [-58.617562, -34.547538],
22                  [-58.616396, -34.548406],
23                  [-58.615583, -34.549011],
24                  [-58.612135, -34.5516584],
25                  [-58.6114201, -34.5526017],
26                  [-58.6108784, -34.5530107],
27                  [-58.6105212, -34.5532873],
28                  [-58.6098298, -34.5537771],
29                  [-58.609559, -34.553973],
30                  [-58.608954, -34.5544455],
31                  [-58.6086543, -34.5546817],
32                  [-58.607888, -34.5552463],
33                  [-58.6077382, -34.5553731],
34                  [-58.6068163, -34.5561048],
35                  [-58.6060671, -34.5566521],
36                  [-58.6053463, -34.5571967],
37                  [-58.6045748, -34.5577815],
38                  [-58.6039179, -34.5582827],
39                  [-58.6037623, -34.5584037],
40                  [-58.6031631, -34.558905],
41                  [-58.6028692, -34.5591125],
42                  [-58.618436, -34.546888]
43                ]
44              ]
45            },
46            "id": "00004145-3100-3c00-0000-000023c34645"
47          }
48        ]
49      }
50    }
51  ]
52}

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
FieldDescription

additionalData
array

Root array element for actual additional data.
An array of item objects.

item object
FieldDescription

providerID
string

ID of the returned entity.

error
string

Reason for the failure to obtain data for this provider.

geometryData
object

Geometry data. Only present if an "error" is not present.
GeoJSON

Response codes

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

CodeMeaning & 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

Forbidden: Possible causes include:

  • Service requires SSL
  • Not authorized
  • Rate or volume limit exceeded
  • Unknown referer
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.

429

Too Many Requests: The API Key is over QPS (Queries per second).

5xx

Server Error: The service was unable to process your request. Contact support to resolve the issue.

Response headers

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

HeaderDescription
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"

Tracking-ID

An identifier for the request. If the Tracking-ID header was specified, it is replicated in the response. Otherwise, it is generated automatically by the service. It is only meant to be used for support and does not involve tracking of you or your users in any form.
Value: An identifier for the request.

Error response

Error response example (JSON)
1{
2  "message": "Missing parameter 'parameterName'",
3  "detailedError": {
4    "code": "MissingParameter",
5    "message": "Missing required parameter 'parameterName'."
6  },
7  "httpStatusCode": "400"
8}

Error response fields

Primary fields
FieldDescription

message
string

A human-readable description of the error.

detailedError
object

Detailed information about the error.
detailedError object

detailedError object
FieldDescription

code
string

One of a server-defined set of error codes.

message
string

A human-readable description of the error code. It is intended as an aid to developers and is not suitable for exposure to end users.