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

PricingContact
Search API
Get your key

Asynchronous Batch Download

 

Service version: 2
Last edit: 2019.02.19

On this page

Purpose

This endpoint fetches results of the Asynchronous batch processing.

  • It responds with HTTP 200 and the batch results assuming batch processing has completed, or HTTP 202 Accepted if the batch is still being processed.
  • HTTP 202 Accepted will be obtained after 120 seconds, and then the client should retry the Request by following the Location header.
  • An HTTP 200 Response does not indicate that every batch item succeeded, but only that the batch calculation was completed.
  • Detailed information about the success or failure of the individual requests within the batch is provided in the HTTP 200 response.

The Batch download endpoint GET Request is a blocking long poll request.

Request data

HTTPS method: GET

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/batchId?key=*****

Example

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

HTTP Request headers

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

Required headers
Note: There are no required headers in this endpoint.
Optional headers
Header Description
Accept-Encoding
string		 Should contain 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).
  • If specified, it is replicated in the Tracking-ID Response header.

Value: Tracking-ID

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		 The 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.
batchId
string		 Unique id of the batch. Returned in the HTTP Location header of the Batch Submission Response.
Value: A unique ID generated by the submission.
Optional parameters
Note: There are no optional parameters in this endpoint.

▲ Return to top

Response data

HTTP Response status codes

Code Meaning and Possible Causes
200 OK: The batch job has completed. Results are streamed to the client.
202 Accepted: The Request has been accepted for processing, but the processing has not been completed. A Location header is added to the Response containing a link to retry later.
400 Bad Request: Missing required parameters or parameters didn't pass validation.
403 Forbidden: The API key is missing, inactive, invalid, not entitled to use the Batch Search API, over QPS, or over QPD. Can also occur when using HTTP instead of HTTPS.
404 Not Found: The requested resource could not be found, for example a batch provided with a batchId does not exist.
405 Method Not Allowed: The client used a HTTP method other than GET.
408 Request timeout.
414 Requested URI is too long.
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. Available only if the response is HTTP 202.
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.
Value: string

▲ Return to top

Successful Response structure

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

XML Response

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

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

▲ Return to top

Successful Response fields

Field Description
batchResponse
object		 Root element of the batch Response.
successfulRequests
string		 Number of successful batch item requests.
totalRequests
string		 Total number of items in batch Request.
batchItems
array		 A set of batch items processing results.
batchItem
object		 Contains results of processing of a single batch item.
statusCode
string		 Status code of a Response from the underlying Search API endpoint for given batch item.
response
object		 Content of the Response from the underlying Search API endpoint for 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
object		 Summary of the batch Request.

▲ Return to top

Successful Response examples

The following code blocks in XML and JSON contain a complete example of a Response to a batch Request for three queries to the Fuzzy Search API.

  • Two of the batch items were successfully executed resulting in an HTTP 200 response, while one failed with an HTTP 400 error due to the use of an incorrect query parameter.
  • Note that batch success indicates that each batch item was executed, not that each batch item executed successfully.

