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

Online Routing Batch (legacy)


Enables users to send a batch of queries within one HTTP request.

The process is that you POST a JSON object containing an array of queries to the server. The server will respond with the results of all of your queries.

This feature is disabled by default for all apps, contact us for more information regarding the use of this feature. 
Batch requests have the following constraints:

  • The HTTP method must be POST.
  • The HTTP request Content-Type header must be set to application/json.
  • Batch requests for the following Online Routing services are supported:
  • The payload of a batch request is limited to 15 queries.
  • Each query within the payload will have a limit flag set to 1 (where appropriate).

Request

Format

Batch Route query:
POST https://<baseURL>/routing/<versionNumber>/batchRoute.<ext>?key=<apiKey>
Batch Route Eta query:
POST https://<baseURL>/routing/<versionNumber>/batchEtaRoute.<ext>?key=<apiKey>

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 0. Yes 0
ext Valid response formats are JSON, JSONP, JS or XML. Yes String
apiKey Your TomTom API Key. Yes String
payload

An array of queries. The following examples might make it clearer how the payload is similar but simplified from a regular request. For example: url encoding the payload is not necessary; the .json formatter is not necessary; query string parameters can be included.

A request to: https://api.tomtom.com/routing/0/ batchRoute.json?key=<apiKey>

{
  "payload" : [
    "37.336,-121.889/37.325,-121.899",
    "37.78900219348633, -122.39112854003905/37.79962738517166, -122.41584777832033"
  ]
}

A request to: https://api.tomtom.com/routing/0/ batchEtaRoute.json?key=<apiKey>

{
  "payload" : [
    "37.336,-121.889/37.325,-121.899",
    "37.78900219348633, -122.39112854003905/37.79962738517166, -122.41584777832033"
  ]
}
Yes JSON Array of strings

Response

Format

Response will be a JSON encoding of the batch of requests. The following is output generated by running the geocode batch from the above sample:

{
   "summary":{
      "status":"Processed",
      "queryTime":2230,
      "totalQueries":3,
      "totalResults":3
   },
   "results":[
      {
         "query":"4 N second st.",
         "result":{
            "summary":{
               "query":"4 N second st.",
               "queryType":"NON_NEAR",
               "queryTime":600,
               "numResults":1,
               "offset":0,
               "totalResults":6028,
               "fuzzyLevel":2
            },
            "results":[
               {
                  "type":"Point Address",
                  "id":17135204,
                  "score":8.9,
                  "address":{
                     "streetNumber":"4",
                     "streetName":"N 2nd St",
                     "municipalitySubdivision":"Reading",
                     "municipality":"Reading",
                     "countrySecondarySubdivision":"Berks",
                     "countryTertiarySubdivision":"Reading",
                     "countrySubdivision":"PA",
                     "postalCode":"19601",
                     "countryCode":"US",
                     "freeformAddress":"4 N 2nd St, Reading, PA 19601"
                  },
                  "position":{
                     "lat":"40.33586",
                     "lon":"-75.93376"
                  }
               }
            ]
         }
      },
      {
         "query":"4 N second st, suite 595.",
         "result":{
            "summary":{
               "query":"4 N second st, suite 595.",
               "queryType":"NON_NEAR",
               "queryTime":856,
               "numResults":1,
               "offset":0,
               "totalResults":9682,
               "fuzzyLevel":2
            },
            "results":[
               {
                  "type":"Point Address",
                  "id":17135204,
                  "score":8.9,
                  "address":{
                     "streetNumber":"4",
                     "streetName":"N 2nd St",
                     "municipalitySubdivision":"Reading",
                     "municipality":"Reading",
                     "countrySecondarySubdivision":"Berks",
                     "countryTertiarySubdivision":"Reading",
                     "countrySubdivision":"PA",
                     "postalCode":"19601",
                     "countryCode":"US",
                     "freeformAddress":"4 N 2nd St, Reading, PA 19601"
                  },
                  "position":{
                     "lat":"40.33586",
                     "lon":"-75.93376"
                  }
               }
            ]
         }
      },
      {
         "query":"4%20N%20second%20st?radius=100",
         "result":{
            "summary":{
               "query":"4 N second st",
               "queryType":"NON_NEAR",
               "queryTime":730,
               "numResults":1,
               "offset":0,
               "totalResults":6028,
               "fuzzyLevel":2
            },
            "results":[
               {
                  "type":"Point Address",
                  "id":17135204,
                  "score":8.9,
                  "address":{
                     "streetNumber":"4",
                     "streetName":"N 2nd St",
                     "municipalitySubdivision":"Reading",
                     "municipality":"Reading",
                     "countrySecondarySubdivision":"Berks",
                     "countryTertiarySubdivision":"Reading",
                     "countrySubdivision":"PA",
                     "postalCode":"19601",
                     "countryCode":"US",
                     "freeformAddress":"4 N 2nd St, Reading, PA 19601"
                  },
                  "position":{
                     "lat":"40.33586",
                     "lon":"-75.93376"
                  }
               }
            ]
         }
      }
   ]
}