Synchronous Batch

Service version: 2
Last edit: 2022.08.15

Purpose

This endpoint allows the submission of a new batch for synchronous processing. It responds with a batch processing result or an HTTP 408 request timeout error, if the processing time exceeds 60 seconds.

Request data

HTTPS method: POST

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.

URL format

POST
Request URL
https://{baseURL}/search/{versionNumber}/batch/sync.{outputFormat}?key={Your_API_Key}

Example

POST
Example request URL
https://api.tomtom.com/search/2/batch/sync.xml?key={Your_API_Key}

curl command format

POST
Request curl command
curl -X POST 'https://{baseURL}/search/{versionNumber}/batch/sync.{outputFormat}?key={Your_API_Key}'

Request parameters

The following table describes the request parameters.

  • Required parameters must be used or the call will fail.
  • Optional parameters may be used.
  • The order of request parameters is not important.

Note: There are no optional parameters in this endpoint.

Required parametersDescription
baseURL
string
Base URL for calling the API.
Values:
versionNumber
string
Service version.
Value: The current value is 2.
key
string
An API Key valid for the requested service.
Value: Your valid API Key.
outputFormat
string
The content type of the response structure.
Default value: xml
Other value: json

Request headers

The following table describes HTTP request headers of particular interest to Batch Search service clients.

Required headersDescription
Content-TypeSpecifies the MIME type of the body of the request.
Values: application/xml and application/json
Optional headersDescription
Accept-EncodingShould contain list of encodings acceptable by the client. Usually used to demand a compressed response.
Value: gzip
Tracking-IDSpecifies 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 format that matches this regular expression is 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.

Supported Search API suite endpoints

A list of Search API suite endpoints supported by the Batch Search service can be found below. For details regarding particular API usage, consult the following respective API documentation pages:

POST body

The POST body of a batch request should contain a set of items which will be used to execute requests to supported endpoints of the Search API suite. Each batch request can contain items corresponding to multiple supported endpoints of the Search API suite. For each endpoint, the same body structure applies and specific parameters of each endpoint are expected to go into query elements.

POST
Request POST body - XML
1<?xml version="1.0" encoding="UTF-8"?>
2<batchRequest>
3 <batchItems>
4 <batchItem>
5 <query>...</query>
6 </batchItem>
7 ...
8 <batchItem>
9 <query>...</query>
10 <post>...</post>
11 </batchItem>
12 </batchItems>
13</batchRequest>
POST
Request POST body - JSON
1{
2 "batchItems": [
3 {"query": "..."},
4 ...
5 {
6 "query": "...",
7 "post": {...}
8 }
9 ]
10}

POST body fields

FieldDescription
batchRequestRoot element of the request.
batchItemsA set of batch items. The maximum number of batch items for a Synchronous API is 100.
batchItemA single batch item.
queryA string used to build a request to one of the supported endpoints of the Search API suite. It is a partial URL without protocol, base URL, service version, and API Key. The output format must match the outputFormat parameter of the batch request. If a batch contains any Additional Data service item, the outputFormat parameter value must be set to json as the Additional Data service does not support the XML response format. A query must be properly URL-encoded. For example, a Fuzzy Search query "Lodz, Mochnackiego 15/19" should be written as follows (XML format): <query>/search/Lodz%2C%20Mochnackiego%2015%2F19</query>. A sample online URL encoder can be found at: URL Encoder.

When posting XML to the Batch Search service, the <query> element values must be valid XML (e.g., the "&" character must be replaced by the predefined XML entity "&amp;"). More information is in the List of XML character entity references. When posting JSON to the Batch Search service the <query> string values must be properly escaped. For example, the " (double-quote) character should be escaped with a \ (back-slash). More information is available in RFC 7159.
post
Contains data that is sent to the Geometry Search or Along Route Search services using the HTTP POST method. These services accept POST data only in JSON format. For batch submissions in XML format, the <post> element's value must also be an appropriate JSON object. A JSON object provided in a XML <post> element must be valid XML, i.e., it has to be properly XML escaped or wrapped in a CDATA section if necessary.

POST body examples

