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

Synchronous Batch

 

Service version: 1
Last edit: 2019.11.08

On this page

Purpose

The Synchronous Batch endpoint allows you to submit a new batch for synchronous processing. It responds with a batch processing result, or a HTTP 408 Request timeout error if the processing time exceeds 60 seconds.

Request data

HTTP Method: POST

URL format

For ease of viewing and identification:

  • Required constants and parameters are shown in bold text.
  • Optional parameters are shown in plain text.
https://baseURL/routing/versionNumber/batch/sync/outputFormat?key=Your_API_Key

Example

https://api.tomtom.com/routing/1/batch/sync/xml?key=Your_API_Key

▲ Return to top

HTTP Request headers

The following table describes HTTP headers of particular interest to Batch Routing service clients.

Required headers
Header Description
Content-Type
String
Specifies the MIME type of the body of the Request. It may be:

  • application/xml
  • application/json
Optional headers
Header Description
Accept-Encoding
string
Should contain a list of encodings acceptable by the client. Used to demand a compressed Response.
Value: gzip
Tracking-ID
string
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 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.

▲ Return to top

Request parameters

The following data 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
Parameter Description
baseURL
string
Base URL for calling the API:
Value: api.tomtom.com
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 parameters
Parameter Description
outputFormat
string
The content type of the Response structure.
Default value: xml
Other value: json

▲ Return to top

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)

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

POST body (JSON)

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

POST body fields

