Additional Data
Service version: 2
Last edit: 2020.09.10
On this page
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.
Request data
HTTPS Method: GET
URL format
GET https://<baseURL>/search/<versionNumber>/additionalData.<ext>?key=<Your_API_Key>&geometries=<geometryIds>[&geometriesZoom=<zoomLevel>]
curl command format
curl '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 |
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 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 | - |
Request Headers
Optional headers | |
---|---|
Header | Description |
[If-None-Match] |
Provides the entity tag (ETag ) of the requested resource as last received by the client.
"F13887B89265DBD6F8E38C3A96F21EF0"
|
Tracking-ID string |
Specifies an identifier for the Request.
An identifier for the Request.
|
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"
}
]
}
}
]
}
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.
Response | |
---|---|
Field | Description |
additionalData[] array |
Root array element for actual additional data.
array of item{} objects
|
item{} object |
|
Field | Description |
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
|
HTTP Response codes
The following table contains Response codes signifying successful and failed requests to an API server.
Code | Meaning & possible causes |
---|---|
200 |
OK:
|
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:
|
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.
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 "
|
Tracking-ID |
An identifier for the Request.
An identifier for the Request.
|
Error Response
The error Response content type depends on the ext
parameter.
Error Response example (JSON)
{
"message":"Missing parameter 'parameterName'",
"detailedError":{
"code":"MissingParameter",
"message":"Missing required parameter 'parameterName'.",
},
"httpStatusCode":"400"
}
Error Response fields
Primary fields | |
---|---|
Field | Description |
message string |
A human-readable description of the error. |
detailedError object |
Detailed information about the error.detailedError{} object
|
detailedError{} object |
|
Field | Description |
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. |