Developer

Asynchronous batch download

Service version: 1
Last edit: 2022.10.01
TomTom Maps

Purpose

The asynchronous batch download endpoint fetches results of the asynchronous batch processing.

  • It responds with HTTP 200 and the batch results, assuming that batch processing has completed, or with HTTP 202 "Accepted" if the batch is still being processed.
  • HTTP 202 "Accepted" is 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 means that batch processing has completed, but it doesn't tell you about the status of the individual batch items. Also check the statusCode fields in the response.
  • Detailed information about the success or failure of the individual requests within the batch is provided in the HTTP 200 response.
  • The batch download GET request is a blocking long-poll request.

Request data

HTTP method: GET

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

URL request format

get
URL request format
https://{baseURL}/routing/{versionNumber}/batch/{batchId}?key={Your_API_Key}&waitTimeSeconds={waitTimeSeconds}

URL request example

get
URL request example
https://api.tomtom.com/routing/1/batch/{batchId}?key={Your_API_Key}

curl request example

get
curl request example
curl 'https://api.tomtom.com/routing/1/batch/{batchId}?key={Your_API_Key}'

Request headers

The following table describes HTTP request headers relevant to Batch Routing service clients.

Note: There are no required headers in this endpoint.

Optional headersDescription
Accept-Encoding

Should contain a 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 the 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, for historical reasons, the download error response will have the xml format.
Note: In case of a successful response, the Accept header value does not affect the batch response format.
Value: 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 a format that matches this regular expression is a UUID: (e.g., 9ac68072-c7a4-11e8-a8d5-f2801f1b9fd1). For details, see RFC 4122.

  • If specified, it is replicated in the Tracking-ID response header.

  • Used for support purposes only. It does not track you or your users.

Value: An identifier for the request.

Request parameters

The following table describes the request parameters.

  • Required parameters must be used, or the call will fail.
  • Optional parameters may be used.
  • A parameter's data type is beneath its name.
Required parametersDescription

baseURL
string

Base URL for calling the API.
Values:

versionNumber
string

Service version.
Value: The current value is 1.

key
string

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

batchId
string

The unique id of the batch returned in the HTTP Location header of the batch submission response.
Value: A unique ID.

Optional parametersDescription

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

  • If the batch processing completes during the given number of seconds, the result is returned.

  • Otherwise, if the batch is still processing, an HTTP 202 (Accepted) response is returned. The client should retry the request by following the Location header.

Note that the provided waitTimeSeconds parameter and its value are passed to the Location response header as a part of the URI.
Default value: 120
Value: It may be either:

  • 5..60

  • 120

Response data

HTTP status codes

CodeMeaning & 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 Routing API over QPS (queries per second) or over QPD (queries per day).

  • Can also occur when using HTTP instead of HTTPS.
404

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

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 the server 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

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

HeaderDescription
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 Routing service.
Value: *

Content-Encoding

The Batch Routing service applies gzip compression to responses if the client requests it 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/json;charset=utf-8

Location

Indicates the location where the batch results can be downloaded.
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.

  • Used for support purposes only. It does not involve tracking you or your users.

Value: An identifier for the request.

Successful response structure

Each batch response consists of one or more elements, which correspond sequentially to the elements in the request. Each element contains either a successful response from the invoked Routing API suite endpoint or a status code indicating why the batch item failed.

JSON Response body example
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
batchItemsA set of batch items processing results.
statusCode

Status code of a response from the underlying Routing API suite endpoint for given batch item.

response

Content of the response from the underlying Routing API suite endpoint for a given batch item query.

  • The full response content is included in both success and failure cases.

  • If the underlying service's response content type does not match the requested content type, the response is wrapped to fit the requested content type.

summarySummary of the batch request.
successfulRequestsNumber of successful batch item requests.
totalRequestsTotal number of items in a batch request.

Successful response example

To improve the readability of the example, the copyright and privacy sections inside a batch item response are skipped.