Field Description
batchRequest Root element of the Request.
Value: The XML root element.
batchItems
array
A set of batch items.
Value: The maximum number of batch items for an Synchronous API is 100.
batchItem A single batch item.
Value: One batch item.
query A 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.
  • When posting XML to the Batch Routing service the <query> element values must be valid XML (e.g., the & character must be replaced by a predefined XML entity &amp;). More information is in the List of XML character entity references.
  • When posting JSON to the Batch Routing service, the query string values must be properly escaped (e.g., a " character should be escaped with a \ (backslash)). More information is available in RFC 7159.
  • 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.
post Contains 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 the XML format if Content-Type is set to application/xml.
  • Please refer to 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.

▲ Return to top

POST body examples

Click to expand/collapse the following examples:

Mixed endpoint examples

XML body example

<?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=fastest&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=fastest&amp;traffic=true&amp;departAt=now</query>
    </batchItem>
    <batchItem>
      <query>/calculateRoute/52.23292,21.06179:43.29379,17.01963/xml</query>
      <post>
        <postData>
          <avoidVignette>
            AUS,CHE
          </avoidVignette>
        </postData>
      </post>
    </batchItem>
    <batchItem>
      <query>/calculateReachableRange/52.36187528311709,4.850560426712036/xml?fuelBudgetInLiters=20&amp;constantSpeedConsumptionInLitersPerHundredkm=50,6</query>
      <post>
        <postData>
          <avoidVignette>
            NLD
          </avoidVignette>
        </postData>
      </post>
    </batchItem>
    <batchItem>
      <query>/calculateReachableRange/52.36173769505809,4.852169752120972/xml?timeBudgetInSec=1800</query>
    </batchItem>
  </batchItems>
</batchRequest>

JSON body example

{
  "batchItems": [
    {"query": "/calculateRoute/52.36006039665441,4.851064682006836:52.36187528311709,4.850560426712036/json?travelMode=car&routeType=fastest&traffic=true&departAt=now&maxAlternatives=0"},
    {"query": "/calculateRoute/52.36241907934766,4.850034713745116:52.36173769505809,4.852169752120972/json?travelMode=teleport&routeType=fastest&traffic=true&departAt=now"},
    {
      "query": "/calculateRoute/52.23292,21.06179:43.29379,17.01963/json",
      "post": {
        "avoidVignette": [
          "AUS",
          "CHE"
        ]
      }
    },
    {
      "query": "/calculateReachableRange/52.36187528311709,4.850560426712036/json?fuelBudgetInLiters=20&constantSpeedConsumptionInLitersPerHundredkm=50,6",
      "post": {
        "avoidVignette": [
          "NLD"
        ]
      }
    },
    {"query": "/calculateReachableRange/52.36173769505809,4.852169752120972/json?timeBudgetInSec=1800"}
  ]
}

Calculate Route examples

XML body example

<?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=fastest&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=fastest&amp;traffic=true&amp;departAt=now</query>
    </batchItem>
    <batchItem>
      <query>/calculateRoute/52.23292,21.06179:43.29379,17.01963/xml</query>
      <post>
        <postData>
          <avoidVignette>
            AUS,CHE
          </avoidVignette>
        </postData>
      </post>
    </batchItem>
  </batchItems>
</batchRequest>

JSON body example

{
  "batchItems": [
    {"query": "/calculateRoute/52.36006039665441,4.851064682006836:52.36187528311709,4.850560426712036/json?travelMode=car&routeType=fastest&traffic=true&departAt=now&maxAlternatives=0"},
    {"query": "/calculateRoute/52.36241907934766,4.850034713745116:52.36173769505809,4.852169752120972/json?travelMode=teleport&routeType=fastest&traffic=true&departAt=now"},
    {
      "query": "/calculateRoute/52.23292,21.06179:43.29379,17.01963/json",
      "post": {
        "avoidVignette": [
          "AUS",
          "CHE"
        ]
      }
    }
  ]
}

Calculate Reachable Range examples

XML body example

<?xml version="1.0" encoding="utf-8"?>
<batchRequest>
  <batchItems>
    <batchItem>
      <query>/calculateReachableRange/52.36187528311709,4.850560426712036/xml?fuelBudgetInLiters=20&amp;constantSpeedConsumptionInLitersPerHundredkm=50,6</query>
      <post>
        <postData>
          <avoidVignette>
            NLD
          </avoidVignette>
        </postData>
      </post>
    </batchItem>
    <batchItem>
      <query>/calculateReachableRange/52.36173769505809,4.852169752120972/xml?timeBudgetInSec=1800</query>
    </batchItem>
  </batchItems>
</batchRequest>

JSON body example

{
  "batchItems": [
    {
      "query": "/calculateReachableRange/52.36187528311709,4.850560426712036/json?fuelBudgetInLiters=20&constantSpeedConsumptionInLitersPerHundredkm=50,6",
      "post": {
        "avoidVignette": [
          "NLD"
        ]
      }
    },
    {"query": "/calculateReachableRange/52.36173769505809,4.852169752120972/json?timeBudgetInSec=1800"}
  ]
}


▲ Return to top

Response data

HTTP Status codes

Code Meaning and Possible Causes
200 OK: The batch job has completed. Results are streamed to the client.
400 Bad Request:

  • Missing required parameters.
  • Exceeded maximum number of batch items.
  • Or, parameters did not pass validation.
403 Forbidden:

  • 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.
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 POST.
408 Request timeout: The request sent to the server took longer than it 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.

▲ Return to top

HTTP Response headers

The following table describes HTTP Response headers of particular interest to Batch service clients.

Header Description
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 the Responses if it is requested by the client 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/xml;charset=utf-8
  • 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.
  • 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.

▲ Return to top

Successful Response structure

Each Batch Response consists of one or more XML <batchItem> elements which correspond sequentially with the <batchItem> elements in the Request. Each <batchItem> element contains a successful Response from the invoked Routing API suite endpoint or a status code indicating why the batch item failed.

XML Response example

<?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 Response example

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

Successful Response fields

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

▲ Return to top

Successful Response examples

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

Click to expand/collapse the following XML and JSON successful Response examples

XML Response example

<?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>
    <batchItem>
      <statusCode>200</statusCode>
      <response>
        <calculateReachableRangeResponse xmlns="http://api.tomtom.com/routing" formatVersion="0.0.1">
          <copyright>...</copyright>
          <privacy>...</privacy>
          <reachableRange>
            <center latitude="52.36176" longitude="4.85056" />
            <boundary>
              <point latitude="52.78716" longitude="4.81318" />
              <point latitude="52.78983" longitude="4.79019" />
              <point latitude="52.78346" longitude="4.70485" />
              <point latitude="52.77541" longitude="4.67377" />
              <point latitude="52.73947" longitude="4.64530" />
              <point latitude="52.61481" longitude="4.64891" />
              <point latitude="52.61362" longitude="4.64887" />
              <point latitude="52.53855" longitude="4.65841" />
              <point latitude="52.49834" longitude="4.64125" />
              <point latitude="52.47165" longitude="4.60932" />
              <point latitude="52.46203" longitude="4.58628" />
              <point latitude="52.44705" longitude="4.59327" />
              <point latitude="52.37132" longitude="4.52544" />
              <point latitude="52.32164" longitude="4.57722" />
              <point latitude="52.26437" longitude="4.45996" />
              <point latitude="52.11393" longitude="4.28383" />
              <point latitude="51.01315" longitude="2.37788" />
              <point latitude="51.02757" longitude="2.42521" />
              <point latitude="50.43132" longitude="2.84907" />
              <point latitude="50.33847" longitude="2.92668" />
              <point latitude="50.34035" longitude="3.46896" />
              <point latitude="50.45216" longitude="3.76045" />
              <point latitude="50.48706" longitude="4.08585" />
              <point latitude="50.13129" longitude="4.49675" />
              <point latitude="50.49117" longitude="4.61820" />
              <point latitude="50.09545" longitude="5.13195" />
              <point latitude="50.05438" longitude="5.20811" />
              <point latitude="50.02166" longitude="5.69731" />
              <point latitude="50.07049" longitude="5.73492" />
              <point latitude="50.21669" longitude="6.23432" />
              <point latitude="50.11697" longitude="6.43576" />
              <point latitude="50.46513" longitude="6.70010" />
              <point latitude="50.37483" longitude="7.41121" />
              <point latitude="50.52358" longitude="7.67539" />
              <point latitude="50.87047" longitude="7.96531" />
              <point latitude="51.02269" longitude="7.82893" />
              <point latitude="51.54443" longitude="8.10810" />
              <point latitude="52.23340" longitude="9.25347" />
              <point latitude="52.86505" longitude="8.23947" />
              <point latitude="52.95622" longitude="8.56608" />
              <point latitude="53.18553" longitude="8.10646" />
              <point latitude="53.32431" longitude="6.87906" />
              <point latitude="53.24864" longitude="6.46143" />
              <point latitude="53.21977" longitude="5.98597" />
              <point latitude="53.20076" longitude="5.64319" />
              <point latitude="53.18381" longitude="5.45848" />
              <point latitude="53.03505" longitude="5.23428" />
              <point latitude="52.95193" longitude="5.07620" />
              <point latitude="52.77310" longitude="4.95600" />
              <point latitude="52.73059" longitude="4.89175" />
            </boundary>
          </reachableRange>
        </calculateReachableRangeResponse>
      </response>
    </batchItem>
    <batchItem>
      <statusCode>200</statusCode>
      <response>
        <calculateReachableRangeResponse xmlns="http://api.tomtom.com/routing" formatVersion="0.0.1">
          <copyright>...</copyright>
          <privacy>...</privacy>
          <reachableRange>
            <center latitude="52.36178" longitude="4.85216" />
            <boundary>
              <point latitude="52.55238" longitude="4.83100" />
              <point latitude="52.58994" longitude="4.81431" />
              <point latitude="52.61593" longitude="4.75696" />
              <point latitude="52.61907" longitude="4.73098" />
              <point latitude="52.60065" longitude="4.72924" />
              <point latitude="52.57070" longitude="4.69273" />
              <point latitude="52.56251" longitude="4.66643" />
              <point latitude="52.51827" longitude="4.65113" />
              <point latitude="52.51005" longitude="4.65357" />
              <point latitude="52.47165" longitude="4.60932" />
              <point latitude="52.46203" longitude="4.58628" />
              <point latitude="52.44705" longitude="4.59327" />
              <point latitude="52.36490" longitude="4.57865" />
              <point latitude="52.32644" longitude="4.58989" />
              <point latitude="52.27725" longitude="4.51188" />
              <point latitude="52.17816" longitude="4.40562" />
              <point latitude="52.13246" longitude="4.39854" />
              <point latitude="52.07782" longitude="4.40456" />
              <point latitude="52.12844" longitude="4.54478" />
              <point latitude="52.14059" longitude="4.65627" />
              <point latitude="52.13539" longitude="4.69158" />
              <point latitude="52.18747" longitude="4.76277" />
              <point latitude="52.24121" longitude="4.81595" />
              <point latitude="52.25268" longitude="4.82480" />
              <point latitude="52.22580" longitude="4.85207" />
              <point latitude="52.22231" longitude="4.86311" />
              <point latitude="52.11528" longitude="4.91272" />
              <point latitude="52.10137" longitude="4.91745" />
              <point latitude="52.15657" longitude="4.95490" />
              <point latitude="52.07171" longitude="5.03885" />
              <point latitude="52.03613" longitude="5.06388" />
              <point latitude="52.06045" longitude="5.09947" />
              <point latitude="52.12534" longitude="5.11099" />
              <point latitude="52.23269" longitude="5.04984" />
              <point latitude="52.17824" longitude="5.18006" />
              <point latitude="52.20486" longitude="5.27330" />
              <point latitude="52.21371" longitude="5.33380" />
              <point latitude="52.35807" longitude="5.35599" />
              <point latitude="52.41557" longitude="5.38758" />
              <point latitude="52.37996" longitude="4.97327" />
              <point latitude="52.39278" longitude="4.96466" />
              <point latitude="52.45905" longitude="5.03088" />
              <point latitude="52.49351" longitude="5.03124" />
              <point latitude="52.54294" longitude="5.02473" />
              <point latitude="52.65326" longitude="5.07318" />
              <point latitude="52.67429" longitude="5.07021" />
              <point latitude="52.72101" longitude="5.02531" />
              <point latitude="52.63597" longitude="4.95650" />
              <point latitude="52.54702" longitude="4.87765" />
              <point latitude="52.54899" longitude="4.86904" />
            </boundary>
          </reachableRange>
        </calculateReachableRangeResponse>
      </response>
    </batchItem>
  </batchItems>
  <summary>
    <successfulRequests>3</successfulRequests>
    <totalRequests>4</totalRequests>
  </summary>
</batchResponse>

JSON Response example

{
  "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]"
        }
      }
    },
    {
      "statusCode": 200,
      "response": {
        "formatVersion": "0.0.1",
        "copyright": "...",
        "privacy": "...",
        "reachableRange": {
          "center": {
            "latitude": 52.36176,
            "longitude": 4.85056
          },
          "boundary": [
            {
              "latitude": 52.78716,
              "longitude": 4.81318
            },
            {
              "latitude": 52.78983,
              "longitude": 4.79019
            },
            {
              "latitude": 52.78346,
              "longitude": 4.70485
            },
            {
              "latitude": 52.77541,
              "longitude": 4.67377
            },
            {
              "latitude": 52.73947,
              "longitude": 4.6453
            },
            {
              "latitude": 52.61481,
              "longitude": 4.64891
            },
            {
              "latitude": 52.61362,
              "longitude": 4.64887
            },
            {
              "latitude": 52.53855,
              "longitude": 4.65841
            },
            {
              "latitude": 52.49834,
              "longitude": 4.64125
            },
            {
              "latitude": 52.47165,
              "longitude": 4.60932
            },
            {
              "latitude": 52.46203,
              "longitude": 4.58628
            },
            {
              "latitude": 52.44705,
              "longitude": 4.59327
            },
            {
              "latitude": 52.37132,
              "longitude": 4.52544
            },
            {
              "latitude": 52.32164,
              "longitude": 4.57722
            },
            {
              "latitude": 52.26437,
              "longitude": 4.45996
            },
            {
              "latitude": 52.11393,
              "longitude": 4.28383
            },
            {
              "latitude": 50.98539,
              "longitude": 2.23052
            },
            {
              "latitude": 50.98863,
              "longitude": 2.35777
            },
            {
              "latitude": 50.43132,
              "longitude": 2.84907
            },
            {
              "latitude": 50.33847,
              "longitude": 2.92668
            },
            {
              "latitude": 50.22934,
              "longitude": 3.27133
            },
            {
              "latitude": 50.45216,
              "longitude": 3.76045
            },
            {
              "latitude": 50.48706,
              "longitude": 4.08585
            },
            {
              "latitude": 49.98206,
              "longitude": 4.51402
            },
            {
              "latitude": 50.49117,
              "longitude": 4.6182
            },
            {
              "latitude": 50.09545,
              "longitude": 5.13195
            },
            {
              "latitude": 49.91044,
              "longitude": 5.29447
            },
            {
              "latitude": 50.02166,
              "longitude": 5.69731
            },
            {
              "latitude": 50.07049,
              "longitude": 5.73492
            },
            {
              "latitude": 50.21669,
              "longitude": 6.23432
            },
            {
              "latitude": 50.11697,
              "longitude": 6.43576
            },
            {
              "latitude": 50.46513,
              "longitude": 6.7001
            },
            {
              "latitude": 50.37483,
              "longitude": 7.41121
            },
            {
              "latitude": 50.52358,
              "longitude": 7.67539
            },
            {
              "latitude": 50.87047,
              "longitude": 7.96531
            },
            {
              "latitude": 51.02269,
              "longitude": 7.82893
            },
            {
              "latitude": 51.54443,
              "longitude": 8.1081
            },
            {
              "latitude": 52.2334,
              "longitude": 9.25347
            },
            {
              "latitude": 52.86505,
              "longitude": 8.23947
            },
            {
              "latitude": 52.95622,
              "longitude": 8.56608
            },
            {
              "latitude": 53.18553,
              "longitude": 8.10646
            },
            {
              "latitude": 53.32431,
              "longitude": 6.87906
            },
            {
              "latitude": 53.24864,
              "longitude": 6.46143
            },
            {
              "latitude": 53.21977,
              "longitude": 5.98597
            },
            {
              "latitude": 53.20076,
              "longitude": 5.64319
            },
            {
              "latitude": 53.18381,
              "longitude": 5.45848
            },
            {
              "latitude": 53.03505,
              "longitude": 5.23428
            },
            {
              "latitude": 52.95193,
              "longitude": 5.0762
            },
            {
              "latitude": 52.7731,
              "longitude": 4.956
            },
            {
              "latitude": 52.73059,
              "longitude": 4.89175
            }
          ]
        }
      }
    },
    {
      "statusCode": 200,
      "response": {
        "formatVersion": "0.0.1",
        "copyright": "...",
        "privacy": "...",
        "reachableRange": {
          "center": {
            "latitude": 52.36178,
            "longitude": 4.85216
          },
          "boundary": [
            {
              "latitude": 52.55238,
              "longitude": 4.831
            },
            {
              "latitude": 52.58944,
              "longitude": 4.81481
            },
            {
              "latitude": 52.61593,
              "longitude": 4.75696
            },
            {
              "latitude": 52.61869,
              "longitude": 4.73182
            },
            {
              "latitude": 52.60065,
              "longitude": 4.72924
            },
            {
              "latitude": 52.5704,
              "longitude": 4.69259
            },
            {
              "latitude": 52.56248,
              "longitude": 4.66803
            },
            {
              "latitude": 52.51754,
              "longitude": 4.65152
            },
            {
              "latitude": 52.51005,
              "longitude": 4.65357
            },
            {
              "latitude": 52.47165,
              "longitude": 4.60932
            },
            {
              "latitude": 52.46203,
              "longitude": 4.58628
            },
            {
              "latitude": 52.44705,
              "longitude": 4.59327
            },
            {
              "latitude": 52.40392,
              "longitude": 4.54964
            },
            {
              "latitude": 52.34494,
              "longitude": 4.58513
            },
            {
              "latitude": 52.27725,
              "longitude": 4.51188
            },
            {
              "latitude": 52.17925,
              "longitude": 4.40661
            },
            {
              "latitude": 52.13387,
              "longitude": 4.40049
            },
            {
              "latitude": 52.08084,
              "longitude": 4.4085
            },
            {
              "latitude": 52.12844,
              "longitude": 4.54478
            },
            {
              "latitude": 52.14113,
              "longitude": 4.6569
            },
            {
              "latitude": 52.13626,
              "longitude": 4.69284
            },
            {
              "latitude": 52.18881,
              "longitude": 4.76185
            },
            {
              "latitude": 52.24121,
              "longitude": 4.81595
            },
            {
              "latitude": 52.25268,
              "longitude": 4.8248
            },
            {
              "latitude": 52.2258,
              "longitude": 4.85207
            },
            {
              "latitude": 52.22231,
              "longitude": 4.86311
            },
            {
              "latitude": 52.11528,
              "longitude": 4.91272
            },
            {
              "latitude": 52.10203,
              "longitude": 4.91813
            },
            {
              "latitude": 52.15657,
              "longitude": 4.9549
            },
            {
              "latitude": 52.07171,
              "longitude": 5.03885
            },
            {
              "latitude": 52.03868,
              "longitude": 5.06395
            },
            {
              "latitude": 52.06083,
              "longitude": 5.09541
            },
            {
              "latitude": 52.12659,
              "longitude": 5.1081
            },
            {
              "latitude": 52.23269,
              "longitude": 5.04984
            },
            {
              "latitude": 52.17824,
              "longitude": 5.18006
            },
            {
              "latitude": 52.20553,
              "longitude": 5.27285
            },
            {
              "latitude": 52.21432,
              "longitude": 5.33036
            },
            {
              "latitude": 52.35769,
              "longitude": 5.3551
            },
            {
              "latitude": 52.4155,
              "longitude": 5.38742
            },
            {
              "latitude": 52.37996,
              "longitude": 4.97327
            },
            {
              "latitude": 52.39278,
              "longitude": 4.96466
            },
            {
              "latitude": 52.45905,
              "longitude": 5.03088
            },
            {
              "latitude": 52.49351,
              "longitude": 5.03124
            },
            {
              "latitude": 52.54294,
              "longitude": 5.02473
            },
            {
              "latitude": 52.65356,
              "longitude": 5.07229
            },
            {
              "latitude": 52.67399,
              "longitude": 5.06906
            },
            {
              "latitude": 52.7202,
              "longitude": 5.02538
            },
            {
              "latitude": 52.63563,
              "longitude": 4.9565
            },
            {
              "latitude": 52.54702,
              "longitude": 4.87765
            },
            {
              "latitude": 52.54899,
              "longitude": 4.86904
            }
          ]
        }
      }
    }
  ],
  "summary": {
    "successfulRequests": 3,
    "totalRequests": 4
  }
}

