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

Online Search 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 Search - Geocoding 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).



Batch Geocode query:
POST https://<baseURL>/search/<versionNumber>/batchGeocode.<ext>?key=<apiKey>
Batch Reverse Geocode query:
POST https://<baseURL>/search/<versionNumber>/batchReverseGeocode.<ext>?key=<apiKey>
Batch Structured Geocode query:
POST https://<baseURL>/search/<versionNumber>/batchStructuredGeocode.<ext>?key=<apiKey>


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

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 batchGeocode.json?key=<apiKey>

  "payload" : [
    "4 N second st.",
    "4 N second st, suite 595.",

A request to batchReverseGeocode.json?key=<apiKey>

  "payload" : [
    "37.337, -121.89"

A request to batchStructuredGeocode.json?key=<apiKey>

  "payload" : [
    "?postalCode=95113&municipality=San Jose&countryCode=US",
    "?streetNumber=4&postalCode=95113&municipality=San Jose&countryCode=US",
    "?streetNumber=4&streetName=N 2nd&postalCode=95113&municipality=San Jose&countryCode=US"
Yes JSON Array of strings



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