Mixed endpoint examples
POST
Request POST body example - XML
1<?xml version="1.0" encoding="utf-8"?>
2<batchRequest>
3 <batchItems>
4 <batchItem>
5 <query>/poiSearch/rembrandt museum.xml</query>
6 </batchItem>
7 <batchItem>
8 <query>/geometrySearch/restaurant.xml?geometryList=[{"type":"CIRCLE","position":"51.5123443,-0.0909851","radius":1000}]</query>
9 </batchItem>
10 <batchItem>
11 <query>/geometrySearch/pizza.xml</query>
12 <post>
13 {
14 "geometryList":[
15 {
16 "type": "CIRCLE",
17 "position": "51.5123443,-0.0909851",
18 "radius": 1000
19 }
20 ]
21 }
22 </post>
23 </batchItem>
24 <batchItem>
25 <query>/searchAlongRoute/restaurant.xml?maxDetourTime=300</query>
26 <post>
27 {
28 "route": {
29 "points": [
30 {
31 "lat": 37.7524152343544,
32 "lon": -122.43576049804686
33 },
34 {
35 "lat": 37.70660472542312,
36 "lon": -122.43301391601562
37 },
38 {
39 "lat": 37.712059855877314,
40 "lon": -122.36434936523438
41 },
42 {
43 "lat": 37.75350561243041,
44 "lon": -122.37396240234374
45 }
46 ]
47 }
48 }
49 </post>
50 </batchItem>
51 <batchItem>
52 <query>/reverseGeocode/crossStreet/52.4781801,4.8884868.xml</query>
53 </batchItem>
54 <batchItem>
55 <query>/search/lodz.xml?limit=10&amp;idxSet=POI,PAD,Str,Xstr,Geo,Addr</query>
56 </batchItem>
57 </batchItems>
58</batchRequest>
POST
Request POST body example - JSON
1{
2 "batchItems": [
3 {"query": "/poiSearch/rembrandt museum.json"},
4 {"query": "/geometrySearch/parking.json?geometryList=[{\"type\":\"CIRCLE\",\"position\":\"51.5123443,-0.0909851\",\"radius\":1000}]"},
5 {
6 "query": "/geometrySearch/pizza.json",
7 "post": {
8 "geometryList":[
9 {
10 "type": "CIRCLE",
11 "position": "51.5123443,-0.0909851",
12 "radius": 1000
13 }
14 ]
15 }
16 },
17 {
18 "query": "/searchAlongRoute/restaurant.json?maxDetourTime=300",
19 "post": {
20 "route": {
21 "points": [
22 {
23 "lat": 37.7524152,
24 "lon": -122.4357604
25 },
26 {
27 "lat": 37.7066047,
28 "lon": -122.4330139
29 },
30 {
31 "lat": 37.7120598,
32 "lon": -122.3643493
33 },
34 {
35 "lat": 37.7535056,
36 "lon": -122.3739624
37 }
38 ]
39 }
40 }
41 },
42 {"query": "/reverseGeocode/crossStreet/52.4829893,4.9247074.json"},
43 {"query": "/search/lodz.json?limit=10&idxSet=POI,PAD,Str,Xstr,Geo,Addr&maxFuzzyLevel=2"}
44 ]
45}
Fuzzy Search examples
POST
Request POST body example - XML
1<?xml version="1.0" encoding="utf-8"?>
2<batchRequest>
3 <batchItems>
4 <batchItem>
5 <query>/search/lodz.xml?limit=10&amp;idxSet=POI,PAD,Str,Xstr,Geo,Addr</query>
6 </batchItem>
7 <batchItem>
8 <query>/search/wroclaw.xml?limit=10&amp;idxSet=POI,PAD,Str,Xstr,Geo,Addr</query>
9 </batchItem>
10 <batchItem>
11 <query>/search/berlin.xml?limit=10&amp;idxSet=POI,PAD,Str,Xstr,Geo,Addr</query>
12 </batchItem>
13 </batchItems>
14</batchRequest>
POST
Request POST body example - JSON
1{
2 "batchItems": [
3 {"query": "/search/lodz.json?limit=10&idxSet=POI,PAD,Str,Xstr,Geo,Addr"},
4 {"query": "/search/wroclaw.json?limit=10&idxSet=POI,PAD,Str,Xstr,Geo,Addr"},
5 {"query": "/search/berlin.json?limit=10&idxSet=POI,PAD,Str,Xstr,Geo,Addr"}
6 ]
7}
POI Search examples
POST
Request POST body example - XML
1
2<?xml version="1.0" encoding="utf-8"?>
3<batchRequest>
4 <batchItems>
5 <batchItem>
6 <query>/poiSearch/rembrandt museum.xml</query>
7 </batchItem>
8 <batchItem>
9 <query>/poiSearch/big ben.xml</query>
10 </batchItem>
11 <batchItem>
12 <query>/poiSearch/colosseo.xml</query>
13 </batchItem>
14 </batchItems>
15</batchRequest>
POST
Request POST body example - JSON
1{
2 "batchItems": [
3 {"query": "/poiSearch/rembrandt museum.json"},
4 {"query": "/poiSearch/big ben.json"},
5 {"query": "/poiSearch/colosseo.json"}
6 ]
7}
Category Search examples
POST
Request POST body example - XML
1<?xml version="1.0" encoding="utf-8"?>
2<batchRequest>
3 <batchItems>
4 <batchItem>
5 <query>/categorySearch/airport.xml?lat=52.229404&amp;lon=21.011422</query>
6 </batchItem>
7 <batchItem>
8 <query>/categorySearch/restaurant.xml?lat=38.925518&amp;lon=76.990957</query>
9 </batchItem>
10 <batchItem>
11 <query>/categorySearch/hotel.xml?lat=34.016308&amp;lon=-118.277123</query>
12 </batchItem>
13 </batchItems>
14</batchRequest>
POST
Request POST body example - JSON
1{
2 "batchItems": [
3 {"query": "/categorySearch/airport.json?lat=52.229404&lon=21.011422"},
4 {"query": "/categorySearch/restaurant.json?lat=38.925518&lon=76.990957"},
5 {"query": "/categorySearch/hotel.json?lat=34.016308&lon=-118.277123"}
6 ]
7}
Geometry Search examples
POST
Request POST body example - XML
1<?xml version="1.0" encoding="utf-8"?>
2<batchRequest>
3 <batchItems>
4 <batchItem>
5 <query>/geometrySearch/restaurant.xml?geometryList=[{"type":"CIRCLE","position":"51.5123443,-0.0909851","radius":1000}]</query>
6 </batchItem>
7 <batchItem>
8 <query>/geometrySearch/pizza.xml</query>
9 <post>
10 {
11 "geometryList":[
12 {
13 "type": "CIRCLE",
14 "position": "51.5123443,-0.0909851",
15 "radius": 1000
16 }
17 ]
18 }
19 </post>
20 </batchItem>
21 </batchItems>
22</batchRequest>
POST
Request POST body example - JSON
1{
2 "batchItems": [
3 {"query": "/geometrySearch/parking.json?geometryList=[{\"type\":\"CIRCLE\",\"position\":\"51.5123443,-0.0909851\",\"radius\":1000}]"},
4 {
5 "query": "/geometrySearch/pizza.json",
6 "post": {
7 "geometryList":[
8 {
9 "type": "CIRCLE",
10 "position": "51.5123443,-0.0909851",
11 "radius": 1000
12 }
13 ]
14 }
15 }
16 ]
17}
Nearby Search examples
POST
Request POST body example - XML
1<?xml version="1.0" encoding="utf-8"?>
2<batchRequest>
3 <batchItems>
4 <batchItem>
5 <query>/nearbySearch/.xml?lat=40.702594&amp;lon=-74.045358&amp;radius=2000</query>
6 </batchItem>
7 <batchItem>
8 <query>/nearbySearch/.xml?lat=41.774831&amp;lon=-87.771554&amp;radius=2000</query>
9 </batchItem>
10 <batchItem>
11 <query>/nearbySearch/.xml?lat=48.141307&amp;lon=17.117647&amp;radius=2000</query>
12 </batchItem>
13 </batchItems>
14</batchRequest>
POST
Request POST body example - JSON
1{
2 "batchItems": [
3 {"query": "/nearbySearch/.json?lat=40.702594&lon=-74.045358&radius=2000"},
4 {"query": "/nearbySearch/.json?lat=41.774831&lon=-87.771554&radius=2000"},
5 {"query": "/nearbySearch/.json?lat=48.141307&lon=17.117647&radius=2000"}
6 ]
7}
Along Route Search examples
POST
Request POST body example - XML
1<?xml version="1.0" encoding="utf-8"?>
2<batchRequest>
3 <batchItems>
4 <batchItem>
5 <query>/searchAlongRoute/restaurant.xml?maxDetourTime=300</query>
6 <post>
7 {
8 "route": {
9 "points": [
10 {
11 "lat": 37.7524152343544,
12 "lon": -122.43576049804686
13 },
14 {
15 "lat": 37.70660472542312,
16 "lon": -122.43301391601562
17 },
18 {
19 "lat": 37.712059855877314,
20 "lon": -122.36434936523438
21 },
22 {
23 "lat": 37.75350561243041,
24 "lon": -122.37396240234374
25 }
26 ]
27 }
28 }
29 </post>
30 </batchItem>
31 <batchItem>
32 <query>/searchAlongRoute/restaurant.xml?maxDetourTime=300</query>
33 <post>
34 {
35 "route": {
36 "points": [
37 {
38 "lat": 48.19871,
39 "lon": 16.36319
40 },
41 {
42 "lat": 48.19843,
43 "lon": 16.36262
44 },
45 {
46 "lat": 48.19824,
47 "lon": 16.36226
48 },
49 {
50 "lat": 48.19788,
51 "lon": 16.3615
52 }
53 ]
54 }
55 }
56 </post>
57 </batchItem>
58 </batchItems>
59</batchRequest>
POST
Request POST body example - JSON
1{
2 "batchItems": [
3 {
4 "query": "/searchAlongRoute/restaurant.json?maxDetourTime=300",
5 "post": {
6 "route": {
7 "points": [
8 {
9 "lat": 37.7524152,
10 "lon": -122.4357604
11 },
12 {
13 "lat": 37.7066047,
14 "lon": -122.4330139
15 },
16 {
17 "lat": 37.7120598,
18 "lon": -122.3643493
19 },
20 {
21 "lat": 37.7535056,
22 "lon": -122.3739624
23 }
24 ]
25 }
26 }
27 },
28 {
29 "query": "/searchAlongRoute/restaurant.json?maxDetourTime=300",
30 "post": {
31 "route": {
32 "points": [
33 {
34 "lat": 48.19871,
35 "lon": 16.36319
36 },
37 {
38 "lat": 48.19843,
39 "lon": 16.36262
40 },
41 {
42 "lat": 48.19824,
43 "lon": 16.36226
44 },
45 {
46 "lat": 48.19788,
47 "lon": 16.3615
48 }
49 ]
50 }
51 }
52 }
53 ]
54}
Geocode examples
POST
Request POST body example - XML
1<?xml version="1.0" encoding="utf-8"?>
2<batchRequest>
3 <batchItems>
4 <batchItem>
5 <query>/geocode/tower bridge.xml</query>
6 </batchItem>
7 <batchItem>
8 <query>/geocode/new york.xml</query>
9 </batchItem>
10 <batchItem>
11 <query>/geocode/amsterdam.xml</query>
12 </batchItem>
13 </batchItems>
14</batchRequest>
POST
Request POST body example - JSON
1{
2 "batchItems": [
3 {"query": "/geocode/tower bridge.json"},
4 {"query": "/geocode/new york.json"},
5 {"query": "/geocode/amsterdam.json"}
6 ]
7}
Structured Geocode examples
POST
Request POST body example - XML
1<?xml version="1.0" encoding="utf-8"?>
2<batchRequest>
3 <batchItems>
4 <batchItem>
5 <query>/structuredGeocode.xml?countryCode=FR&amp;municipality=Paris&amp;streetName=Avenue de Suffren&amp;streetNumber=70</query>
6 </batchItem>
7 <batchItem>
8 <query>/structuredGeocode.xml?countryCode=ES&amp;municipality=Madrid&amp;streetName=Calle Mariblanca&amp;streetNumber=25</query>
9 </batchItem>
10 </batchItems>
11</batchRequest>
POST
Request POST body example - JSON
1{
2 "batchItems": [
3 {"query": "/structuredGeocode.json?countryCode=FR&municipality=Paris&streetName=Avenue de Suffren&streetNumber=70"},
4 {"query": "/structuredGeocode.json?countryCode=ES&municipality=Madrid&streetName=Calle Mariblanca&streetNumber=25"}
5 ]
6}
Reverse Geocode examples
POST
Request POST body example - XML
1<?xml version="1.0" encoding="utf-8"?>
2<batchRequest>
3 <batchItems>
4 <batchItem>
5 <query>/reverseGeocode/48.203233,16.360454.xml</query>
6 </batchItem>
7 <batchItem>
8 <query>/reverseGeocode/-26.202878,28.033040.xml</query>
9 </batchItem>
10 <batchItem>
11 <query>/reverseGeocode/12.975469,77.597284.xml</query>
12 </batchItem>
13 </batchItems>
14</batchRequest>
POST
Request POST body example - JSON
1{
2 "batchItems": [
3 {"query": "/reverseGeocode/48.203233,16.360454.json"},
4 {"query": "/reverseGeocode/-26.202878,28.033040.json"},
5 {"query": "/reverseGeocode/12.975469,77.597284.json"}
6 ]
7}
CrossStreet lookup examples
POST
Request POST body example - XML
1<?xml version="1.0" encoding="utf-8"?>
2<batchRequest>
3 <batchItems>
4 <batchItem>
5 <query>/reverseGeocode/crossStreet/52.4781801,4.8884868.xml</query>
6 </batchItem>
7 <batchItem>
8 <query>/reverseGeocode/crossStreet/12.977194,77.608367.xml</query>
9 </batchItem>
10 <batchItem>
11 <query>/reverseGeocode/crossStreet/21.130272,79.063060.xml</query>
12 </batchItem>
13 </batchItems>
14</batchRequest>
POST
Request POST body example - JSON
1{
2 "batchItems": [
3 {"query": "/reverseGeocode/crossStreet/52.4781801,4.8884868.json"},
4 {"query": "/reverseGeocode/crossStreet/12.977194,77.608367.json"},
5 {"query": "/reverseGeocode/crossStreet/21.130272,79.063060.json"}
6 ]
7}
Additional Data examples
POST
Request POST body example - XML
1<?xml version="1.0" encoding="utf-8"?>
2<batchRequest>
3 <batchItems>
4 <batchItem>
5 <query>/additionalData.json?geometries=00004631-3400-3c00-0000-0000673c4d2e</query>
6 </batchItem>
7 <batchItem>
8 <query>/additionalData.json?geometries=00004631-3400-3c00-0000-0000673c42fe</query>
9 </batchItem>
10 </batchItems>
11</batchRequest>

