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

Batch Search

Dispatch batches of requests to endpoints from the Search API
suite with ease.

Asynchronous and synchronous batch processing

You can call Batch Search APIs to run either synchronously or asynchronously.

Asynchronous API overview

The asynchronous API is appropriate for processing big volumes of relatively complex search requests. It allows
retrieval of processing results in a separate call (multiple downloads are possible). The asynchronous API is
optimized for reliability and is not expected to run into a timeout. A number of batch items is limited to 10000
for this API.

Data retention period notice

Please, be aware that batches processed by asynchronous API are available for download for 14 days, after which
request for results download will return 404 (Not Found) response.

Sequence of asynchronous API client actions

  1. Client sends a request to the asynchronous batch submission endpoint.
  2. The server will respond with one of the following:
  3. After getting an HTTP 202 or HTTP 303 response, the client should follow the redirect to the asynchronous
    batch download endpoint
    which is a blocking long poll request.
  4. When client calls the asynchronous batch download endpoint, then possible
    scenarios are:

    • Batch response is calculated before timeout (120 seconds). The client receives HTTP 200. Batch response
      is ready and it gets streamed to the client.
    • Batch response is not ready before timeout. The client receives HTTP 202. Batch request is accepted for
      processing. The client downloads batch results from the URL specified by the Location header
      (see point 3).

Synchronous API overview

The synchronous API is recommended for lightweight search requests. In such a case, when the service receives a
request, it will respond as soon as the batch items are calculated and there will be no possibility to retrieve the
results later on. The synchronous API will return a timeout error, if the request takes longer than 60
seconds
. A number of batch items is limited to 100 for this API.

Sequence of synchronous API client actions

  1. Client sends a request to the synchronous batch endpoint.
  2. The server will respond with one of the following:
    • HTTP 200 Batch processing result - the calculation is finished before timeout and the client downloads
      results straight away.
    • HTTP 408 Request timeout error, if the request takes longer than 60 seconds and cannot
      be finished in this timeframe.
    • HTTP another error (see synchronous batch HTTP status codes).

 

Asynchronous batch submission endpoint

This endpoint allows submitting 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.

Batch submission request

HTTP method and URL

POST https://<baseURL>/search/<versionNumber>/batch.<outputFormat>?key=<APIKEY>[&redirectMode=<redirectMode>]<

Example

https://api.tomtom.com/search/2/batch.xml?key=<APIKEY>

HTTP Headers

The table below describes HTTP request headers of particular interest to Batch Search service clients. Required
headers must be used or the call will fail. Optional headers, which are highlighted with [square
brackets]
, may be used. If there is a default value that will be assumed when an optional
header is not used, it is shown in the table.

Header Description Req'd? Values Default Value
Content-Type Specifies the MIME type of the body of the request. Yes
  • application/xml
  • application/json
[Tracking-ID] 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 RFC4122.

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

No

 

Parameters

The table below describes 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.

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 2. Yes 2
key Authorization key for access to the API. Yes API Key
outputFormat The content type of the response structure. Yes
  • xml
  • json
[redirectMode] Controls the HTTP code of the successful HTTP response to the submission request.

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

In both cases the same Location header is included.

No
  • auto
  • manual
auto

 

POST body

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

POST body format

XML:

<?xml version="1.0" encoding="utf-8"?>
<batchRequest>
    <batchItems>
        <batchItem>
            <query>...</query>
        </batchItem>
        ...
        <batchItem>
            <query>...</query>
            <post>...</post>
        </batchItem>
    </batchItems>
</batchRequest>

JSON:

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

POST body fields

Field Description
batchRequest Root element of the request.
batchItems A set of batch items. Maximum number of batch items for 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.

A query must be properly URL-encoded.
For example, a fuzzy search query "Lodz, Mochnackiego 15/19" should be written as
follows:

<query>/search/Lodz%2C%20Mochnackiego%2015%2F19</query>

A sample online URL encoder can be found here.

When posting XML to the Batch Search service the <query> element values must be valid XML
(e.g. & character must be replaced by predefined XML entity &amp;). More information in href="https://en.wikipedia.org/wiki/List_of_XML_and_HTML_character_entity_references#Predefined_entities_in_XML">List
of XML character entity references.