Click to expand/collapse the following 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>
        <response>
          <summary>
            <query>lodz</query>
            <queryType>NON_NEAR</queryType>
            <queryTime>95</queryTime>
            <numResults>1</numResults>
            <offset>0</offset>
            <totalResults>363</totalResults>
            <fuzzyLevel>1</fuzzyLevel>
          </summary>
          <results>
            <item>
              <type>Geography</type>
              <id>PL/GEO/p0/4455</id>
              <score>5.98</score>
              <info>search:decarta:ta:616013002038177-PL</info>
              <address>
                <municipality>Lodz</municipality>
                <countrySecondarySubdivision>Łódź</countrySecondarySubdivision>
                <countrySubdivision>Łódzkie</countrySubdivision>
                <countryCode>PL</countryCode>
                <country>Poland</country>
                <countryCodeISO3>POL</countryCodeISO3>
                <freeformAddress>Lodz</freeformAddress>
              </address>
              <position>
                <lat>51.75905</lat>
                <lon>19.4586</lon>
              </position>
            </item>
          </results>
        </response>
      </response>
    </batchItem>
    <batchItem>
      <statusCode>200</statusCode>
      <response>
        <response>
          <summary>
            <query>restaurant amsterdam</query>
            <queryType>NON_NEAR</queryType>
            <queryTime>186</queryTime>
            <numResults>3</numResults>
            <offset>0</offset>
            <totalResults>3731</totalResults>
            <fuzzyLevel>1</fuzzyLevel>
          </summary>
          <results>
            <item>
              <type>POI</type>
              <id>AU/POI/p0/261806</id>
              <score>7.5</score>
              <info>search:decarta:ta:036001105620466-AU</info>
              <poi>
                <name>Nieuw Amsterdam</name>
                <categories>
                  <item>restaurant</item>
                </categories>
                <classifications>
                  <item>
                    <code>RESTAURANT</code>
                    <names>
                      <item>
                        <nameLocale>en-US</nameLocale>
                        <name>restaurant</name>
                      </item>
                    </names>
                  </item>
                </classifications>
              </poi>
              <address>
                <streetNumber>112</streetNumber>
                <streetName>Hardware Street</streetName>
                <municipalitySubdivision>Melbourne CBD</municipalitySubdivision>
                <municipality>Melbourne</municipality>
                <countrySecondarySubdivision>Melbourne</countrySecondarySubdivision>
                <countrySubdivision>Vic</countrySubdivision>
                <postalCode>3000</postalCode>
                <countryCode>AU</countryCode>
                <country>Australia</country>
                <countryCodeISO3>AUS</countryCodeISO3>
                <freeformAddress>Hardware Street 112, Melbourne CBD Melbourne, Vic, 3000</freeformAddress>
              </address>
              <position>
                <lat>-37.8123</lat>
                <lon>144.96068</lon>
              </position>
            </item>
            <item>
              <type>POI</type>
              <id>BE/POI/p0/61115</id>
              <score>7.5</score>
              <info>review:decarta:ta:056001000066087-BE</info>
              <poi>
                <name>Borse van Amsterdam</name>
                <url>www.borsevanamsterdam.be</url>
                <categories>
                  <item>belgian</item>
                  <item>important tourist attraction</item>
                  <item>restaurant</item>
                </categories>
                <classifications>
                  <item>
                    <code>RESTAURANT</code>
                    <names>
                      <item>
                        <nameLocale>en-US</nameLocale>
                        <name>belgian</name>
                      </item>
                      <item>
                        <nameLocale>en-US</nameLocale>
                        <name>restaurant</name>
                      </item>
                    </names>
                  </item>
                  <item>
                    <code>IMPORTANT_TOURIST_ATTRACTION</code>
                    <names>
                      <item>
                        <nameLocale>en-US</nameLocale>
                        <name>important tourist attraction</name>
                      </item>
                    </names>
                  </item>
                </classifications>
              </poi>
              <address>
                <streetNumber>26</streetNumber>
                <streetName>Grote Markt</streetName>
                <municipalitySubdivision>Aalst</municipalitySubdivision>
                <municipality>Aalst</municipality>
                <countrySecondarySubdivision>Oost-Vlaanderen</countrySecondarySubdivision>
                <countryTertiarySubdivision>Aalst</countryTertiarySubdivision>
                <countrySubdivision>Vlaams Gewest</countrySubdivision>
                <postalCode>9300</postalCode>
                <countryCode>BE</countryCode>
                <country>Belgium</country>
                <countryCodeISO3>BEL</countryCodeISO3>
                <freeformAddress>Grote Markt 26, 9300 Aalst</freeformAddress>
              </address>
              <position>
                <lat>50.93852</lat>
                <lon>4.03821</lon>
              </position>
            </item>
            <item>
              <type>POI</type>
              <id>BG/POI/p0/11627</id>
              <score>7.5</score>
              <info>search:decarta:ta:100009000014937-BG</info>
              <poi>
                <name>Amsterdam</name>
                <phone>+(359)-(87)-8868962</phone>
                <categories>
                  <item>restaurant</item>
                </categories>
                <classifications>
                  <item>
                    <code>RESTAURANT</code>
                    <names>
                      <item>
                        <nameLocale>en-US</nameLocale>
                        <name>restaurant</name>
                      </item>
                    </names>
                  </item>
                </classifications>
              </poi>
              <address>
                <streetNumber>10</streetNumber>
                <streetName>улица К. Стоилов</streetName>
                <municipalitySubdivision>Plovdiv</municipalitySubdivision>
                <municipality>Пловдив</municipality>
                <countrySecondarySubdivision>Пловдив</countrySecondarySubdivision>
                <postalCode>4000</postalCode>
                <countryCode>BG</countryCode>
                <country>Bulgaria</country>
                <countryCodeISO3>BGR</countryCodeISO3>
                <freeformAddress>улица К. Стоилов 10, 4000 Plovdiv (Пловдив)</freeformAddress>
              </address>
              <position>
                <lat>42.14805</lat>
                <lon>24.7491</lon>
              </position>
            </item>
          </results>
        </response>
      </response>
    </batchItem>
    <batchItem>
      <statusCode>400</statusCode>
      <response>
        <response>
          <errorText>Error parsing 'maxFuzzyLevel': 'asd' is not a valid integer</errorText>
          <message>Error parsing 'maxFuzzyLevel': 'asd' is not a valid integer</message>
          <httpStatusCode>400</httpStatusCode>
        </response>
      </response>
    </batchItem>
  </batchItems>
  <summary>
    <successfulRequests>2</successfulRequests>
    <totalRequests>3</totalRequests>
  </summary>
