Sorry, you need to enable JavaScript to visit this website.

Batch Routing

Dispatch batches of Routing requests with ease.

 

Sequence of client actions

  1. Client sends a request to the batch submission endpoint.
  2. The server will respond with one of:
  3. After getting a HTTP 303 response the client should follow the redirect to the batch download endpoint which is a blocking long poll request.
  4. Client waits for batch response, possible scenarios are:
    • Batch response is calculated before timeout. The client receives HTTP 200. Batch response is ready and it gets streamed to the client.
    • Batch response is not ready before timeout. The client receives HTTP 202. Batch request is accepted for processing. The client downloads batch results from the URL specified by the Location header (see point 3).

 

Batch submission endpoint

Submit a new batch for processing.

Responds with a redirect to the location at which the batch results can be obtained when the batch processing has completed.

Batch submission request

Format

POST https://<baseURL>/routing/<versionNumber>/batch[/<outputFormat>]?key=<APIKEY>

Example

https://api.tomtom.com/routing/1/batch/xml?key=<APIKEY>

Headers

The table below describes HTTP request headers of particular interest to Batch Routing service clients. Required headers must be used or the call will fail. Optional headers, which are highlighted with [square brackets], may be used. If there is a default value that will be assumed when an optional header is not used, it is shown in the table. The order of request headers is not important.

Header Description Req'd? Values Default Value
Content-Type Specifies the MIME type of the body of the request. Yes
  • application/xml
  • application/json

 

Parameters

The table below describes all of the parameters that can be used in a request. Required parameters must be used or the call will fail. Optional parameters, which are highlighted with [square brackets], may be used. If there is a default value that will be assumed when an optional parameter is not used, it is shown in the table. The order of request parameters is not important.

Parameter Description Req'd? Type / Values Default Value Max Value
baseURL Base URL for calling the API. Yes api.tomtom.com
versionNumber Service version number. The current value is 1. Yes 1
key Authorization key for access to the API. Yes API Key
[outputFormat] The content type of the response structure. No
  • xml
  • json
xml

 

POST body

The POST body of batch request should contain a set of items which will be used to execute requests to the Routing service.

POST body format

XML:

<?xml version="1.0" encoding="utf-8"?>
<batchRequest>
    <batchItems>
        <batchItem>
            <query>queryValue</query>
        </batchItem>
        ...
        <batchItem>
            <query>queryValue</query>
        </batchItem>
    </batchItems>
</batchRequest>

JSON:

{
  "batchItems": [
    {"query": "queryValue"},
    ....
    {"query": "queryValue"}
  ]
}

POST body example

XML:

<?xml version="1.0" encoding="utf-8"?>
<batchRequest>
    <batchItems>
        <batchItem>
            <query>/calculateRoute/52.36006039665441,4.851064682006836:52.36187528311709,4.850560426712036/xml?travelMode=car&amp;routeType=shortest&amp;traffic=true&amp;departAt=now&amp;maxAlternatives=0</query>
        </batchItem>
        <batchItem>
            <query>/calculateRoute/52.36241907934766,4.850034713745116:52.36173769505809,4.852169752120972/xml?travelMode=teleport&amp;routeType=shortest&amp;traffic=true&amp;departAt=now</query>
        </batchItem>
    </batchItems>
</batchRequest>

JSON:

{
  "batchItems": [
    {"query": "/calculateRoute/52.36006039665441,4.851064682006836:52.36187528311709,4.850560426712036/json?travelMode=car&routeType=shortest&traffic=true&departAt=now&maxAlternatives=0"},
    {"query": "/calculateRoute/52.36241907934766,4.850034713745116:52.36173769505809,4.852169752120972/json?travelMode=teleport&routeType=shortest&traffic=true&departAt=now"}
  ]
}

Structure of POST body

Field Description
batchRequest Root element of the request.
batchItems A set of batch items. Maximum number of batch items is 700.
batchItem A single batch item.
query A string used to build a request to the Routing service. 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. When POSTing XML to the Batch Routing service the <query> element values must be valid XML (e.g. & must be &amp;, see example of batch XML POST body content).

