Asynchronous Batch Download

Service version: 2
Last edit: 2022.09.26

Purpose

This endpoint fetches results of the Asynchronous Batch processing. It responds with HTTP 200 and the batch results assuming batch processing has completed, or HTTP 202 Accepted if the batch is still being processed. HTTP 202 "Accepted" will be sent after 120 seconds by default. This behavior can be overridden as needed by passing the waitTimeSeconds parameter with a desired value. The client should then retry the request by following the Location header.

An HTTP 200 response does not indicate that every batch item succeeded, but only that the batch calculation was completed. Detailed information about the success or failure of the individual requests within the batch is provided in the HTTP 200 response. The Batch Download endpoint GET request is a blocking long poll request.

Request data

HTTPS method: GET

For ease of viewing and identification:

  • Constants and parameters enclosed in curly brackets &#123 } 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 request format

https://{baseURL}/search/{versionNumber}/batch/{batchId}?key={Your_API_Key}&waitTimeSeconds={waitTimeSeconds}

URL request example

https://api.tomtom.com/search/2/batch/45e0909c-625a-4822-a060-8f7f88498c0e?key={Your_API_Key}

curl command request example

curl 'https://api.tomtom.com/search/2/batch/45e0909c-625a-4822-a060-8f7f88498c0e?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.

Required parameters

Description

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.

batchId
string

Unique id of the batch. Returned in the HTTP

Location

header of the Batch Submission response.


Value: A unique ID generated by the submission.

Optional parameters

Description

waitTimeSeconds
integer

Allows changing the maximum amount of time, in seconds, for which the client may have to wait for an Asynchronous Batch Download Response while the batch is being processed. If the batch processing completes during the given number of seconds, then the batch processing result is returned. Otherwise, if the batch is still processing, a HTTP 202 (Accepted) response is returned. The client should then retry the request by following the

Location

header. Please note that the provided waitTimeSeconds parameter and its value are passed to the

Locationresponse header as a part of the URI.
Default value: 120

Other values: It may be either 5..60 or 120.

Request headers

The following table describes HTTP request headers of particular interest to Batch Search service clients. Note: There are no required headers in this endpoint.

Optional headers

Description

Accept-Encoding

Should contain list of encodings acceptable by the client. Used to demand a compressed response.


Value: gzip

Accept

Indicates the format of the download error response (e.g., a batch with a provided batchId does not exist). For instance, if a client submitted a batch with an output format set to json and would like to get the download error response in the same format, the Accept header should be set to application/json. Otherwise the download error response will have the default format which is xml. Note: In case of a successful response, the Accept header value will not affect the batch response format.


Values: application/xml and application/json

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

Response data

HTTPS status codes

Code

Meaning & possible causes

200

OK: The batch job has completed. Results are streamed to the client.

202

Accepted: The request has been accepted for processing, but the processing has not been completed. A

Location

header is added to the response containing a link to retry later.

400

Bad Request: Missing required parameters, or parameters did not pass validation.

403

Forbidden: The API Key is missing, inactive, invalid, or not entitled to use Batch Search API over QPS (Queries per second) or over QPD (Queries per day). This can also occur when using HTTP instead of HTTPS.

404

Not Found: The requested resource could not be found, for example a batch with a provided batchId does not exist.

405

Method Not Allowed: The client used a 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.

429

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

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.

Response headers

Header

Description

Access-Control-Expose-Headers

A comma separated list of HTTP header names that browsers are allowed to access.


Value: Content-Length

Access-Control-Allow-Origin

A header instructing browsers to allow customer websites to contact the Batch Search service.


Value: *

Content-Encoding

The Batch Search service applies gzip compression to the responses if it is requested by the client with the Accept-Encoding header.


Value: gzip

Content-Type

The 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

Location

Indicates the location where the batch results can be downloaded. Available only if the response is HTTP 202.


Value: URI

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.

Successful response structure

Each batch response consists of one or more 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.

1<?xml version="1.0" encoding="utf-8"?>
2<batchResponse
3 xmlns="http://api.tomtom.com/batch" formatVersion="0.0.1">
4 <batchItems>
5 <batchItem>
6 <statusCode>...</statusCode>
7 <response>
8 ...
9 </response>
10 </batchItem>
11 ...
12 <batchItem>
13 <statusCode>...</statusCode>
14 <response>
15 ...
16 </response>
17 </batchItem>
18 </batchItems>
19 <summary>
20 <successfulRequests>...</successfulRequests>
21 <totalRequests>...</totalRequests>
22 </summary>
23</batchResponse>
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

Field

Description

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 results of processing of a single batch item.
statusCode
string

Status code of a response from the underlying

Search API

endpoint for given batch item.

response
object

Content of the response from the underlying

Search API

