Asynchronous batch download
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 HTTP202
"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 thewaitTimeSeconds
parameter with a desired value. The client should then retry the request by following theLocation
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
https://{baseURL}/routing/{versionNumber}/batch/{batchId}?key={Your_API_Key}&waitTimeSeconds={waitTimeSeconds}
URL request example
https://api.tomtom.com/routing/1/batch/{batchId}?key={Your_API_Key}
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 headers | Description |
---|---|
Accept-Encoding | Should contain a list of encodings acceptable by the client. Used to
demand a compressed response. |
Accept | Indicates the format of the download
error response (e.g., a batch with the
provided |
Tracking-ID | Specifies an identifier for the request.
Value: An |
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 parameters | Description |
---|---|
| Base URL for calling the API.
|
| Service version. |
| An API key valid for the requested service. |
| The unique id of the batch returned in the HTTP Location header of the batch submission response. |
Optional parameters | Description |
---|---|
| 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.
Note that the provided
|
Response data
HTTP 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:
|
404 | Not Found: The requested resource could not be found. For example,
a batch with the provided |
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.
Header | Description |
---|---|
Access-Control-Expose-Headers | A comma-separated list of HTTP header names that browsers are allowed to
access. |
Access-Control-Allow-Origin | A header instructing browsers to allow customer websites to contact the
Batch Routing service. |
Content-Encoding | The Batch Routing service applies gzip compression to responses if
the client requests it with the Accept-Encoding header. |
Content-Type | The format of the response as chosen by the client. See the |
Location | Indicates the location where the batch results can be downloaded. |
Tracking-ID | An identifier for the request.
Value: An |
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.
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 |
---|---|
batchItems | A 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.
|
summary | Summary of the batch request. |
successfulRequests | Number of successful batch item requests. |
totalRequests | Total 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.8510932 },33 {34 "latitude": 52.36084,35 "longitude": 4.8510636 },37 {38 "latitude": 52.36176,39 "longitude": 4.8510440 },41 {42 "latitude": 52.36176,43 "longitude": 4.8505644 }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.8505680 },81 "boundary": [82 {83 "latitude": 52.78716,84 "longitude": 4.8131885 },86 {87 "latitude": 52.78983,88 "longitude": 4.7901989 },90 {91 "latitude": 52.78346,92 "longitude": 4.7048593 },94 {95 "latitude": 52.77541,96 "longitude": 4.6737797 },98 {99 "latitude": 52.73947,100 "longitude": 4.6453101 },102 {103 "latitude": 52.61481,104 "longitude": 4.64891105 },106 {107 "latitude": 52.61362,108 "longitude": 4.64887109 },110 {111 "latitude": 52.53855,112 "longitude": 4.65841113 },114 {115 "latitude": 52.49834,116 "longitude": 4.64125117 },118 {119 "latitude": 52.47165,120 "longitude": 4.60932121 },122 {123 "latitude": 52.46203,124 "longitude": 4.58628125 },126 {127 "latitude": 52.44705,128 "longitude": 4.59327129 },130 {131 "latitude": 52.37132,132 "longitude": 4.52544133 },134 {135 "latitude": 52.32164,136 "longitude": 4.57722137 },138 {139 "latitude": 52.26437,140 "longitude": 4.45996141 },142 {143 "latitude": 52.11393,144 "longitude": 4.28383145 },146 {147 "latitude": 50.98539,148 "longitude": 2.23052149 },150 {151 "latitude": 50.98863,152 "longitude": 2.35777153 },154 {155 "latitude": 50.43132,156 "longitude": 2.84907157 },158 {159 "latitude": 50.33847,160 "longitude": 2.92668161 },162 {163 "latitude": 50.22934,164 "longitude": 3.27133165 },166 {167 "latitude": 50.45216,168 "longitude": 3.76045169 },170 {171 "latitude": 50.48706,172 "longitude": 4.08585173 },174 {175 "latitude": 49.98206,176 "longitude": 4.51402177 },178 {179 "latitude": 50.49117,180 "longitude": 4.6182181 },182 {183 "latitude": 50.09545,184 "longitude": 5.13195185 },186 {187 "latitude": 49.91044,188 "longitude": 5.29447189 },190 {191 "latitude": 50.02166,192 "longitude": 5.69731193 },194 {195 "latitude": 50.07049,196 "longitude": 5.73492197 },198 {199 "latitude": 50.21669,200 "longitude": 6.23432201 },202 {203 "latitude": 50.11697,204 "longitude": 6.43576205 },206 {207 "latitude": 50.46513,208 "longitude": 6.7001209 },210 {211 "latitude": 50.37483,212 "longitude": 7.41121213 },214 {215 "latitude": 50.52358,216 "longitude": 7.67539217 },218 {219 "latitude": 50.87047,220 "longitude": 7.96531221 },222 {223 "latitude": 51.02269,224 "longitude": 7.82893225 },226 {227 "latitude": 51.54443,228 "longitude": 8.1081229 },230 {231 "latitude": 52.2334,232 "longitude": 9.25347233 },234 {235 "latitude": 52.86505,236 "longitude": 8.23947237 },238 {239 "latitude": 52.95622,240 "longitude": 8.56608241 },242 {243 "latitude": 53.18553,244 "longitude": 8.10646245 },246 {247 "latitude": 53.32431,248 "longitude": 6.87906249 },250 {251 "latitude": 53.24864,252 "longitude": 6.46143253 },254 {255 "latitude": 53.21977,256 "longitude": 5.98597257 },258 {259 "latitude": 53.20076,260 "longitude": 5.64319261 },262 {263 "latitude": 53.18381,264 "longitude": 5.45848265 },266 {267 "latitude": 53.03505,268 "longitude": 5.23428269 },270 {271 "latitude": 52.95193,272 "longitude": 5.0762273 },274 {275 "latitude": 52.7731,276 "longitude": 4.956277 },278 {279 "latitude": 52.73059,280 "longitude": 4.89175281 }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.85216296 },297 "boundary": [298 {299 "latitude": 52.55238,300 "longitude": 4.831301 },302 {303 "latitude": 52.58944,304 "longitude": 4.81481305 },306 {307 "latitude": 52.61593,308 "longitude": 4.75696309 },310 {311 "latitude": 52.61869,312 "longitude": 4.73182313 },314 {315 "latitude": 52.60065,316 "longitude": 4.72924317 },318 {319 "latitude": 52.5704,320 "longitude": 4.69259321 },322 {323 "latitude": 52.56248,324 "longitude": 4.66803325 },326 {327 "latitude": 52.51754,328 "longitude": 4.65152329 },330 {331 "latitude": 52.51005,332 "longitude": 4.65357333 },334 {335 "latitude": 52.47165,336 "longitude": 4.60932337 },338 {339 "latitude": 52.46203,340 "longitude": 4.58628341 },342 {343 "latitude": 52.44705,344 "longitude": 4.59327345 },346 {347 "latitude": 52.40392,348 "longitude": 4.54964349 },350 {351 "latitude": 52.34494,352 "longitude": 4.58513353 },354 {355 "latitude": 52.27725,356 "longitude": 4.51188357 },358 {359 "latitude": 52.17925,360 "longitude": 4.40661361 },362 {363 "latitude": 52.13387,364 "longitude": 4.40049365 },366 {367 "latitude": 52.08084,368 "longitude": 4.4085369 },370 {371 "latitude": 52.12844,372 "longitude": 4.54478373 },374 {375 "latitude": 52.14113,376 "longitude": 4.6569377 },378 {379 "latitude": 52.13626,380 "longitude": 4.69284381 },382 {383 "latitude": 52.18881,384 "longitude": 4.76185385 },386 {387 "latitude": 52.24121,388 "longitude": 4.81595389 },390 {391 "latitude": 52.25268,392 "longitude": 4.8248393 },394 {395 "latitude": 52.2258,396 "longitude": 4.85207397 },398 {399 "latitude": 52.22231,400 "longitude": 4.86311401 },402 {403 "latitude": 52.11528,404 "longitude": 4.91272405 },406 {407 "latitude": 52.10203,408 "longitude": 4.91813409 },410 {411 "latitude": 52.15657,412 "longitude": 4.9549413 },414 {415 "latitude": 52.07171,416 "longitude": 5.03885417 },418 {419 "latitude": 52.03868,420 "longitude": 5.06395421 },422 {423 "latitude": 52.06083,424 "longitude": 5.09541425 },426 {427 "latitude": 52.12659,428 "longitude": 5.1081429 },430 {431 "latitude": 52.23269,432 "longitude": 5.04984433 },434 {435 "latitude": 52.17824,436 "longitude": 5.18006437 },438 {439 "latitude": 52.20553,440 "longitude": 5.27285441 },442 {443 "latitude": 52.21432,444 "longitude": 5.33036445 },446 {447 "latitude": 52.35769,448 "longitude": 5.3551449 },450 {451 "latitude": 52.4155,452 "longitude": 5.38742453 },454 {455 "latitude": 52.37996,456 "longitude": 4.97327457 },458 {459 "latitude": 52.39278,460 "longitude": 4.96466461 },462 {463 "latitude": 52.45905,464 "longitude": 5.03088465 },466 {467 "latitude": 52.49351,468 "longitude": 5.03124469 },470 {471 "latitude": 52.54294,472 "longitude": 5.02473473 },474 {475 "latitude": 52.65356,476 "longitude": 5.07229477 },478 {479 "latitude": 52.67399,480 "longitude": 5.06906481 },482 {483 "latitude": 52.7202,484 "longitude": 5.02538485 },486 {487 "latitude": 52.63563,488 "longitude": 4.9565489 },490 {491 "latitude": 52.54702,492 "longitude": 4.87765493 },494 {495 "latitude": 52.54899,496 "longitude": 4.86904497 }498 ]499 }500 }501 }502 ],503 "summary": {504 "successfulRequests": 3,505 "totalRequests": 4506 }507}
Error response
Note: For historical reasons, the default error response format is XML. It may be changed using the Accept header.
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. |
detailedError object | Detailed information about the error. |
error object | |
Field | Description |
description string | A human-readable description of the error. |
detailedError object | |
Field | Description |
| One of the defined error codes. |
| 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. |
| Optional.
|
| Optional. |
innerError` | Optional. |
innerError object | |
Field | Description |
| One of the defined error codes. |
| Optional. |
| Optional. |
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
orinnerError
. - Further levels of refinement are possible by nesting
innerError
insideinnerError
.
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 code | Description |
---|---|
BadArgument | One of the request parameters did not pass validation. The Possible inner errors:
|
BatchNotFound | Top-level code for requests which resulted in an HTTP |
InvalidParameterValue | The value of one of the parameters is invalid. |
InternalServerError | Top-level code for requests that resulted in an HTTP |
NotFound | Top-level code for requests that resulted in an HTTP |
ServiceUnavailable | Top-level code for requests that resulted in an HTTP |
ValueOutOfRange | The value of one of the numeric parameters is outside the allowed range. |