The above POST body contains example geometry ID values. Proper geometry ID values can be retrieved from a Search request.

POST
Request POST body example - JSON
1{
2 "batchItems": [
3 {"query": "/additionalData.json?geometries=00004631-3400-3c00-0000-0000673c4d2e"},
4 {"query": "/additionalData.json?geometries=00004631-3400-3c00-0000-0000673c42fe"}
5 ]
6}

The above POST body contains example geometry ID values. Proper geometry ID values can be retrieved from a Search request.

EV Charging Stations Availability examples
POST
Request POST body example - XML
1 <?xml version="1.0" encoding="utf-8"?>
2 <batchRequest>
3 <batchItems>
4 <batchItem>
5 <query>/chargingAvailability.xml?chargingAvailability=00112233-4455-6677-8899-aabbccddeeff</query>
6 </batchItem>
7 <batchItem>
8 <query>/chargingAvailability.xml?chargingAvailability=00112233-4455-6677-8899-001122334455</query>
9 </batchItem>
10 </batchItems>
11 </batchRequest>

The above POST body contains example charging availability ID values. Proper charging availability ID values can be retrieved from a Search request.

POST
Request POST body example - JSON
1 {
2 "batchItems": [
3 {"query": "/chargingAvailability.json?chargingAvailability=00112233-4455-6677-8899-aabbccddeeff"},
4 {"query": "/chargingAvailability.json?chargingAvailability=00112233-4455-6677-8899-001122334455"}
5 ]
6 }

