Asynchronous Batch Submission

Service version: 1
Last edit: 2022.05.05

Deprecation Notice

Dec 1, 2020
  • All XML capabilities of the Batch Routing API are deprecated. This includes:
    • base path parameter outputFormat value xml
    • request header Content-Type value application/xml
    • POST body batch item's query output format (last path element) value xml
    • POST body parameter post value format XML
  • These capabilities will be withdrawn following a 12 month deprecation period.
  • The planned withdrawal date is Dec 1, 2021.
  • Following withdrawal, requests using this functionality may receive an HTTP error in the response.

Purpose

The Asynchronous Batch Submission endpoint allows the submission of a new batch for asynchronous processing. It responds with a redirect to the location at which the batch results can be obtained when the batch processing has completed.

Request data

HTTPS Method: POST

  • 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
URL request format
https://{baseURL}/routing/{versionNumber}/batch/{outputFormat}?key={Your_API_Key}&redirectMode={redirectMode}&waitTimeSeconds={waitTimeSeconds}

Example

POST
Request example
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 service clients.

Required headersDescription
Content-TypeSpecifies the MIME type of the body of the request. It may be:
  • application/xml Deprecated - for details, see a deprecation notice at the top of this page.
  • application/json
Optional headersDescription
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.

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.
Optional parametersDescription
outputFormat
string		The content type of the response structure.
If it is not provided, then xml is assumed as default.
Value: It may be either:
  • json
  • xml Deprecated - for details, see a deprecation notice at the top of this page.
redirectMode
string		Controls the HTTP code of the successful HTTP response to the Submission request.
Value:
  • When set to auto, HTTP code 303 is returned. The HTTP client may automatically redirect to the download endpoint.
  • When set to manual, HTTP code 202 is returned. The HTTP client will not automatically redirect to the download endpoint.

In both cases the same Location header is included.
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.
Please 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

Supported Routing API suite endpoints

A list of Routing API suite endpoints supported by the Batch Routing 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 Routing API suite.

Each batch request can contain items corresponding to multiple supported endpoints of the Routing API suite. For each endpoint, the same body structure applies and specific parameters of each endpoint are expected to go into query elements.

POST body (XML)

POST
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 body (JSON)

POST
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.
Value: The XML root element.
batchItemsA set of batch items.
Value: The maximum number of batch items for an Asynchronous API is 700.
batchItemA single batch item.
Value: One batch item.
queryA string used to build a request to one of the supported endpoints of the Routing API suite.
  • It is a partial URL without protocol, base URL, service version or API Key parts.
  • The output format (last path element) must match the outputFormat parameter of the batch request.

Value: When posting XML to the Batch Routing service, the <query> element values must be valid XML (e.g., the & character must be replaced by the predefined XML entity `&`). More information is available in the List of XML character entity references.Deprecated - for details, see a deprecation notice at the top of this page.

Please note that the callback parameter is not supported by Batch Routing. For detailed descriptions refer to the documentation of Calculate Route and Calculate Reachable Range services.

postContains data that is passed to the Calculate Route or Calculate Reachable Range services using the HTTP POST method.
  • The `POST` data format must match the Content-Type header of a submitted batch request i.e., it should be in JSON format when the Content-Type is set to application/json and should be in XML format (Deprecated - for details, see a deprecation notice at the top of this page) if the Content-Type is set to application/xml.
  • Please refer to the POST Data Parameters section of Calculate Route and Calculate Reachable Range services documentation for detailed descriptions and examples of XML and JSON content for this field.

POST body examples

