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

PricingContact
Search API
Get your key

Asynchronous Batch Submission

 

Service version: 2
Last edit: 2019.02.19

On this page

Purpose

This endpoint allows the submission of a new batch for asynchronous processing. It responds with a redirect to the location at which the batch results can be obtained when the batch processing has completed.

Request data

HTTPS 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/search/versionNumber/batch.outputFormat?key=*****&redirectMode=redirectMode>

Example

https://api.tomtom.com/search/2/batch.json?key=*****

▲ Return to top

HTTP Request headers

The following data table describes HTTP Request headers of particular interest to Batch Search service clients.

  • Required headers must be used or the call will fail.
  • Optional headers may be used.
Required headers
Header Description
Content-Type
string		 Specifies the MIME type of the body of the Request.
Values:

  • application/xml
  • application/json
Optional headers
Header Description
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.

Value: An identifier for the Request.

▲ Return to top

Request parameters

The following table describes the parameters that can be used in a Request.

  • Required parameters must be used or the call will fail.
  • Optional parameters may be used.
Required parameters
Parameter Description
baseURL
string		 Base URL for calling the API.
Value: api.tomtom.com
versionNumber
integer		 The service version number.
Value: The current value is 2.
key
string		 An API Key valid for the requested service.
Value: Your valid API Key.
outputFormat
string		 The content type of the Response structure.
Values:

  • json
  • xml
Optional parameters
Parameter Description
redirectMode
string		 Controls the HTTP code of the successful HTTP Response to the submission Request.

  • When set to auto, HTTP code 303 is returned.
    • The HTTP client may automatically redirect to the Download endpoint.
  • When set to manual, HTTP code 202 is returned.
    • The HTTP client will not automatically redirect to the Download endpoint.

In both cases the same Location header is included.
Default value: auto
Other value: manual

▲ Return to top

POST body examples

The POST body of a batch Request should contain a set of items which will be used to execute requests to the endpoints of the Search API suite.

Each batch Request can contain items corresponding to multiple API endpoints of the Search API suite. For each API, the same body structure applies and the specific parameters of each endpoint are expected to go into query elements.

Examples of mixed Search API suite query items inside of the batch Request body structures can be found below. For details on the particular API usage, consult the respective API documentation pages.

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 fields (XML)

Field Description
batchRequest Root element of the Request.
batchItems A set of batch items. The maximum number of batch items for an Asynchronous API is 10000.
batchItem A single batch item.
query A string used to build a Request to the API from the Search API suite.

  • It is a partial URL without protocol, base URL, service version, and API Key.
  • The output format must match the outputFormat parameter of the batch Request.
  • If a batch contains any Additional Data service item, the outputFormat parameter value must be set to json as the Additional Data service does not support the XML Response format.
  • A query must be properly URL-encoded.
  • For example, a Fuzzy Search query "Lodz, Mochnackiego 15/19" should be written as follows (XML format):
    <query>/search/Lodz%2C%20Mochnackiego%2015%2F19</query>
  • A sample online URL encoder can be found at: URL Encoder.

When posting XML to the Batch Search service, the <query> element values must be valid XML (e.g., the "&" character must be replaced by the predefined XML entity "&amp;"). More information is in the List of XML character entity references.
When posting JSON to the Batch Search service, the <query> string values must be properly escaped; e.g., the " character should be escaped with a \ (backslash). More information is available in RFC 7159.
post Contains data that is sent to the Geometry Search or Along Route Search services using the HTTP POST method.

  • These services accept POST data only in JSON format.
  • For batch submissions in the XML format, the <post> element must be also an appropriate JSON object.
  • A JSON object provided in a XML <post> element must be properly XML escaped or wrapped into a CDATA section. For example:
    {
  "geometryList":[
    {
      "type":"CIRCLE",
      "position":"51.5123443,-0.0909851",
      "radius":1000
    }
  ]
}

    For XML, it should be XML escaped, e.g., the " character must be replaced by the predefined XML entity &quot; as shown in the following JSON code example:

    {
  &quot;geometryList&quot;:[
    {
      &quot;type&quot;:&quot;CIRCLE&quot;,
      &quot;position&quot;:&quot;51.5123443,-0.0909851&quot;,
      &quot;radius&quot;:1000
    }
  ]
}

    Or it can be wrapped in a CDATA section:

    <![CDATA[
{
  "geometryList":[
    {
      "type":"CIRCLE",
      "position":"51.5123443,-0.0909851",
      "radius":1000
    }
  ]
}
]]>

POST body (JSON)

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

POST body example

Each batch Request can contain items corresponding to multiple API endpoints of the Search API suite. For each API, the same body structure applies and the specific parameters of each endpoint are expected to go into query elements.

Examples of mixed Search API suite query items inside of the batch Request body structures can be found below. For details on the particular API usage, consult the respective API documentation pages.