The above POST body contains example charging availability ID values. Proper charging availability ID values can be retrieved from a Search request.


Response data

HTTP status codes

CodeMeaning & possible causes
200OK: The batch job has completed. Results are streamed to client.
400Bad Request: Missing required parameters, exceeded maximum number of batch items, or parameters did not pass validation.
403Forbidden: The API Key is missing, inactive, invalid, not entitled to use Batch Search API over QPS (Queries per second) or over QPD (Queries per day). Can also occur when using HTTP instead of HTTPS.
404Not Found: The requested resource could not be found, but it may be available again in the future.
405Method Not Allowed: The client used an HTTP method other than POST.
408Request timeout: The request sent to the server took longer than it was prepared to wait.
414Requested URI is too long: Indicates that the URI requested by the client is longer than the server is willing to interpret.
429Too Many Requests: The API Key is over QPS (Queries per second).
500An error occurred while processing the request. Please try again later.
502Internal network connectivity issue. Please try again later.
503Service currently unavailable. Please try again later.
504Internal network connectivity issue or a request that has taken too long to complete. Please try again later.
596Service not found. Request contains an incorrect FQDN and/or path.

Response headers

The following table lists HTTP response headers of particular interest to the service clients.

HeaderDescription
Access-Control-Expose-HeadersA comma separated list of HTTP header names that browsers are allowed to access.
Value: Content-Length
Access-Control-Allow-OriginA header instructing browsers to allow customer websites to contact the Batch Search service.
Value: *
Content-EncodingThe Batch Search service applies gzip compression to the responses if it is requested by the client with the Accept-Encoding header.
Value: gzip
Content-TypeThe format of the response as chosen by the client (see the contentType request parameter).
Values: application/xml;charset=utf-8 and application/json;charset=utf-8.
Tracking-IDAn 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.

