Asynchronous batch submission
Purpose
The asynchronous batch submission endpoint allows you to submit a new batch for asynchronous processing. It responds with a redirect to the location where the batch results can be obtained after processing is complete.
Request data
HTTPS method: POST
- 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/json?key={Your_API_Key}&redirectMode={redirectMode}&waitTimeSeconds={waitTimeSeconds}
URL request example
https://api.tomtom.com/routing/1/batch/json?key={Your_API_Key}
curl request example
curl -XPOST 'https://api.tomtom.com/routing/1/batch/json?key={Your_API_Key}'
Request headers
The following data table describes HTTP request headers of particular interest to Batch Routing service clients.
Required headers | Description |
---|---|
Content-Type | Specifies the MIME type of the request body. Valid value: |
Optional headers | Description |
---|---|
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. |
Optional parameters | Description |
---|---|
| Controls the HTTP code of the successful HTTP response to the submission request.
In both cases, the same Location header is included. |
| 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.
|
Supported Routing API suite endpoints
The following supported Routing API suite endpoints can be used with the Batch Routing service. For details about each API, see their respective documentation pages:
POST request body
The POST
body of a batch request must contain a set of items used to execute requests to supported endpoints of the Routing API suite.
Each batch request can contain items corresponding to multiple supported endpoints of the Routing API suite. The same body structure applies to each endpoint. Endpoint-specific parameters must be placed in query
elements.
1{2 "batchItems": [3 {"query": "..."},4 ...5 {6 "query": "...",7 "post": {...}8 }9 ]10}
POST request body fields
Field | Description |
---|---|
batchItems | A set of batch items. |
query | A string used to build a request to one of the supported endpoints of the Routing API suite.
|
post | Contains data that is passed to the Calculate Route or Calculate Reachable Range services using the HTTP POST method.
|
POST request body examples
1{2 "batchItems": [3 {4 "query": "/calculateRoute/52.36006039665441,4.851064682006836:52.36187528311709,4.850560426712036/json?travelMode=car&routeType=fastest&traffic=true&departAt=now&maxAlternatives=0"5 },6 {7 "query": "/calculateRoute/52.36241907934766,4.850034713745116:52.36173769505809,4.852169752120972/json?travelMode=teleport&routeType=fastest&traffic=true&departAt=now"8 },9 {10 "query": "/calculateRoute/52.23292,21.06179:43.29379,17.01963/json",11 "post": {12 "avoidVignette": [13 "AUS",14 "CHE"15 ]16 }17 },18 {19 "query": "/calculateReachableRange/52.36187528311709,4.850560426712036/json?fuelBudgetInLiters=20&constantSpeedConsumptionInLitersPerHundredkm=50,6",20 "post": {21 "avoidVignette": [22 "NLD"23 ]24 }25 },26 {27 "query": "/calculateReachableRange/52.36173769505809,4.852169752120972/json?timeBudgetInSec=1800"28 }29 ]30}
1{2 "batchItems": [3 {4 "query": "/calculateRoute/52.36006039665441,4.851064682006836:52.36187528311709,4.850560426712036/json?travelMode=car&routeType=fastest&traffic=true&departAt=now&maxAlternatives=0"5 },6 {7 "query": "/calculateRoute/52.36241907934766,4.850034713745116:52.36173769505809,4.852169752120972/json?travelMode=teleport&routeType=fastest&traffic=true&departAt=now"8 },9 {10 "query": "/calculateRoute/52.23292,21.06179:43.29379,17.01963/json",11 "post": {12 "avoidVignette": [13 "AUS",14 "CHE"15 ]16 }17 }18 ]19}
1{2 "batchItems": [3 {4 "query": "/calculateReachableRange/52.36187528311709,4.850560426712036/json?fuelBudgetInLiters=20&constantSpeedConsumptionInLitersPerHundredkm=50,6",5 "post": {6 "avoidVignette": [7 "NLD"8 ]9 }10 },11 {12 "query": "/calculateReachableRange/52.36173769505809,4.852169752120972/json?timeBudgetInSec=1800"13 }14 ]15}
Response data
Batch submission response
On successful batch request submission, the Batch Routing service responds with an HTTP 202
or an HTTP 303
. The response has a Location header with a link to the batch download endpoint and no body. In case of an error, a body is present.
HTTP Status codes
Code | Meaning & possible causes |
---|---|
202 | Accepted:
|
| See Other:
|
400 | Bad Request:
|
403 | Forbidden:
|
404 | Not Found: The requested resource could not be found. It may be available again in the future. |
405 | Method Not Allowed: The client used an HTTP method other than POST. |
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 table describes HTTP response headers of particular interest to Batch Routing 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 the responses if
requested by the client using 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 |
Error response
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 | Description |
---|---|
| Version of the batch error response format. |
| Simplified information about the error. |
| Detailed information about the error. |
error object | |
Field | Description |
| 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 |
| 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. |
| Optional. |
innerError object | |
Field | Description |
| One of the defined error codes. |
| 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. |
| Optional. |
Error code hierarchy
A 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
orinnerError
. - Further levels of refinement are possible by nesting
innerError
insideinnerError
.
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 was missing or did not pass validation.
The Possible inner errors:
|
BadRequest | Top-level code for requests that resulted in an HTTP Possible root causes:
|
IllegalParameter | Unsupported request parameter was specified. |
InvalidParameterValue | The value of one of the parameters is invalid. |
InternalServerError | Top-level code for requests that resulted in an HTTP |
MalformedBody | POST body has an unexpected format. |
MissingRequiredParameter | One of the required parameters was not provided. |
NotFound | Top-level code for requests that resulted in an HTTP 404 Not Found caused by providing an incorrect request path. |
ServiceUnavailable | Top-level code for requests that resulted in an HTTP |
ValueOutOfRange | The value of one of the numeric parameters is out of the allowed range. |