When posting JSON to the Batch Search service the <query> string values must be properly
escaped (e.g. " character should be escaped with \). More information is available in RFC7159.

post

Contains data that is sent to Geometry
Search
or Along Route
Search
services using 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. JSON object provided in XML post element must
be properly XML escaped or wrapped into a CDATA section. Example:

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

should be XML escaped, e.g. " character
must be replaced by predefined XML entity &quot;.

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

or wrapped in a CDATA section:

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

 

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.

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

XML:

<?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>
        {
          &quot;geometryList&quot;:[
            {
              &quot;type&quot;:&quot;CIRCLE&quot;,
              &quot;position&quot;:&quot;51.5123443,-0.0909851&quot;,
              &quot;radius&quot;: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&amp;idxSet=POI,PAD,Str,Xstr,Geo,Addr</query>
    </batchItem>
  </batchItems>
</batchRequest>

JSON:

{
  "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"}
  ]
}

 

Batch submission response

On a successful batch request submission the Batch Search service responds with an HTTP 303 redirect to batch
download endpoint. Response has a Location header with link to that endpoint and no body.

Response Codes

Code Meaning and Possible Causes
202

Accepted: a HTTP response with Location header, which 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 Location header, which 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
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, 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.
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.

 

HTTP Headers

Header Description Values
Location Indicates the location where the batch results can be downloaded. URI
target="_blank">Access-Control-Expose-Headers A comma separated list of HTTP header names that browsers are allowed to access. Content-Length
target="_blank">Access-Control-Allow-Origin A header instructing browsers to allow customer websites to contact the Batch Search service. *
Content-Encoding The Batch Search service applies gzip compression to the responses, if it is requested by the client
with the Accept-Encoding header.
gzip
Content-Type The format of the response as chosen by the client (see the contentType request
parameter).
  • application/xml; charset=utf-8
  • application/json; charset=utf-8
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.

 

 

Error response example

The submission endpoint will return error responses with content type depending on the outputFormat
parameter.

XML:

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

JSON:

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

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

 

Asynchronous batch download endpoint

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 s, then client should retry request by following the Location header. An HTTP
200 response does not indicate that every batch item succeeded, 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 GET request is a blocking long poll request.

Batch download request

HTTP method and URL

GET https://<baseURL>/search/<versionNumber>/batch/<batchId>?key=<APIKEY>

Example

https://api.tomtom.com/search/2/batch/<batchId>?key=<APIKEY>

HTTP Headers

The table below describes HTTP request headers of particular interest to Batch Search service clients. Required
headers must be used or the call will fail. Optional headers, which are highlighted with [square
brackets]
, may be used. If there is a default value that will be assumed when an optional
header is not used, it is shown in the table.

Header Description Req'd? Values Default Value
[Accept-Encoding] Should contain list of encodings acceptable by the client. Usually used to demand a compressed
response.
No gzip
[Tracking-ID] 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 RFC4122.

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

No

Parameters

The table below describes 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.

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 2. Yes 2
key Authorization key for access to the API. Yes API Key
batchId Unique id of the batch, returned in HTTP Location header of Batch
Submission response
.
Yes String

 

Batch download response

HTTP Status Codes

Code Meaning and Possible Causes
200 OK: The batch job has completed. Results are streamed to 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 with provided batchId
does not exist.
405 Method Not Allowed: the client used an 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.

 

HTTP Headers

The table below lists HTTP response headers of particular interest to the service clients.

Header Description Values
Location Indicates the location where the batch results can be downloaded. Available only if the response is
HTTP 202.
URI
target="_blank">Access-Control-Expose-Headers A comma separated list of HTTP header names that browsers are allowed to access. Content-Length
target="_blank">Access-Control-Allow-Origin A header instructing browsers to allow customer websites to contact the Batch Search service. *
Content-Encoding The Batch Search service applies gzip compression to the responses, if it is requested by the client
with the Accept-Encoding header.
gzip
Content-Type The format of the response as chosen by the client (see the contentType request
parameter).
  • application/xml; charset=utf-8
  • application/json; charset=utf-8
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.

 

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:

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

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

 

Successful response fields

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

 

Successful response example

Below you can find a complete example of a response to a batch request for three queries to the target="_blank">Fuzzy Search API. Two 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.

XML:

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

{
  "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
  }
}

Other Search API suite responses

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

  1. Fuzzy Search (link)
  2. POI Search (link)
  3. Category Search (link)
  4. Routed Search (link)
  5. Geometry Search (link)
  6. Nearby Search (link)
  7. Low Bandwidth Search (link)
  8. Geocode (link)
  9. Structured Geocode (link)
  10. Reverse Geocode (link)
  11. CrossStreet Lookup (link)

 

Error response example

Result download endpoint error responses will be always XML.

XML:

<?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 Description string.

 

Synchronous batch endpoint

This endpoint allows submitting a new batch for synchronous processing. It responds with a batch processing result
or an HTTP 408 Request timeout error, if processing time is exceeds 60 seconds.

Request

HTTP method and URL

POST https://<baseURL>/search/<versionNumber>/batch/sync.<outputFormat>?key=<APIKEY>

Example

https://api.tomtom.com/search/2/batch/sync.xml?key=<APIKEY>

HTTP Headers

The table below describes HTTP request headers of particular interest to Batch Search service clients. Required
headers must be used or the call will fail. Optional headers, which are highlighted with [square
brackets]
, may be used. If there is a default value that will be assumed when an optional
header is not used, it is shown in the table.

Header Description Req'd? Values Default Value
Content-Type Specifies the MIME type of the body of the request. Yes
  • application/xml
  • application/json
[Accept-Encoding] Should contain list of encodings acceptable by the client. Usually used to demand a compressed
response.
No gzip
[Tracking-ID] 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 RFC4122.

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

No

 

Parameters

The table below describes 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.

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 2. Yes 2
key Authorization key for access to the API. Yes API Key
[outputFormat] The content type of the response structure. No
  • xml
  • json
xml

 

POST body

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

POST body format

XML:

<?xml version="1.0" encoding="utf-8"?>
<batchRequest>
    <batchItems>
        <batchItem>
            <query>...</query>
        </batchItem>
        ...
        <batchItem>
            <query>...</query>
            <post>...</post>
        </batchItem>
    </batchItems>
</batchRequest>

JSON:

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

POST body fields

Field Description
batchRequest Root element of the request.
batchItems A set of batch items. Maximum number of batch items for synchronous API is 100.
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.

A query must be properly URL-encoded.
For example, a fuzzy search query "Lodz, Mochnackiego 15/19" should be written as
follows:

<query>/search/Lodz%2C%20Mochnackiego%2015%2F19</query>

A sample online URL encoder can be found here.

When posting XML to the Batch Search service the <query> element values must be valid XML
(e.g. & character must be replaced by predefined XML entity &amp;). More information in href="https://en.wikipedia.org/wiki/List_of_XML_and_HTML_character_entity_references#Predefined_entities_in_XML">List
of XML character entity references.

When posting JSON to the Batch Search service the <query> string values must be properly
escaped (e.g. " character should be escaped with \). More information is available in RFC7159.

post

Contains data that is sent to Geometry
Search
or Along Route
Search
services using 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. JSON object provided in XML post element must
be properly XML escaped or wrapped into a CDATA section. Example:

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

should be XML escaped, e.g. " character
must be replaced by predefined XML entity &quot;.

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

or wrapped in a CDATA section:

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

 

POST body example

XML:

<?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>
        {
          &quot;geometryList&quot;:[
            {
              &quot;type&quot;:&quot;CIRCLE&quot;,
              &quot;position&quot;:&quot;51.5123443,-0.0909851&quot;,
              &quot;radius&quot;: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&amp;idxSet=POI,PAD,Str,Xstr,Geo,Addr</query>
    </batchItem>
  </batchItems>
</batchRequest>

JSON:

{
  "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"}
  ]
}

 

Response

HTTP Status Codes

Code Meaning and Possible Causes
200 OK: The batch job has completed. Results are streamed to client.
400 Bad Request: Missing required parameters, exceeded maximum number of batch items 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, 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.
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.

 

HTTP Headers

The table below lists HTTP response headers of particular interest to the service clients.

Header Description Values
target="_blank">Access-Control-Expose-Headers A comma separated list of HTTP header names that browsers are allowed to access. Content-Length
target="_blank">Access-Control-Allow-Origin A header instructing browsers to allow customer websites to contact the Batch Search service. *
Content-Encoding The Batch Search service applies gzip compression to the responses, if it is requested by the client
with the Accept-Encoding header.
gzip
Content-Type The format of the response as chosen by the client (see the contentType request
parameter).
  • application/xml; charset=utf-8
  • application/json; charset=utf-8
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.

 

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:

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

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

Successful response fields

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

Successful response example

Below you can find a complete example of a response to a batch request for three queries to the target="_blank">Fuzzy Search API. Two 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.

XML:

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

{
  "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
  }
}

Other Search API suite responses

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

  1. Fuzzy Search (link)
  2. POI Search (link)
  3. Category Search (link)
  4. Routed Search (link)
  5. Geometry Search (link)
  6. Nearby Search (link)
  7. Low Bandwidth Search (link)
  8. Along Route Search (link)
  9. Geocode (link)
  10. Structured Geocode (link)
  11. Reverse Geocode (link)
  12. CrossStreet Lookup (link)

 

Error response example

The error responses content type depends on the outputFormat parameter.

XML:

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

JSON:

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

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