JSON response example
1{
2  "formatVersion": "0.0.1",
3  "batchItems": [
4    {
5      "statusCode": 200,
6      "response": {
7        "formatVersion": "0.0.12",
8        "copyright": "...",
9        "privacy": "...",
10        "routes": [
11          {
12            "summary": {
13              "lengthInMeters": 223,
14              "travelTimeInSeconds": 66,
15              "trafficDelayInSeconds": 0,
16              "departureTime": "2016-04-22T13:43:25+02:00",
17              "arrivalTime": "2016-04-22T13:44:31+02:00"
18            },
19            "legs": [
20              {
21                "summary": {
22                  "lengthInMeters": 223,
23                  "travelTimeInSeconds": 66,
24                  "trafficDelayInSeconds": 0,
25                  "departureTime": "2016-04-22T13:43:25+02:00",
26                  "arrivalTime": "2016-04-22T13:44:31+02:00"
27                },
28                "points": [
29                  {
30                    "latitude": 52.36006,
31                    "longitude": 4.85109
32                  },
33                  {
34                    "latitude": 52.36084,
35                    "longitude": 4.85106
36                  },
37                  {
38                    "latitude": 52.36176,
39                    "longitude": 4.85104
40                  },
41                  {
42                    "latitude": 52.36176,
43                    "longitude": 4.85056
44                  }
45                ]
46              }
47            ],
48            "sections": [
49              {
50                "startPointIndex": 0,
51                "endPointIndex": 3,
52                "travelMode": "car"
53              }
54            ]
55          }
56        ]
57      }
58    },
59    {
60      "statusCode": 400,
61      "response": {
62        "formatVersion": "0.0.12",
63        "copyright": "...",
64        "privacy": "...",
65        "error": {
66          "description": "Invalid travel mode value: [teleport]"
67        }
68      }
69    },
70    {
71      "statusCode": 200,
72      "response": {
73        "formatVersion": "0.0.1",
74        "copyright": "...",
75        "privacy": "...",
76        "reachableRange": {
77          "center": {
78            "latitude": 52.36176,
79            "longitude": 4.85056
80          },
81          "boundary": [
82            {
83              "latitude": 52.78716,
84              "longitude": 4.81318
85            },
86            {
87              "latitude": 52.78983,
88              "longitude": 4.79019
89            },
90            {
91              "latitude": 52.78346,
92              "longitude": 4.70485
93            },
94            {
95              "latitude": 52.77541,
96              "longitude": 4.67377
97            },
98            {
99              "latitude": 52.73947,
100              "longitude": 4.6453
101            },
102            {
103              "latitude": 52.61481,
104              "longitude": 4.64891
105            },
106            {
107              "latitude": 52.61362,
108              "longitude": 4.64887
109            },
110            {
111              "latitude": 52.53855,
112              "longitude": 4.65841
113            },
114            {
115              "latitude": 52.49834,
116              "longitude": 4.64125
117            },
118            {
119              "latitude": 52.47165,
120              "longitude": 4.60932
121            },
122            {
123              "latitude": 52.46203,
124              "longitude": 4.58628
125            },
126            {
127              "latitude": 52.44705,
128              "longitude": 4.59327
129            },
130            {
131              "latitude": 52.37132,
132              "longitude": 4.52544
133            },
134            {
135              "latitude": 52.32164,
136              "longitude": 4.57722
137            },
138            {
139              "latitude": 52.26437,
140              "longitude": 4.45996
141            },
142            {
143              "latitude": 52.11393,
144              "longitude": 4.28383
145            },
146            {
147              "latitude": 50.98539,
148              "longitude": 2.23052
149            },
150            {
151              "latitude": 50.98863,
152              "longitude": 2.35777
153            },
154            {
155              "latitude": 50.43132,
156              "longitude": 2.84907
157            },
158            {
159              "latitude": 50.33847,
160              "longitude": 2.92668
161            },
162            {
163              "latitude": 50.22934,
164              "longitude": 3.27133
165            },
166            {
167              "latitude": 50.45216,
168              "longitude": 3.76045
169            },
170            {
171              "latitude": 50.48706,
172              "longitude": 4.08585
173            },
174            {
175              "latitude": 49.98206,
176              "longitude": 4.51402
177            },
178            {
179              "latitude": 50.49117,
180              "longitude": 4.6182
181            },
182            {
183              "latitude": 50.09545,
184              "longitude": 5.13195
185            },
186            {
187              "latitude": 49.91044,
188              "longitude": 5.29447
189            },
190            {
191              "latitude": 50.02166,
192              "longitude": 5.69731
193            },
194            {
195              "latitude": 50.07049,
196              "longitude": 5.73492
197            },
198            {
199              "latitude": 50.21669,
200              "longitude": 6.23432
201            },
202            {
203              "latitude": 50.11697,
204              "longitude": 6.43576
205            },
206            {
207              "latitude": 50.46513,
208              "longitude": 6.7001
209            },
210            {
211              "latitude": 50.37483,
212              "longitude": 7.41121
213            },
214            {
215              "latitude": 50.52358,
216              "longitude": 7.67539
217            },
218            {
219              "latitude": 50.87047,
220              "longitude": 7.96531
221            },
222            {
223              "latitude": 51.02269,
224              "longitude": 7.82893
225            },
226            {
227              "latitude": 51.54443,
228              "longitude": 8.1081
229            },
230            {
231              "latitude": 52.2334,
232              "longitude": 9.25347
233            },
234            {
235              "latitude": 52.86505,
236              "longitude": 8.23947
237            },
238            {
239              "latitude": 52.95622,
240              "longitude": 8.56608
241            },
242            {
243              "latitude": 53.18553,
244              "longitude": 8.10646
245            },
246            {
247              "latitude": 53.32431,
248              "longitude": 6.87906
249            },
250            {
251              "latitude": 53.24864,
252              "longitude": 6.46143
253            },
254            {
255              "latitude": 53.21977,
256              "longitude": 5.98597
257            },
258            {
259              "latitude": 53.20076,
260              "longitude": 5.64319
261            },
262            {
263              "latitude": 53.18381,
264              "longitude": 5.45848
265            },
266            {
267              "latitude": 53.03505,
268              "longitude": 5.23428
269            },
270            {
271              "latitude": 52.95193,
272              "longitude": 5.0762
273            },
274            {
275              "latitude": 52.7731,
276              "longitude": 4.956
277            },
278            {
279              "latitude": 52.73059,
280              "longitude": 4.89175
281            }
282          ]
283        }
284      }
285    },
286    {
287      "statusCode": 200,
288      "response": {
289        "formatVersion": "0.0.1",
290        "copyright": "...",
291        "privacy": "...",
292        "reachableRange": {
293          "center": {
294            "latitude": 52.36178,
295            "longitude": 4.85216
296          },
297          "boundary": [
298            {
299              "latitude": 52.55238,
300              "longitude": 4.831
301            },
302            {
303              "latitude": 52.58944,
304              "longitude": 4.81481
305            },
306            {
307              "latitude": 52.61593,
308              "longitude": 4.75696
309            },
310            {
311              "latitude": 52.61869,
312              "longitude": 4.73182
313            },
314            {
315              "latitude": 52.60065,
316              "longitude": 4.72924
317            },
318            {
319              "latitude": 52.5704,
320              "longitude": 4.69259
321            },
322            {
323              "latitude": 52.56248,
324              "longitude": 4.66803
325            },
326            {
327              "latitude": 52.51754,
328              "longitude": 4.65152
329            },
330            {
331              "latitude": 52.51005,
332              "longitude": 4.65357
333            },
334            {
335              "latitude": 52.47165,
336              "longitude": 4.60932
337            },
338            {
339              "latitude": 52.46203,
340              "longitude": 4.58628
341            },
342            {
343              "latitude": 52.44705,
344              "longitude": 4.59327
345            },
346            {
347              "latitude": 52.40392,
348              "longitude": 4.54964
349            },
350            {
351              "latitude": 52.34494,
352              "longitude": 4.58513
353            },
354            {
355              "latitude": 52.27725,
356              "longitude": 4.51188
357            },
358            {
359              "latitude": 52.17925,
360              "longitude": 4.40661
361            },
362            {
363              "latitude": 52.13387,
364              "longitude": 4.40049
365            },
366            {
367              "latitude": 52.08084,
368              "longitude": 4.4085
369            },
370            {
371              "latitude": 52.12844,
372              "longitude": 4.54478
373            },
374            {
375              "latitude": 52.14113,
376              "longitude": 4.6569
377            },
378            {
379              "latitude": 52.13626,
380              "longitude": 4.69284
381            },
382            {
383              "latitude": 52.18881,
384              "longitude": 4.76185
385            },
386            {
387              "latitude": 52.24121,
388              "longitude": 4.81595
389            },
390            {
391              "latitude": 52.25268,
392              "longitude": 4.8248
393            },
394            {
395              "latitude": 52.2258,
396              "longitude": 4.85207
397            },
398            {
399              "latitude": 52.22231,
400              "longitude": 4.86311
401            },
402            {
403              "latitude": 52.11528,
404              "longitude": 4.91272
405            },
406            {
407              "latitude": 52.10203,
408              "longitude": 4.91813
409            },
410            {
411              "latitude": 52.15657,
412              "longitude": 4.9549
413            },
414            {
415              "latitude": 52.07171,
416              "longitude": 5.03885
417            },
418            {
419              "latitude": 52.03868,
420              "longitude": 5.06395
421            },
422            {
423              "latitude": 52.06083,
424              "longitude": 5.09541
425            },
426            {
427              "latitude": 52.12659,
428              "longitude": 5.1081
429            },
430            {
431              "latitude": 52.23269,
432              "longitude": 5.04984
433            },
434            {
435              "latitude": 52.17824,
436              "longitude": 5.18006
437            },
438            {
439              "latitude": 52.20553,
440              "longitude": 5.27285
441            },
442            {
443              "latitude": 52.21432,
444              "longitude": 5.33036
445            },
446            {
447              "latitude": 52.35769,
448              "longitude": 5.3551
449            },
450            {
451              "latitude": 52.4155,
452              "longitude": 5.38742
453            },
454            {
455              "latitude": 52.37996,
456              "longitude": 4.97327
457            },
458            {
459              "latitude": 52.39278,
460              "longitude": 4.96466
461            },
462            {
463              "latitude": 52.45905,
464              "longitude": 5.03088
465            },
466            {
467              "latitude": 52.49351,
468              "longitude": 5.03124
469            },
470            {
471              "latitude": 52.54294,
472              "longitude": 5.02473
473            },
474            {
475              "latitude": 52.65356,
476              "longitude": 5.07229
477            },
478            {
479              "latitude": 52.67399,
480              "longitude": 5.06906
481            },
482            {
483              "latitude": 52.7202,
484              "longitude": 5.02538
485            },
486            {
487              "latitude": 52.63563,
488              "longitude": 4.9565
489            },
490            {
491              "latitude": 52.54702,
492              "longitude": 4.87765
493            },
494            {
495              "latitude": 52.54899,
496              "longitude": 4.86904
497            }
498          ]
499        }
500      }
501    }
502  ],
503  "summary": {
504    "successfulRequests": 3,
505    "totalRequests": 4
506  }
507}

Error response

Note: For historical reasons, the default error response format is XML. It may be changed using the Accept header.

JSON error response example
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
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 array

innerError`
object

Optional.
A higher level of detail 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 detail about this error.
innerError object

Error code hierarchy

List of predefined, hierarchical, human-readable error codes.

  • Top-level codes correspond to HTTP error codes.
  • These 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. Applications must be ready to handle unknown error codes (e.g., by stopping error processing at the last understood level of detail).

Error codeDescription
BadArgument

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

Possible inner errors:

  • InvalidParameterValue

  • ValueOutOfRange

BatchNotFound

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

InvalidParameterValueThe value of one of the parameters is invalid.
InternalServerError

Top-level code for requests that resulted in an HTTP 500 Internal Server Error. The service cannot handle the request right now due to an unexpected condition.

NotFound

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

ServiceUnavailable

Top-level code for requests that resulted in an HTTP 503 Service Unavailable. The service cannot handle the request right now; this is typically a temporary state.

ValueOutOfRange

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