▲ Return to top

Error Response

The error Response content type depends on the outputFormat parameter.

Error Response example (XML)

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<batchResponse xmlns="http://api.tomtom.com/batch" formatVersion="0.0.1">
  <error description="Validation of batch item 1 failed. Batch response format (XML) does not match content type of batch item query."/>
  <detailedError>
    <code>BadRequest</code>
    <message>Bad Request</message>
    <details>
      <detail>
        <code>MalformedBody</code>
        <message>Validation of batch item 1 failed. Batch response format (XML) does not match content type of batch item query.</message>
        <target>postBody</target>
      </detail>
    </details>
  </detailedError>
</batchResponse>

Error Response example (JSON)

{
  "formatVersion": "0.0.1",
  "error": {
    "description": "Validation of batch item 1 failed. Batch response format (JSON) does not match content type of batch item query."
  },
  "detailedError": {
    "code": "BadRequest",
    "message": "Bad Request",
    "details": {
      "code": "MalformedBody",
      "message": "Validation of batch item 1 failed. Batch response format (JSON) does not match content type of batch item query",
      "target": "postBody",
    }
  }
}

▲ Return to top

Error Response fields

Primary fields
Field Description
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
Field Description
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
Field Description
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
Field Description
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

▲ Return to top

Error code hierarchy

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 code Description
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
BadRequest

Top level code for Requests which ended with HTTP 400 Bad Request.

Possible root causes:

  • BadArgument
  • MalformedBody
BatchRequestTimeout Top level code for Requests which ended with HTTP 408 Request Timeout.
Calculating batch takes too long to complete using sync mode. Please recalculate using async mode.
IllegalParameter Unsupported request parameter was specified.
InvalidParameterValue The value of one of the parameters is invalid.
InternalServerError Top level code for Requests which ended with HTTP 500 Internal Server Error.
The service cannot handle the request right now, an unexpected condition was encountered.
MalformedBody POST body has unexpected format.
MissingRequiredParameter One of the required parameters was not provided.
NotFound Top level code for Requests which ended with HTTP 404 Not Found caused by providing incorrect Request path.
ServiceUnavailable Top level code for Requests which ended with HTTP 503 Service Unavailable.
The service cannot handle the request right now, this is certainly a temporary state.

▲ Return to Top

You are here