Mixed endpoint examples
POST
POST body request example - XML
1<?xml version="1.0" encoding="utf-8"?>
2<batchRequest>
3  <batchItems>
4    <batchItem>
5      <query>/calculateRoute/52.36006039665441,4.851064682006836:52.36187528311709,4.850560426712036/xml?travelMode=car&routeType=fastest&traffic=true&departAt=now&maxAlternatives=0</query>
6    </batchItem>
7    <batchItem>
8      <query>/calculateRoute/52.36241907934766,4.850034713745116:52.36173769505809,4.852169752120972/xml?travelMode=teleport&routeType=fastest&traffic=true&departAt=now</query>
9    </batchItem>
10    <batchItem>
11      <query>/calculateRoute/52.23292,21.06179:43.29379,17.01963/xml</query>
12      <post>
13        <postData>
14          <avoidVignette>
15            AUS,CHE
16          </avoidVignette>
17        </postData>
18      </post>
19    </batchItem>
20    <batchItem>
21      <query>/calculateReachableRange/52.36187528311709,4.850560426712036/xml?fuelBudgetInLiters=20&constantSpeedConsumptionInLitersPerHundredkm=50,6</query>
22      <post>
23        <postData>
24          <avoidVignette>
25            NLD
26          </avoidVignette>
27        </postData>
28      </post>
29    </batchItem>
30    <batchItem>
31      <query>/calculateReachableRange/52.36173769505809,4.852169752120972/xml?timeBudgetInSec=1800</query>
32    </batchItem>
33  </batchItems>
34</batchRequest>
POST
POST body request example - JSON
1{
2  "batchItems": [
3    {"query": "/calculateRoute/52.36006039665441,4.851064682006836:52.36187528311709,4.850560426712036/json?travelMode=car&amp;routeType=fastest&amp;traffic=true&amp;departAt=now&amp;maxAlternatives=0"},
4    {"query": "/calculateRoute/52.36241907934766,4.850034713745116:52.36173769505809,4.852169752120972/json?travelMode=teleport&amp;routeType=fastest&amp;traffic=true&amp;departAt=now"},
5    {
6      "query": "/calculateRoute/52.23292,21.06179:43.29379,17.01963/json",
7      "post": {
8        "avoidVignette": [
9          "AUS",
10          "CHE"
11        ]
12      }
13    },
14    {
15      "query": "/calculateReachableRange/52.36187528311709,4.850560426712036/json?fuelBudgetInLiters=20&amp;constantSpeedConsumptionInLitersPerHundredkm=50,6",
16      "post": {
17        "avoidVignette": [
18          "NLD"
19        ]
20      }
21    },
22    {"query": "/calculateReachableRange/52.36173769505809,4.852169752120972/json?timeBudgetInSec=1800"}
23  ]
24}
Calculate Route examples
POST
POST request body example - XML
1  <?xml version="1.0" encoding="utf-8" ?>
2  <batchRequest>
3    <batchItems>
4      <batchItem>
5        <query>/calculateRoute/52.36006039665441,4.851064682006836:52.36187528311709,4.850560426712036/xml?travelMode=car&routeType=fastest&traffic=true&departAt=now&maxAlternatives=0</query>
6      </batchItem>
7      <batchItem>
8        <query>/calculateRoute/52.36241907934766,4.850034713745116:52.36173769505809,4.852169752120972/xml?travelMode=teleport&routeType=fastest&traffic=true&departAt=now</query>
9      </batchItem>
10      <batchItem>
11        <query>/calculateRoute/52.23292,21.06179:43.29379,17.01963/xml</query>
12        <post>
13          <postData>
14            <avoidVignette>
15              AUS,CHE
16            </avoidVignette>
17          </postData>
18        </post>
19      </batchItem>
20    </batchItems>
21  </batchRequest>
POST
POST request body example - JSON
1  {
2    "batchItems": [
3      {"query": "/calculateRoute/52.36006039665441,4.851064682006836:52.36187528311709,4.850560426712036/json?travelMode=car&routeType=fastest&traffic=true&departAt=now&maxAlternatives=0"},
4      {"query": "/calculateRoute/52.36241907934766,4.850034713745116:52.36173769505809,4.852169752120972/json?travelMode=teleport&routeType=fastest&traffic=true&departAt=now"},
5      {
6        "query": "/calculateRoute/52.23292,21.06179:43.29379,17.01963/json",
7        "post": {
8          "avoidVignette": [
9            "AUS",
10            "CHE"
11          ]
12        }
13      }
14    ]
15  }
Calculate Reachable Range examples
POST
POST request body example - XML
1<?xml version="1.0" encoding="utf-8"?>
2<batchRequest>
3  <batchItems>
4    <batchItem>
5      <query>/calculateReachableRange/52.36187528311709,4.850560426712036/xml?fuelBudgetInLiters=20&constantSpeedConsumptionInLitersPerHundredkm=50,6</query>
6      <post>
7        <postData>
8          <avoidVignette>
9            NLD
10          </avoidVignette>
11        </postData>
12      </post>
13    </batchItem>
14    <batchItem>
15      <query>/calculateReachableRange/52.36173769505809,4.852169752120972/xml?timeBudgetInSec=1800</query>
16    </batchItem>
17  </batchItems>
18</batchRequest>
POST
POST request body example - JSON
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}

Response data

Batch Submission response

On a 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

CodeMeaning & possible causes
202Accepted:
  • An HTTP response with a Location header that points where the batch results can be obtained.
  • This code is used when redirectMode is set to manual.
303See Other:
  • An HTTP response with a Location header that points where the batch results can be obtained.
  • This code is used when redirectMode is set to auto.
400Bad Request:
  • Missing required parameters.
  • Exceeded maximum number of batch items.
  • Parameters did not pass validation.
403Forbidden:
  • The API Key is missing, inactive, invalid, 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.
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.
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 describes HTTP response headers of particular interest to Batch 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 Routing service.
Value: *
Content-EncodingThe Batch Routing 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
  • application/json;charset=utf-8
LocationIndicates the location where the batch results can be downloaded.
Value: URI
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.

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  {
5    "description": "Validation of batch item 1 failed. Batch response format (JSON) does not match content type of batch item query."
6  },
7  "detailedError": 
8  {
9    "code": "BadRequest",
10    "message": "Bad Request",
11    "details": 
12    {
13      "code": "MalformedBody",
14      "message": "Validation of batch item 1 failed. Batch response format (JSON) does not match content type of batch item query",
15      "target": "postBody"
16    }
17  }
18}

Error response fields

Primary fieldsDescription
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 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

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

One 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
  • ValueOutOfRange
BadRequest

Top level code for requests which resulted in an HTTP 400 Bad Request.

Possible root causes:

  • BadArgument
  • MalformedBody
IllegalParameterUnsupported request parameter was specified.
InvalidParameterValueThe value of one of the parameters is invalid.
InternalServerErrorTop 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.
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 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.
ValueOutOfRangeThe value of one of the numeric parameters is out of the allowed range.