</batchResponse>

JSON Response example

{
  "formatVersion": "0.0.1",
  "batchItems": [
    {
      "statusCode": 200,
      "response": {
        "summary": {
          "query": "lodz",
          "queryType": "NON_NEAR",
          "queryTime": 101,
          "numResults": 1,
          "offset": 0,
          "totalResults": 363,
          "fuzzyLevel": 1
        },
        "results": [
          {
            "type": "Geography",
            "id": "PL/GEO/p0/4455",
            "score": 5.98,
            "info": "search:decarta:ta:616013002038177-PL",
            "address": {
              "municipality": "Lodz",
              "countrySecondarySubdivision": "Łódź",
              "countrySubdivision": "Łódzkie",
              "countryCode": "PL",
              "country": "Poland",
              "countryCodeISO3": "POL",
              "freeformAddress": "Lodz"
            },
            "position": {
              "lat": 51.75905,
              "lon": 19.4586
            }
          }
        ]
      }
    },
    {
      "statusCode": 200,
      "response": {
        "summary": {
          "query": "restaurant amsterdam",
          "queryType": "NON_NEAR",
          "queryTime": 186,
          "numResults": 3,
          "offset": 0,
          "totalResults": 3731,
          "fuzzyLevel": 1
        },
        "results": [
          {
            "type": "POI",
            "id": "AU/POI/p0/261806",
            "score": 7.5,
            "info": "search:decarta:ta:036001105620466-AU",
            "poi": {
              "name": "Nieuw Amsterdam",
              "categories": [
                "restaurant"
              ],
              "classifications": [
                {
                  "code": "RESTAURANT",
                  "names": [
                    {
                      "nameLocale": "en-US",
                      "name": "restaurant"
                    }
                  ]
                }
              ]
            },
            "address": {
              "streetNumber": "112",
              "streetName": "Hardware Street",
              "municipalitySubdivision": "Melbourne CBD",
              "municipality": "Melbourne",
              "countrySecondarySubdivision": "Melbourne",
              "countrySubdivision": "Vic",
              "postalCode": "3000",
              "countryCode": "AU",
              "country": "Australia",
              "countryCodeISO3": "AUS",
              "freeformAddress": "Hardware Street 112, Melbourne CBD Melbourne, Vic, 3000"
            },
            "position": {
              "lat": -37.8123,
              "lon": 144.96068
            }
          },
          {
            "type": "POI",
            "id": "BE/POI/p0/61115",
            "score": 7.5,
            "info": "review:decarta:ta:056001000066087-BE",
            "poi": {
              "name": "Borse van Amsterdam",
              "url": "www.borsevanamsterdam.be",
              "categories": [
                "belgian",
                "important tourist attraction",
                "restaurant"
              ],
              "classifications": [
                {
                  "code": "RESTAURANT",
                  "names": [
                    {
                      "nameLocale": "en-US",
                      "name": "belgian"
                    },
                    {
                      "nameLocale": "en-US",
                      "name": "restaurant"
                    }
                  ]
                },
                {
                  "code": "IMPORTANT_TOURIST_ATTRACTION",
                  "names": [
                    {
                      "nameLocale": "en-US",
                      "name": "important tourist attraction"
                    }
                  ]
                }
              ]
            },
            "address": {
              "streetNumber": "26",
              "streetName": "Grote Markt",
              "municipalitySubdivision": "Aalst",
              "municipality": "Aalst",
              "countrySecondarySubdivision": "Oost-Vlaanderen",
              "countryTertiarySubdivision": "Aalst",
              "countrySubdivision": "Vlaams Gewest",
              "postalCode": "9300",
              "countryCode": "BE",
              "country": "Belgium",
              "countryCodeISO3": "BEL",
              "freeformAddress": "Grote Markt 26, 9300 Aalst"
            },
            "position": {
              "lat": 50.93852,
              "lon": 4.03821
            }
          },
          {
            "type": "POI",
            "id": "BG/POI/p0/11627",
            "score": 7.5,
            "info": "search:decarta:ta:100009000014937-BG",
            "poi": {
              "name": "Amsterdam",
              "phone": "+(359)-(87)-8868962",
              "categories": [
                "restaurant"
              ],
              "classifications": [
                {
                  "code": "RESTAURANT",
                  "names": [
                    {
                      "nameLocale": "en-US",
                      "name": "restaurant"
                    }
                  ]
                }
              ]
            },
            "address": {
              "streetNumber": "10",
              "streetName": "улица К. Стоилов",
              "municipalitySubdivision": "Plovdiv",
              "municipality": "Пловдив",
              "countrySecondarySubdivision": "Пловдив",
              "postalCode": "4000",
              "countryCode": "BG",
              "country": "Bulgaria",
              "countryCodeISO3": "BGR",
              "freeformAddress": "улица К. Стоилов 10, 4000 Plovdiv (Пловдив)"
            },
            "position": {
              "lat": 42.14805,
              "lon": 24.7491
            }
          }
        ]
      }
    },
    {
      "statusCode": 400,
      "response": {
          "errorText": "Error parsing 'maxFuzzyLevel': 'asd' is not a valid integer",
          "message": "Error parsing 'maxFuzzyLevel': 'asd' is not a valid integer",
          "httpStatusCode": 400
      }
    }
  ],
  "summary": {
    "successfulRequests": 2,
    "totalRequests": 3
  }
}

▲ Return to top

Other Search suite API responses

For details on the particular Search suite API response's structure, consult the following, respective Search API suite documentation pages.

Error Response example

The result download endpoint error responses will be always XML.

XML example

<?xml version="1.0" encoding="UTF-8"?>
<batchResponse xmlns="http://api.tomtom.com/batch" formatVersion="0.0.1">
  <error description="Batch not found for provided id."/>
</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.

▲ Return to top