Successful response structure

Each Batch response consists of one or more XML <batchItem> elements which correspond sequentially with the <batchItem> elements in the request. Each <batchItem> element contains a successful response from the invoked Search API endpoint or a status code indicating why the batch item failed.

Successful response example - XML
1<?xml version="1.0" encoding="UTF-8"?>
2<batchResponse xmlns="http://api.tomtom.com/batch" formatVersion="0.0.1">
3 <batchItems>
4 <batchItem>
5 <statusCode>...</statusCode>
6 <response>...</response>
7 </batchItem>
8 ...
9 <batchItem>
10 <statusCode>...</statusCode>
11 <response>...</response>
12 </batchItem>
13 </batchItems>
14 <summary>
15 <successfulRequests>...</successfulRequests>
16 <totalRequests>...</totalRequests>
17 </summary>
18</batchResponse>
Successful response example - JSON
1{
2 "formatVersion": "0.0.1",
3 "batchItems": [
4 {
5 "statusCode": ...,
6 "response": {...}
7 },
8 ...,
9 {
10 "statusCode": ...,
11 "response": {...}
12 }
13 ],
14 "summary": {
15 "successfulRequests": ...,
16 "totalRequests": ...
17 }
18}

Successful response fields

FieldDescription
batchResponse
object
Root element of the batch response.
successfulRequests
string
Number of successful batch item requests.
totalRequests
string
Total number of items in batch request.
batchItems
array
A set of batch items processing results.
batchItem
object
Contains the results of processing a single batch item.
statusCode
string
Status code of a response from the underlying Search API endpoint for a given batch item.
response
object
Content of the response from the underlying Search API endpoint for a given batch item query. The full response content will be included both in case of success and failure. If the underlying service's response content type does not match the requested content type, then the response will be wrapped to fit the requested content type.
summary
object
Summary of the batch request.

Successful response examples

The following code blocks in XML and JSON contain a complete example of a response to a batch request for three queries to the Fuzzy Search endpoint. Two the batch items were successfully executed resulting in a HTTP 200 response, while one failed with a HTTP 400 error due to the use of an incorrect query parameter. Note that batch success indicates that each batch item was executed, not that each batch item executed successfully.

