TomTom LogoDocs
Products
Resources
Pricing
Sign in
Routing API
Documentation
API Explorer

Synchronous batch

Service version: 1Last edit: 2022.10.01TomTom Maps

Purpose

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

Request data

HTTP 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

post
URL request format
https://{baseURL}/routing/{versionNumber}/batch/sync/json?key={Your_API_Key}

URL request example

post
URL request example
https://api.tomtom.com/routing/1/batch/sync/json?key={Your_API_Key}

curl request example

post
curl request example
curl -XPOST 'https://api.tomtom.com/routing/1/batch/sync/json?key={Your_API_Key}'

Request headers

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

Required headersDescription
Content-Type

Specifies the MIME type of the request body. Valid value: application/json.
Optional headersDescription
Accept-Encoding

Should contain a list of encodings acceptable to the client. Used to demand a compressed response.
Value: gzip

Tracking-ID

Specifies an identifier for the request.

  • Can be used to trace a call.

  • The value must match the regular expression '^[a-zA-Z0-9-]{1,100}$'.

  • An example of a format that matches this regular expression is UUID: (e.g., 9ac68072-c7a4-11e8-a8d5-f2801f1b9fd1 ). For details, see RFC 4122 .

  • If specified, it is replicated in the Tracking-ID response header.

  • Used for support purposes only and does not involve tracking you or your users.

Value: An identifier for the request.

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

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 request 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
JSON request body example
{
  "batchItems": [
    {"query": "..."},
    ...
    {
      "query": "...",
      "post": {...}
    }
  ]
}

POST request body fields

FieldDescription

batchItems
array

A set of batch items.
Value: The maximum number of batch items for an Synchronous API is 100.

query
string

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

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

  • Note that the callback parameter is not supported by Batch Routing. For detailed descriptions, see the documentation for the Calculate Route and Calculate Reachable Range services.

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.

  • Refer to the POST Data parameters section of Calculate Route and Calculate Reachable Range services documentation for detailed descriptions and examples of content for this field.

POST request body examples

post
Mixed endpoints 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"
    }
  ]
}
post
Calculate Route 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"
        ]
      }
    }
  ]
}
post
Calculate Reachable Range 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"
    }
  ]
}

Response data

HTTP status codes

Code Meaning & 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, or not entitled to use Batch Routing API, or has exceeded the allowed QPS (queries per second) or QPD (queries per day) limits.

  • Can also occur when using HTTP instead of HTTPS.
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.

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 has exceeded the allowed QPS (queries per second) limit.

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

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

  • Used for support purposes only. It does not involve tracking you or your users.

Value: An identifier for the request.

Successful response structure

Each batch response consists of one or more elements that correspond sequentially to the elements in the request. Each element contains a successful response from the invoked Routing API suite endpoint or a status code indicating why the batch item failed.

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

Successful response fields

FieldDescription
batchItemsA set of batch items processing results.
statusCode

Status code of a response from the underlying Routing API suite endpoint for the 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 the requested content type, the response will be wrapped to fit the requested content type.

summarySummary of the batch request.
successfulRequestsNumber of successful batch item requests.
totalRequestsTotal 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 
{
  "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
  }
}

Error response

JSON error response example
{
  "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"
    }
  }
}

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 detail 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 detail about this error.
innerError object

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

BadRequest

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

Possible root causes:

  • BadArgument

  • MalformedBody

BatchRequestTimeout

Top level code for requests which resulted in a HTTP 408 Request Timeout. Calculating batch takes too long to complete using sync mode. Please recalculate using async mode.

IllegalParameterUnsupported request parameter was specified.
InvalidParameterValueThe value of one of the parameters is invalid.
InternalServerError

Top level code for requests which resulted in an HTTP 500 Internal Server Error. The service cannot handle the request right now due to an unexpected condition.

MalformedBody

POST body has an unexpected format.

MissingRequiredParameterOne of the required parameters was not provided.
NotFound

Top level code for requests which resulted in a HTTP 404 Not Found caused by providing an incorrect request path.

ServiceUnavailable

Top level code for requests which resulted in an HTTP 503 Service Unavailable. The service cannot handle the request right now, this is usually a temporary state.