When POSTing JSON to the Batch Routing service the <query> element values must be valid JSON (e.g. " should be \").

Please note that the callback parameter and supporting points POST requests are not supported by Batch Routing.

 

Batch submission response

On a successful batch request submission the Batch Routing service responds with a HTTP 303 redirect to batch download endpoint. Response has a Location header with link to that endpoint and no body.

Response Codes

Code Meaning and Possible Causes
303

See Other: a HTTP redirect to the location where the batch results can be obtained.

400 Bad Request: Missing required parameters, exceeded maximum number of batch items or parameters didn't pass validation.
403 Forbidden: The API key is missing, inactive, invalid, not entitled to use the Batch Routing API, over QPS or over QPD. Can also occur when using HTTP instead of HTTPS.
404 Not Found: the requested resource could not be found, but it may be available again in the future.
405 Method Not Allowed: the client used a HTTP method other than GET (download endpoint) or POST (submission endpoint).
408 Request timeout.
414 Requested uri is too long.
500 An error occured while processing the request. Please try again later.
502 Internal network connectivity issue.
503 Service currently unavailable.
504 Internal network connectivity issue or a request that has taken too long to complete.
596 Service not found. Request contains an incorrect FQDN and/or path.

 

Response Headers

Header Description Values
Location Indicates the location where the batch results can be downloaded. URI
Access-Control-Expose-Headers A comma separated list of HTTP header names that browsers are allowed to access. Content-Length
Access-Control-Allow-Origin A header instructing browsers to allow customer websites to contact the Batch Routing service. *
Content-Encoding The Batch Routing service supports HTTP compression, if requested by the client. gzip
Content-Type The format of the response as chosen by the client (see the contentType request parameter).
  • application/xml; charset=utf-8
  • application/json; charset=utf-8

 

Batch download endpoint

Fetch the batch results, if ready.

Responds with HTTP 200 and the batch results assuming batch processing has completed, or HTTP 202 Accepted if the batch is still being processed. A HTTP 200 response does not indicate that every batch item succeeded, only that the batch 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 GET request is a blocking long poll request.

Batch download request

Format

GET https://<baseURL>/routing/<versionNumber>/batch/<batchId>?key=<APIKEY>

Example

https://api.tomtom.com/routing/1/batch/<batchId>?key=<APIKEY>

Headers

The table below describes HTTP request headers of particular interest to Batch Routing service clients. Required headers must be used or the call will fail. Optional headers, which are highlighted with [square brackets], may be used. If there is a default value that will be assumed when an optional header is not used, it is shown in the table. The order of request headers is not important.

Header Description Req'd? Values Default Value
[Accept-Encoding] Requests that the response be compressed. No gzip

Parameters

The table below describes all of the parameters that can be used in a request. Required parameters must be used or the call will fail. Optional parameters, which are highlighted with [square brackets], may be used. If there is a default value that will be assumed when an optional parameter is not used, it is shown in the table. The order of request parameters is not important.

Parameter Description Req'd? Type / Values Default Value Max Value
baseURL Base URL for calling the API. Yes api.tomtom.com
versionNumber Service version number. The current value is 1. Yes 1
key Authorization key for access to the API. Yes API Key
batchId Unique id of the batch, returned in HTTP 303 See Other HTTP Location header of Batch Submission response. Yes String

 

Batch download response

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 Online Routing API or a status code indicating why the batch item failed.

Successful batch response structure

XML:

<?xml version="1.0" encoding="utf-8"?>
<batchResponse xmlns="http://api.tomtom.com/batch" formatVersion="0.0.1">
    <batchItems>
        <batchItem>
            <statusCode>...</statusCode>
            <response>
                ...
            </response>
        </batchItem>
        ...
        <batchItem>
            <statusCode>...</statusCode>
            <response>
                ...
            </response>
        </batchItem>
    </batchItems>
    <summary>
        <successfulRequests>...</successfulRequests>
        <totalRequests>...</totalRequests>
    </summary>
</batchResponse>

JSON:

{
    "formatVersion": "0.0.1",
    "batchItems": [
        {
            "statusCode": ...,
            "response": {...}
        },
        ...,
        {
            "statusCode": ...,
            "response": {...}
        }
    ],
    "summary": {
        "successfulRequests": ...,
        "totalRequests": ...
    }
}

Structure of a successful response

Field Description
batchResponse Root element of the batch response.
successfulRequests Number of successful batch item requests.
totalRequests Total number of items in batch request.
batchItems A set of batch items processing results.
batchItem Contains results of processing of a single batch item.
statusCode Status code of a response from the Routing endpoint for given batch item.
response Content of the response from the Routing 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 Summary of the batch request.

Example of a successful response

To improve readability of the examples, the copyright and privacy sections inside batch items' response are skipped.

XML:

<?xml version="1.0" encoding="utf-8"?>
<batchResponse xmlns="http://api.tomtom.com/batch" formatVersion="0.0.1">
    <batchItems>
        <batchItem>
            <statusCode>200</statusCode>
            <response>
                <calculateRouteResponse xmlns="http://api.tomtom.com/routing" formatVersion="0.0.12"><copyright>...</copyright><privacy>...</privacy><route><summary><lengthInMeters>223</lengthInMeters><travelTimeInSeconds>66</travelTimeInSeconds><trafficDelayInSeconds>0</trafficDelayInSeconds><departureTime>2016-04-22T13:21:30+02:00</departureTime><arrivalTime>2016-04-22T13:22:36+02:00</arrivalTime></summary><leg><summary><lengthInMeters>223</lengthInMeters><travelTimeInSeconds>66</travelTimeInSeconds><trafficDelayInSeconds>0</trafficDelayInSeconds><departureTime>2016-04-22T13:21:30+02:00</departureTime><arrivalTime>2016-04-22T13:22:36+02:00</arrivalTime></summary><points><point latitude="52.36006" longitude="4.85109"/><point latitude="52.36084" longitude="4.85106"/><point latitude="52.36176" longitude="4.85104"/><point latitude="52.36176" longitude="4.85056"/></points></leg><sections><section><startPointIndex>0</startPointIndex><endPointIndex>3</endPointIndex><travelMode>car</travelMode></section></sections></route></calculateRouteResponse>
            </response>
        </batchItem>
        <batchItem>
            <statusCode>400</statusCode>
            <response>
                <calculateRouteResponse xmlns="http://api.tomtom.com/routing" formatVersion="0.0.12"><copyright>...</copyright><privacy>...</privacy><error description="Invalid travel mode value: [teleport]"/></calculateRouteResponse>
            </response>
        </batchItem>
    </batchItems>
    <summary>
        <successfulRequests>1</successfulRequests>
        <totalRequests>2</totalRequests>
    </summary>
</batchResponse>

JSON:

{
    "formatVersion": "0.0.1",
    "batchItems": [
        {
            "statusCode": 200,
            "response": {"formatVersion":"0.0.12","copyright":"...","privacy":"...","routes":[{"summary":{"lengthInMeters":223,"travelTimeInSeconds":66,"trafficDelayInSeconds":0,"departureTime":"2016-04-22T13:43:25+02:00","arrivalTime":"2016-04-22T13:44:31+02:00"},"legs":[{"summary":{"lengthInMeters":223,"travelTimeInSeconds":66,"trafficDelayInSeconds":0,"departureTime":"2016-04-22T13:43:25+02:00","arrivalTime":"2016-04-22T13:44:31+02:00"},"points":[{"latitude":52.36006,"longitude":4.85109},{"latitude":52.36084,"longitude":4.85106},{"latitude":52.36176,"longitude":4.85104},{"latitude":52.36176,"longitude":4.85056}]}],"sections":[{"startPointIndex":0,"endPointIndex":3,"travelMode":"car"}]}]}
        },
        {
            "statusCode": 400,
            "response": {"formatVersion":"0.0.12","copyright":"...","privacy":"...","error":{"description":"Invalid travel mode value: [teleport]"}}
        }
    ],
    "summary": {
        "successfulRequests": 1,
        "totalRequests": 2
    }
}

 

Example of an error response

The submission endpoint will return error responses with content type depending on the outputFormat parameter. Result download endpoint error responses will be always xml.

XML:

<?xml version="1.0" encoding="utf-8"?>
<batchResponse xmlns="http://api.tomtom.com/batch" formatVersion="0.0.1">
    <error description="Required String parameter 'key' is not present"/>
</batchResponse>

JSON:

{
  "formatVersion": "0.0.1",
  "error": {
    "description": "Required String parameter 'key' is not present"
  }
}

Structure of an error response

Field Description
batchResponse Root element of the batch error response.
formatVersion Version of batch error response format.
error Element describing the error.
description Description string.

 

Response Codes

Code Meaning and Possible Causes
200 OK: The batch job has completed. Results are streamed to 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 result download later.
400 Bad Request: Missing required parameters or parameters didn't pass validation.
403 Forbidden: The API key is missing, inactive, invalid, not entitled to use the Batch Routing API, over QPS or over QPD. Can also occur when using HTTP instead of HTTPS.
404 Not Found: the requested resource could not be found, for example a batch with provided batchId does not exist.
405 Method Not Allowed: the client used a HTTP method other than GET or POST.
408 Request timeout.
414 Requested uri is too long.
500 An error occured while processing the request. Please try again later.
502 Internal network connectivity issue.
503 Service currently unavailable.
504 Internal network connectivity issue or a request that has taken too long to complete.
596 Service not found.

 

Response Headers

The table below lists HTTP response headers of particular interest to the Routing service clients.

Header Description Values
Location Indicates the location where the batch results can be downloaded. Available only if the response is HTTP 202. URI
Access-Control-Expose-Headers A comma separated list of HTTP header names that browsers are allowed to access. Content-Length
Access-Control-Allow-Origin A header instructing browsers to allow customer websites to contact the Batch Routing service. *
Content-Encoding The Batch Routing service supports HTTP compression, if requested by the client. gzip
Content-Type The format of the response as chosen by the client (see the contentType request parameter).
  • application/xml; charset=utf-8
  • application/json; charset=utf-8