XML response example
1<?xml version="1.0" encoding="UTF-8"?>
2<batchResponse xmlns="http://api.tomtom.com/batch" formatVersion="0.0.1">
3 <batchItems>
4 <batchItem>
5 <statusCode>200</statusCode>
6 <response>
7 <response>
8 <summary>
9 <query>lodz</query>
10 <queryType>NON_NEAR</queryType>
11 <queryTime>95</queryTime>
12 <numResults>1</numResults>
13 <offset>0</offset>
14 <totalResults>363</totalResults>
15 <fuzzyLevel>1</fuzzyLevel>
16 </summary>
17 <results>
18 <item>
19 <type>Geography</type>
20 <id>PL/GEO/p0/4455</id>
21 <score>5.98</score>
22 <info>search:decarta:ta:616013002038177-PL</info>
23 <address>
24 <municipality>Lodz</municipality>
25 <countrySecondarySubdivision>Łódź</countrySecondarySubdivision>
26 <countrySubdivision>Łódzkie</countrySubdivision>
27 <countryCode>PL</countryCode>
28 <country>Poland</country>
29 <countryCodeISO3>POL</countryCodeISO3>
30 <freeformAddress>Lodz</freeformAddress>
31 </address>
32 <position>
33 <lat>51.75905</lat>
34 <lon>19.4586</lon>
35 </position>
36 </item>
37 </results>
38 </response>
39 </response>
40 </batchItem>
41 <batchItem>
42 <statusCode>200</statusCode>
43 <response>
44 <response>
45 <summary>
46 <query>restaurant amsterdam</query>
47 <queryType>NON_NEAR</queryType>
48 <queryTime>186</queryTime>
49 <numResults>3</numResults>
50 <offset>0</offset>
51 <totalResults>3731</totalResults>
52 <fuzzyLevel>1</fuzzyLevel>
53 </summary>
54 <results>
55 <item>
56 <type>POI</type>
57 <id>AU/POI/p0/261806</id>
58 <score>7.5</score>
59 <info>search:decarta:ta:036001105620466-AU</info>
60 <poi>
61 <name>Nieuw Amsterdam</name>
62 <categories>
63 <item>restaurant</item>
64 </categories>
65 <classifications>
66 <item>
67 <code>RESTAURANT</code>
68 <names>
69 <item>
70 <nameLocale>en-US</nameLocale>
71 <name>restaurant</name>
72 </item>
73 </names>
74 </item>
75 </classifications>
76 </poi>
77 <address>
78 <streetNumber>112</streetNumber>
79 <streetName>Hardware Street</streetName>
80 <municipalitySubdivision>Melbourne CBD</municipalitySubdivision>
81 <municipality>Melbourne</municipality>
82 <countrySecondarySubdivision>Melbourne</countrySecondarySubdivision>
83 <countrySubdivision>Vic</countrySubdivision>
84 <postalCode>3000</postalCode>
85 <countryCode>AU</countryCode>
86 <country>Australia</country>
87 <countryCodeISO3>AUS</countryCodeISO3>
88 <freeformAddress>Hardware Street 112, Melbourne CBD Melbourne, Vic, 3000</freeformAddress>
89 </address>
90 <position>
91 <lat>-37.8123</lat>
92 <lon>144.96068</lon>
93 </position>
94 </item>
95 <item>
96 <type>POI</type>
97 <id>BE/POI/p0/61115</id>
98 <score>7.5</score>
99 <info>review:decarta:ta:056001000066087-BE</info>
100 <poi>
101 <name>Borse van Amsterdam</name>
102 <url>www.borsevanamsterdam.be</url>
103 <categories>
104 <item>belgian</item>
105 <item>important tourist attraction</item>
106 <item>restaurant</item>
107 </categories>
108 <classifications>
109 <item>
110 <code>RESTAURANT</code>
111 <names>
112 <item>
113 <nameLocale>en-US</nameLocale>
114 <name>belgian</name>
115 </item>
116 <item>
117 <nameLocale>en-US</nameLocale>
118 <name>restaurant</name>
119 </item>
120 </names>
121 </item>
122 <item>
123 <code>IMPORTANT_TOURIST_ATTRACTION</code>
124 <names>
125 <item>
126 <nameLocale>en-US</nameLocale>
127 <name>important tourist attraction</name>
128 </item>
129 </names>
130 </item>
131 </classifications>
132 </poi>
133 <address>
134 <streetNumber>26</streetNumber>
135 <streetName>Grote Markt</streetName>
136 <municipalitySubdivision>Aalst</municipalitySubdivision>
137 <municipality>Aalst</municipality>
138 <countrySecondarySubdivision>Oost-Vlaanderen</countrySecondarySubdivision>
139 <countryTertiarySubdivision>Aalst</countryTertiarySubdivision>
140 <countrySubdivision>Vlaams Gewest</countrySubdivision>
141 <postalCode>9300</postalCode>
142 <countryCode>BE</countryCode>
143 <country>Belgium</country>
144 <countryCodeISO3>BEL</countryCodeISO3>
145 <freeformAddress>Grote Markt 26, 9300 Aalst</freeformAddress>
146 </address>
147 <position>
148 <lat>50.93852</lat>
149 <lon>4.03821</lon>
150 </position>
151 </item>
152 <item>
153 <type>POI</type>
154 <id>BG/POI/p0/11627</id>
155 <score>7.5</score>
156 <info>search:decarta:ta:100009000014937-BG</info>
157 <poi>
158 <name>Amsterdam</name>
159 <phone>+(359)-(87)-8868962</phone>
160 <categories>
161 <item>restaurant</item>
162 </categories>
163 <classifications>
164 <item>
165 <code>RESTAURANT</code>
166 <names>
167 <item>
168 <nameLocale>en-US</nameLocale>
169 <name>restaurant</name>
170 </item>
171 </names>
172 </item>
173 </classifications>
174 </poi>
175 <address>
176 <streetNumber>10</streetNumber>
177 <streetName>улица К. Стоилов</streetName>
178 <municipalitySubdivision>Plovdiv</municipalitySubdivision>
179 <municipality>Пловдив</municipality>
180 <countrySecondarySubdivision>Пловдив</countrySecondarySubdivision>
181 <postalCode>4000</postalCode>
182 <countryCode>BG</countryCode>
183 <country>Bulgaria</country>
184 <countryCodeISO3>BGR</countryCodeISO3>
185 <freeformAddress>улица К. Стоилов 10, 4000 Plovdiv (Пловдив)</freeformAddress>
186 </address>
187 <position>
188 <lat>42.14805</lat>
189 <lon>24.7491</lon>
190 </position>
191 </item>
192 </results>
193 </response>
194 </response>
195 </batchItem>
196 <batchItem>
197 <statusCode>400</statusCode>
198 <response>
199 <response>
200 <errorText>Error parsing 'maxFuzzyLevel': 'asd' is not a valid integer</errorText>
201 <message>Error parsing 'maxFuzzyLevel': 'asd' is not a valid integer</message>
202 <httpStatusCode>400</httpStatusCode>
203 </response>
204 </response>
205 </batchItem>
206 </batchItems>
207 <summary>
208 <successfulRequests>2</successfulRequests>
209 <totalRequests>3</totalRequests>
210 </summary>
211</batchResponse>
JSON response example
1{
2 "formatVersion": "0.0.1",
3 "batchItems": [
4 {
5 "statusCode": 200,
6 "response": {
7 "summary": {
8 "query": "lodz",
9 "queryType": "NON_NEAR",
10 "queryTime": 101,
11 "numResults": 1,
12 "offset": 0,
13 "totalResults": 363,
14 "fuzzyLevel": 1
15 },
16 "results": [
17 {
18 "type": "Geography",
19 "id": "PL/GEO/p0/4455",
20 "score": 5.98,
21 "info": "search:decarta:ta:616013002038177-PL",
22 "address": {
23 "municipality": "Lodz",
24 "countrySecondarySubdivision": "Łódź",
25 "countrySubdivision": "Łódzkie",
26 "countryCode": "PL",
27 "country": "Poland",
28 "countryCodeISO3": "POL",
29 "freeformAddress": "Lodz"
30 },
31 "position": {
32 "lat": 51.75905,
33 "lon": 19.4586
34 }
35 }
36 ]
37 }
38 },
39 {
40 "statusCode": 200,
41 "response": {
42 "summary": {
43 "query": "restaurant amsterdam",
44 "queryType": "NON_NEAR",
45 "queryTime": 186,
46 "numResults": 3,
47 "offset": 0,
48 "totalResults": 3731,
49 "fuzzyLevel": 1
50 },
51 "results": [
52 {
53 "type": "POI",
54 "id": "AU/POI/p0/261806",
55 "score": 7.5,
56 "info": "search:decarta:ta:036001105620466-AU",
57 "poi": {
58 "name": "Nieuw Amsterdam",
59 "categories": [
60 "restaurant"
61 ],
62 "classifications": [
63 {
64 "code": "RESTAURANT",
65 "names": [
66 {
67 "nameLocale": "en-US",
68 "name": "restaurant"
69 }
70 ]
71 }
72 ]
73 },
74 "address": {
75 "streetNumber": "112",
76 "streetName": "Hardware Street",
77 "municipalitySubdivision": "Melbourne CBD",
78 "municipality": "Melbourne",
79 "countrySecondarySubdivision": "Melbourne",
80 "countrySubdivision": "Vic",
81 "postalCode": "3000",
82 "countryCode": "AU",
83 "country": "Australia",
84 "countryCodeISO3": "AUS",
85 "freeformAddress": "Hardware Street 112, Melbourne CBD Melbourne, Vic, 3000"
86 },
87 "position": {
88 "lat": -37.8123,
89 "lon": 144.96068
90 }
91 },
92 {
93 "type": "POI",
94 "id": "BE/POI/p0/61115",
95 "score": 7.5,
96 "info": "review:decarta:ta:056001000066087-BE",
97 "poi": {
98 "name": "Borse van Amsterdam",
99 "url": "www.borsevanamsterdam.be",
100 "categories": [
101 "belgian",
102 "important tourist attraction",
103 "restaurant"
104 ],
105 "classifications": [
106 {
107 "code": "RESTAURANT",
108 "names": [
109 {
110 "nameLocale": "en-US",
111 "name": "belgian"
112 },
113 {
114 "nameLocale": "en-US",
115 "name": "restaurant"
116 }
117 ]
118 },
119 {
120 "code": "IMPORTANT_TOURIST_ATTRACTION",
121 "names": [
122 {
123 "nameLocale": "en-US",
124 "name": "important tourist attraction"
125 }
126 ]
127 }
128 ]
129 },
130 "address": {
131 "streetNumber": "26",
132 "streetName": "Grote Markt",
133 "municipalitySubdivision": "Aalst",
134 "municipality": "Aalst",
135 "countrySecondarySubdivision": "Oost-Vlaanderen",
136 "countryTertiarySubdivision": "Aalst",
137 "countrySubdivision": "Vlaams Gewest",
138 "postalCode": "9300",
139 "countryCode": "BE",
140 "country": "Belgium",
141 "countryCodeISO3": "BEL",
142 "freeformAddress": "Grote Markt 26, 9300 Aalst"
143 },
144 "position": {
145 "lat": 50.93852,
146 "lon": 4.03821
147 }
148 },
149 {
150 "type": "POI",
151 "id": "BG/POI/p0/11627",
152 "score": 7.5,
153 "info": "search:decarta:ta:100009000014937-BG",
154 "poi": {
155 "name": "Amsterdam",
156 "phone": "+(359)-(87)-8868962",
157 "categories": [
158 "restaurant"
159 ],
160 "classifications": [
161 {
162 "code": "RESTAURANT",
163 "names": [
164 {
165 "nameLocale": "en-US",
166 "name": "restaurant"
167 }
168 ]
169 }
170 ]
171 },
172 "address": {
173 "streetNumber": "10",
174 "streetName": "улица К. Стоилов",
175 "municipalitySubdivision": "Plovdiv",
176 "municipality": "Пловдив",
177 "countrySecondarySubdivision": "Пловдив",
178 "postalCode": "4000",
179 "countryCode": "BG",
180 "country": "Bulgaria",
181 "countryCodeISO3": "BGR",
182 "freeformAddress": "улица К. Стоилов 10, 4000 Plovdiv (Пловдив)"
183 },
184 "position": {
185 "lat": 42.14805,
186 "lon": 24.7491
187 }
188 }
189 ]
190 }
191 },
192 {
193 "statusCode": 400,
194 "response": {
195 "errorText": "Error parsing 'maxFuzzyLevel': 'asd' is not a valid integer",
196 "message": "Error parsing 'maxFuzzyLevel': 'asd' is not a valid integer",
197 "httpStatusCode": 400
198 }
199 }
200 ],
201 "summary": {
202 "successfulRequests": 2,
203 "totalRequests": 3
204 }
205}