Click to expand/collapse the following examples.

XML body example

<?xml version="1.0" encoding="utf-8"?>
<batchRequest>
  <batchItems>
    <batchItem>
      <query>/poiSearch/rembrandt museum.xml</query>
    </batchItem>
    <batchItem>
      <query>/geometrySearch/restaurant.xml?geometryList=[{"type":"CIRCLE","position":"51.5123443,-0.0909851","radius":1000}]</query>
    </batchItem>
    <batchItem>
      <query>/geometrySearch/pizza.xml</query>
      <post>
        {
          "geometryList":[
            {
              "type":"CIRCLE",
              "position":"51.5123443,-0.0909851",
              "radius":1000
            }
          ]
        }
      </post>
    </batchItem>
    <batchItem>
      <query>/geometrySearch/pizza.xml</query>
      <post>
        <![CDATA[
        {
          "geometryList":[
            {
              "type":"CIRCLE",
              "position":"51.5123443,-0.0909851",
              "radius":1000
            }
          ]
        }
        ]]>
      </post>
    </batchItem>
    <batchItem>
      <query>/geometrySearch/pizza.xml</query>
      <post>
        <![CDATA[
        {
          "geometryList":[
            {
              "type":"CIRCLE",
              "position":"51.5123443,-0.0909851",
              "radius":1000
            }
          ]
        }
        ]]>
      </post>
    </batchItem>
    <batchItem>
      <query>/searchAlongRoute/restaurant.xml?maxDetourTime=10000</query>
      <post>
        <![CDATA[
        {
          "route":{
            "points":[
              {
                "lat":37.7524152343544,
                "lon":-122.43576049804686
              },
              {
                "lat":37.70660472542312,
                "lon":-122.43301391601562
              },
              {
                "lat":37.712059855877314,
                "lon":-122.36434936523438
              },
              {
                "lat":37.75350561243041,
                "lon":-122.37396240234374
              }
            ]
          }
        }
        ]]>
      </post>
    </batchItem>
    <batchItem>
      <query>/reverseGeocode/crossStreet/52.4781801,4.8884868.xml</query>
    </batchItem>
    <batchItem>
      <query>/search/lodz.xml?limit=10&idxSet=POI,PAD,Str,Xstr,Geo,Addr</query>
    </batchItem>
  </batchItems>
</batchRequest>

JSON body example

{
  "batchItems": [
    {"query": "/poiSearch/rembrandt museum.json"},
    {"query": "/geometrySearch/parking.json?geometryList=[{\"type\":\"CIRCLE\",\"position\":\"51.5123443,-0.0909851\",\"radius\":1000}]"},
    {
      "query": "/geometrySearch/pizza.json",
      "post": {
        "geometryList":[
          {
            "type":"CIRCLE",
            "position":"51.5123443,-0.0909851",
            "radius":1000
          }
        ]
      }
    },
    {
      "query": "/searchAlongRoute/restaurant.json",
      "post": {
        "route":{
          "points":[
            {
              "lat":37.7524152,
              "lon":-122.4357604
            },
            {
              "lat":37.7066047,
              "lon":-122.4330139
            },
            {
              "lat":37.7120598,
              "lon":-122.3643493
            },
            {
              "lat":37.7535056,
              "lon":-122.3739624
            }
          ]
        }
      }
    },
    {"query": "/reverseGeocode/crossStreet/52.4829893,4.9247074.json"},
    {"query": "/search/lodz.json?limit=10&idxSet=POI,PAD,Str,Xstr,Geo,Addr&maxFuzzyLevel=2"}
  ]
}


▲ Return to top

Response data

On a successful batch Request submission, the Batch Search service responds with a HTTP 303 redirect to the batch download endpoint. The response has a Location header with a link to that endpoint and no body.

HTTP Response status codes

Code Meaning and Possible Causes
202 Accepted: A HTTP Response with a Location header that points where the batch results can be obtained. This code is used when redirectMode is set to manual.
303 See Other: A HTTP Response with a Location header that points where the batch results can be obtained. This code is used when redirectMode is set to auto.
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 Search API over QPS or over QPD. It 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 an 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.
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

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 Search service.
Value: *
Content-Encoding The Batch Search 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. For details, see RFC 4122.

Value: TrackingID

▲ Return to top

Error Response example

The error Response content types depend on the outputFormat parameter.

XML example

<?xml version="1.0" encoding="utf-8"?>
  <batchResponse xmlns="http://api.tomtom.com/batch" formatVersion="0.0.1">
    <error description="Output format: csv is unsupported."/>
  </batchResponse>

Error Response fields

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

JSON example

{
  "formatVersion": "0.0.1",
  "error": {
    "description": "Output format: csv is unsupported."
  }
}

▲ Return to Top