endpoint for 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 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 of 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.

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>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>
Successful response example - JSON
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": ["restaurant"],
60 "classifications": [
61 {
62 "code": "RESTAURANT",
63 "names": [
64 {
65 "nameLocale": "en-US",
66 "name": "restaurant"
67 }
68 ]
69 }
70 ]
71 },
72 "address": {
73 "streetNumber": "112",
74 "streetName": "Hardware Street",
75 "municipalitySubdivision": "Melbourne CBD",
76 "municipality": "Melbourne",
77 "countrySecondarySubdivision": "Melbourne",
78 "countrySubdivision": "Vic",
79 "postalCode": "3000",
80 "countryCode": "AU",
81 "country": "Australia",
82 "countryCodeISO3": "AUS",
83 "freeformAddress": "Hardware Street 112, Melbourne CBD Melbourne, Vic, 3000"
84 },
85 "position": {
86 "lat": -37.8123,
87 "lon": 144.96068
88 }
89 },
90 {
91 "type": "POI",
92 "id": "BE/POI/p0/61115",
93 "score": 7.5,
94 "info": "review:decarta:ta:056001000066087-BE",
95 "poi": {
96 "name": "Borse van Amsterdam",
97 "url": "www.borsevanamsterdam.be",
98 "categories": [
99 "belgian",
100 "important tourist attraction",
101 "restaurant"
102 ],
103 "classifications": [
104 {
105 "code": "RESTAURANT",
106 "names": [
107 {
108 "nameLocale": "en-US",
109 "name": "belgian"
110 },
111 {
112 "nameLocale": "en-US",
113 "name": "restaurant"
114 }
115 ]
116 },
117 {
118 "code": "IMPORTANT_TOURIST_ATTRACTION",
119 "names": [
120 {
121 "nameLocale": "en-US",
122 "name": "important tourist attraction"
123 }
124 ]
125 }
126 ]
127 },
128 "address": {
129 "streetNumber": "26",
130 "streetName": "Grote Markt",
131 "municipalitySubdivision": "Aalst",
132 "municipality": "Aalst",
133 "countrySecondarySubdivision": "Oost-Vlaanderen",
134 "countryTertiarySubdivision": "Aalst",
135 "countrySubdivision": "Vlaams Gewest",
136 "postalCode": "9300",
137 "countryCode": "BE",
138 "country": "Belgium",
139 "countryCodeISO3": "BEL",
140 "freeformAddress": "Grote Markt 26, 9300 Aalst"
141 },
142 "position": {
143 "lat": 50.93852,
144 "lon": 4.03821
145 }
146 },
147 {
148 "type": "POI",
149 "id": "BG/POI/p0/11627",
150 "score": 7.5,
151 "info": "search:decarta:ta:100009000014937-BG",
152 "poi": {
153 "name": "Amsterdam",
154 "phone": "+(359)-(87)-8868962",
155 "categories": ["restaurant"],
156 "classifications": [
157 {
158 "code": "RESTAURANT",
159 "names": [
160 {
161 "nameLocale": "en-US",
162 "name": "restaurant"
163 }
164 ]
165 }
166 ]
167 },
168 "address": {
169 "streetNumber": "10",
170 "streetName": "улица К. Стоилов",
171 "municipalitySubdivision": "Plovdiv",
172 "municipality": "Пловдив",
173 "countrySecondarySubdivision": "Пловдив",
174 "postalCode": "4000",
175 "countryCode": "BG",
176 "country": "Bulgaria",
177 "countryCodeISO3": "BGR",
178 "freeformAddress": "улица К. Стоилов 10, 4000 Plovdiv (Пловдив)"
179 },
180 "position": {
181 "lat": 42.14805,
182 "lon": 24.7491
183 }
184 }
185 ]
186 }
187 },
188 {
189 "statusCode": 400,
190 "response": {
191 "errorText": "Error parsing 'maxFuzzyLevel': 'asd' is not a valid integer",
192 "message": "Error parsing 'maxFuzzyLevel': 'asd' is not a valid integer",
193 "httpStatusCode": 400
194 }
195 }
196 ],
197 "summary": {
198 "successfulRequests": 2,
199 "totalRequests": 3
200 }
201}

Other supported Search API suite responses

For details on particular supported Search API suite endpoint's response structure, consult the following respective API documentation pages:

Other API endpoints support

Error response

The default error response format is XML. It may be changed by using the Accept header.

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="Batch not found for provided id."/>
4 <detailedError>
5 <code>BatchNotFound</code>
6 <message>Batch not found for provided id.</message>
7 </detailedError>
8</batchResponse>
1{
2 "formatVersion": "0.0.1",
3 "error": {
4 "description": "Batch not found for provided id."
5 },
6 "detailedError": {
7 "code": "BatchNotFound",
8 "message": "Batch not found for provided id."
9 }
10}

Error response fields

Primary fields

Field

Description
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

Field Description
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

Field Description
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

Field Description
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 code

Description

BadArgument

One of the request parameters did not pass validation. The target field contains the name of the related parameter.


Possible inner errors: InvalidParameterValue and ValueOutOfRange.

BatchNotFound

Top level code for requests which resulted in an HTTP 404 Not Found caused by requesting batchId which does not exist, or the batch being already expired.

InvalidParameterValueThe value of one of the parameters is invalid.
InternalServerError

Top level code for requests which resulted in an HTTP 500 Internal Server Error. The service cannot handle the request right now, an unexpected condition was encountered.

NotFound

Top level code for requests which resulted in an HTTP 404 Not Found caused by providing incorrect request path.

ServiceUnavailable

Top 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.

ValueOutOfRange

The value of one of the numeric parameters is out of the allowed range.