Other supported Search API suite responses

For details on a particular supported Search API suite endpoint's response structure, consult the respective API documentation pages available in the supported endpoints section.

Error response

The error response content type depends on the outputFormat parameter.

Error response example - XML
1 <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
2 <batchResponse xmlns="http://api.tomtom.com/batch" formatVersion="0.0.1">
3 <error description="Validation of batch item 1 failed. Batch response format (XML) does not match content type of batch item query."/>
4 <detailedError>
5 <code>BadRequest</code>
6 <message>Bad Request</message>
7 <details>
8 <detail>
9 <code>MalformedBody</code>
10 <message>Validation of batch item 1 failed. Batch response format (XML) does not match content type of batch item query.</message>
11 <target>postBody</target>
12 </detail>
13 </details>
14 </detailedError>
15 </batchResponse>
Error response example - JSON
1{
2 "formatVersion": "0.0.1",
3 "error": {
4 "description": "Validation of batch item 1 failed. Batch response format (JSON) does not match content type of batch item query."
5 },
6 "detailedError": {
7 "code": "BadRequest",
8 "message": "Bad Request",
9 "details": {
10 "code": "MalformedBody",
11 "message": "Validation of batch item 1 failed. Batch response format (JSON) does not match content type of batch item query",
12 "target": "postBody",
13 }
14 }
15 }

Error response fields

Primary fields
FieldDescription
formatVersion
string
Version of the batch error response format.
error
object
Simplified information about the error.
error object
detailedError
object
Detailed information about the error.
detailedError object
error object
FieldDescription
description
string
A human-readable description of the error. It is intended as an aid to developers and is not suitable for exposure to end users.
detailedError object
FieldDescription
code
string
One of the defined 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.
target
string
Optional.
Target of the particular error.
Values:
  • The name of the request parameter.
  • postBody
details
array
Optional.
An array of root causes (more detailed errors) that led to this error.
detailedError object
innerError
object
Optional.
A higher level of details about this error.
innerError object
innerError object
FieldDescription
code
string
One of the defined error codes.
message
string
Optional.
A human-readable representation of the error code. It is intended as an aid to developers and is not suitable for exposure to end users.
innerError
object
Optional. A higher level of details about this error.
innerError object

Error code hierarchy

List of predefined, hierarchical, human-readable error codes. Top level codes relate to HTTP error codes. They may be refined by error codes in details or innerError. Further levels of refinement are possible by nesting innerError inside innerError. In the future, the list may be extended with additional codes. The application must be ready for the occurrence of an unknown error code (e.g., by stopping error processing at the last understood level of detail).

Error codeDescription
BadArgumentOne of the request parameters was missing or did not pass validation. The target field contains the name of the related parameter.
Possible inner errors:
  • MissingRequiredParameter
  • InvalidParameterValue
  • IllegalParameter
BadRequestTop level code for requests which resulted in an HTTP 400 Bad Request.
Possible root causes: BadArgument and MalformedBody.
BatchRequestTimeoutTop level code for requests which resulted in an HTTP 408 Request Timeout. Calculating batch takes too long to complete using sync mode. Please recalculate using async mode.
IllegalParameterUnsupported request parameter was specified.
InvalidParameterValueThe value of one of the parameters is invalid.
InternalServerErrorTop level code for requests which resulted in a HTTP 500 Internal Server Error. The service cannot handle the request right now, an unexpected condition was encountered.
MalformedBodyPOST body has unexpected format.
MissingRequiredParameterOne of the required parameters was not provided.
NotFoundTop level code for requests which resulted in an HTTP 404 Not Found caused by providing an incorrect request path.
ServiceUnavailableTop level code for requests which resulted in an HTTP 503 Service Unavailable. The service cannot handle the request right now, this is certainly a temporary state.