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

Synchronous Batch

 

Service version: 2
Last edit: 2019.09.13

On this page

Purpose

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

Request data

HTTPS method: POST

URL format

For ease of viewing and identification:

  • Required constants and parameters are shown in bold text.
  • Optional parameters are shown in plain text.
https://baseURL/search/<versionNumber>/batch/sync.<outputFormat>?key=<Your_API_Key>

Example

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

▲ Return to top

HTTP Request headers

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

Required headers
Header Description
Content-Type
string
Specifies the MIME type of the body of the Request.
Values:

  • application/xml
  • application/json
Optional headers
Header Description
Accept-Encoding
string
Should contain list of encodings acceptable by the client. Usually 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). For details check RFC 4122.
  • If specified, it is replicated in the Tracking-ID Response header.

Value: An identifier for the Request.

▲ Return to top

Request parameters

The following table describes the Request parameters.

  • Required parameters must be used or the call will fail.
  • Optional parameters may be used.
Required parameters
Parameter Description
baseURL
string
Base URL for calling the API
Value: api.tomtom.com
versionNumber
integer
The service version number.
Value: The current value is 2.
key
string
An API Key valid for the requested service.
Value: Your valid API Key.
outputFormat
string
The content type of the Response structure.
Default value: xml
Other value: json
Optional parameters
Note: There are no optional parameters in this endpoint.

▲ Return to top

Supported Search API suite endpoints

A list of Search API suite endpoints supported by the Batch Search service can be found below. For details regarding particular API usage, consult the following respective API documentation pages:

POST body

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

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

POST body (XML)

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

POST body (JSON)

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

POST body fields

Field Description
batchRequest Root element of the Request.
batchItems A set of batch items. The maximum number of batch items for a Synchronous API is 100.
batchItem A single batch item.
query A string used to build a request to one of the supported endpoints of the Search API suite.

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

When posting XML to the Batch Search service, the <query> element values must be valid XML (e.g., the "&" character must be replaced by the predefined XML entity "&amp;"). More information is in the List of XML character entity references.
When posting JSON to the Batch Search service the <query> string values must be properly escaped. For example, the " (double-quote) character should be escaped with a \ (back-slash). More information is available in RFC 7159.

post Contains data that is sent to the Geometry Search or Along Route Search services using the HTTP POST method.

  • These services accept POST data only in JSON format.
  • For batch submissions in XML format, the <post> element's value must also be an appropriate JSON object.
  • A JSON object provided in a XML <post> element must be valid XML, i.e., it has to be properly XML escaped or wrapped in a CDATA section if necessary.

▲ Return to top

POST body examples

Click to expand/collapse the following examples:

Mixed endpoint examples

XML body example

<?xml version="1.0" encoding="utf-8"?>
<batchRequest>
  <batchItems>
    <batchItem>
      <query>/poiSearch/rembrandt museum.xml</query>
    </batchItem>
    <batchItem>
      <query>/geometrySearch/restaurant.xml?geometryList=[{"type":"CIRCLE","position":"51.5123443,-0.0909851","radius":1000}]</query>
    </batchItem>
    <batchItem>
      <query>/geometrySearch/pizza.xml</query>
      <post>
        {
          "geometryList":[
            {
              "type": "CIRCLE",
              "position": "51.5123443,-0.0909851",
              "radius": 1000
            }
          ]
        }
      </post>
    </batchItem>
    <batchItem>
      <query>/searchAlongRoute/restaurant.xml?maxDetourTime=300</query>
      <post>
        {
          "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 body example

{
  "batchItems": [
    {"query": "/poiSearch/rembrandt museum.json"},
    {"query": "/geometrySearch/parking.json?geometryList=[{\"type\":\"CIRCLE\",\"position\":\"51.5123443,-0.0909851\",\"radius\":1000}]"},
    {
      "query": "/geometrySearch/pizza.json",
      "post": {
        "geometryList":[
          {
            "type": "CIRCLE",
            "position": "51.5123443,-0.0909851",
            "radius": 1000
          }
        ]
      }
    },
    {
      "query": "/searchAlongRoute/restaurant.json?maxDetourTime=300",
      "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"}
  ]
}

Fuzzy Search examples

XML body example

<?xml version="1.0" encoding="utf-8"?>
<batchRequest>
  <batchItems>
    <batchItem>
      <query>/search/lodz.xml?limit=10&amp;idxSet=POI,PAD,Str,Xstr,Geo,Addr</query>
    </batchItem>
    <batchItem>
      <query>/search/wroclaw.xml?limit=10&amp;idxSet=POI,PAD,Str,Xstr,Geo,Addr</query>
    </batchItem>
    <batchItem>
      <query>/search/berlin.xml?limit=10&amp;idxSet=POI,PAD,Str,Xstr,Geo,Addr</query>
    </batchItem>
  </batchItems>
</batchRequest>

JSON body example

{
  "batchItems": [
    {"query": "/search/lodz.json?limit=10&idxSet=POI,PAD,Str,Xstr,Geo,Addr"},
    {"query": "/search/wroclaw.json?limit=10&idxSet=POI,PAD,Str,Xstr,Geo,Addr"},
    {"query": "/search/berlin.json?limit=10&idxSet=POI,PAD,Str,Xstr,Geo,Addr"}
  ]
}

POI Search examples

XML body example

<?xml version="1.0" encoding="utf-8"?>
<batchRequest>
  <batchItems>
    <batchItem>
      <query>/poiSearch/rembrandt museum.xml</query>
    </batchItem>
    <batchItem>
      <query>/poiSearch/big ben.xml</query>
    </batchItem>
    <batchItem>
      <query>/poiSearch/colosseo.xml</query>
    </batchItem>
  </batchItems>
</batchRequest>

JSON body example

{
  "batchItems": [
    {"query": "/poiSearch/rembrandt museum.json"},
    {"query": "/poiSearch/big ben.json"},
    {"query": "/poiSearch/colosseo.json"}
  ]
}

Category Search examples

XML body example

<?xml version="1.0" encoding="utf-8"?>
<batchRequest>
  <batchItems>
    <batchItem>
      <query>/categorySearch/airport.xml?lat=52.229404&amp;lon=21.011422</query>
    </batchItem>
    <batchItem>
      <query>/categorySearch/restaurant.xml?lat=38.925518&amp;lon=76.990957</query>
    </batchItem>
    <batchItem>
      <query>/categorySearch/hotel.xml?lat=34.016308&amp;lon=-118.277123</query>
    </batchItem>
  </batchItems>
</batchRequest>

JSON body example

{
  "batchItems": [
    {"query": "/categorySearch/airport.json?lat=52.229404&lon=21.011422"},
    {"query": "/categorySearch/restaurant.json?lat=38.925518&lon=76.990957"},
    {"query": "/categorySearch/hotel.json?lat=34.016308&lon=-118.277123"}
  ]
}

Geometry Search examples

XML body example

<?xml version="1.0" encoding="utf-8"?>
<batchRequest>
  <batchItems>
    <batchItem>
      <query>/geometrySearch/restaurant.xml?geometryList=[{"type":"CIRCLE","position":"51.5123443,-0.0909851","radius":1000}]</query>
    </batchItem>
    <batchItem>
      <query>/geometrySearch/pizza.xml</query>
      <post>
        {
          "geometryList":[
            {
              "type": "CIRCLE",
              "position": "51.5123443,-0.0909851",
              "radius": 1000
            }
          ]
        }
      </post>
    </batchItem>
  </batchItems>
</batchRequest>

JSON body example

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

Nearby Search examples

XML body example

<?xml version="1.0" encoding="utf-8"?>
<batchRequest>
  <batchItems>
    <batchItem>
      <query>/nearbySearch/.xml?lat=40.702594&amp;lon=-74.045358&amp;radius=2000</query>
    </batchItem>
    <batchItem>
      <query>/nearbySearch/.xml?lat=41.774831&amp;lon=-87.771554&amp;radius=2000</query>
    </batchItem>
    <batchItem>
      <query>/nearbySearch/.xml?lat=48.141307&amp;lon=17.117647&amp;radius=2000</query>
    </batchItem>
  </batchItems>
</batchRequest>

JSON body example

{
  "batchItems": [
    {"query": "/nearbySearch/.json?lat=40.702594&lon=-74.045358&radius=2000"},
    {"query": "/nearbySearch/.json?lat=41.774831&lon=-87.771554&radius=2000"},
    {"query": "/nearbySearch/.json?lat=48.141307&lon=17.117647&radius=2000"}
  ]
}

Along Route Search examples

XML body example

<?xml version="1.0" encoding="utf-8"?>
<batchRequest>
  <batchItems>
    <batchItem>
      <query>/searchAlongRoute/restaurant.xml?maxDetourTime=300</query>
      <post>
        {
          "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>/searchAlongRoute/restaurant.xml?maxDetourTime=300</query>
      <post>
        {
          "route": {
            "points": [
              {
                "lat": 48.19871,
                "lon": 16.36319
              },
              {
                "lat": 48.19843,
                "lon": 16.36262
              },
              {
                "lat": 48.19824,
                "lon": 16.36226
              },
              {
                "lat": 48.19788,
                "lon": 16.3615
              }
            ]
          }
        }
      </post>
    </batchItem>
  </batchItems>
</batchRequest>

JSON body example

{
  "batchItems": [
    {
      "query": "/searchAlongRoute/restaurant.json?maxDetourTime=300",
      "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": "/searchAlongRoute/restaurant.json?maxDetourTime=300",
      "post": {
        "route": {
          "points": [
            {
              "lat": 48.19871,
              "lon": 16.36319
            },
            {
              "lat": 48.19843,
              "lon": 16.36262
            },
            {
              "lat": 48.19824,
              "lon": 16.36226
            },
            {
              "lat": 48.19788,
              "lon": 16.3615
            }
          ]
        }
      }
    }
  ]
}

Geocode examples

XML body example

<?xml version="1.0" encoding="utf-8"?>
<batchRequest>
  <batchItems>
    <batchItem>
      <query>/geocode/tower bridge.xml</query>
    </batchItem>
    <batchItem>
      <query>/geocode/new york.xml</query>
    </batchItem>
    <batchItem>
      <query>/geocode/amsterdam.xml</query>
    </batchItem>
  </batchItems>
</batchRequest>

JSON body example

{
  "batchItems": [
    {"query": "/geocode/tower bridge.json"},
    {"query": "/geocode/new york.json"},
    {"query": "/geocode/amsterdam.json"}
  ]
}

Structured Geocode examples

XML body example

<?xml version="1.0" encoding="utf-8"?>
<batchRequest>
  <batchItems>
    <batchItem>
      <query>/structuredGeocode.xml?countryCode=FR&amp;municipality=Paris&amp;streetName=Avenue de Suffren&amp;streetNumber=70</query>
    </batchItem>
    <batchItem>
      <query>/structuredGeocode.xml?countryCode=ES&amp;municipality=Madrid&amp;streetName=Calle Mariblanca&amp;streetNumber=25</query>
    </batchItem>
  </batchItems>
</batchRequest>

JSON body example

{
  "batchItems": [
    {"query": "/structuredGeocode.json?countryCode=FR&municipality=Paris&streetName=Avenue de Suffren&streetNumber=70"},
    {"query": "/structuredGeocode.json?countryCode=ES&municipality=Madrid&streetName=Calle Mariblanca&streetNumber=25"}
  ]
}

Reverse Geocode examples

XML body example

<?xml version="1.0" encoding="utf-8"?>
<batchRequest>
  <batchItems>
    <batchItem>
      <query>/reverseGeocode/48.203233,16.360454.xml</query>
    </batchItem>
    <batchItem>
      <query>/reverseGeocode/-26.202878,28.033040.xml</query>
    </batchItem>
    <batchItem>
      <query>/reverseGeocode/12.975469,77.597284.xml</query>
    </batchItem>
  </batchItems>
</batchRequest>

JSON body example

{
  "batchItems": [
    {"query": "/reverseGeocode/48.203233,16.360454.json"},
    {"query": "/reverseGeocode/-26.202878,28.033040.json"},
    {"query": "/reverseGeocode/12.975469,77.597284.json"}
  ]
}

CrossStreet lookup examples

XML body example

<?xml version="1.0" encoding="utf-8"?>
<batchRequest>
  <batchItems>
    <batchItem>
      <query>/reverseGeocode/crossStreet/52.4781801,4.8884868.xml</query>
    </batchItem>
    <batchItem>
      <query>/reverseGeocode/crossStreet/12.977194,77.608367.xml</query>
    </batchItem>
    <batchItem>
      <query>/reverseGeocode/crossStreet/21.130272,79.063060.xml</query>
    </batchItem>
  </batchItems>
</batchRequest>

JSON body example

{
  "batchItems": [
    {"query": "/reverseGeocode/crossStreet/52.4781801,4.8884868.json"},
    {"query": "/reverseGeocode/crossStreet/12.977194,77.608367.json"},
    {"query": "/reverseGeocode/crossStreet/21.130272,79.063060.json"}
  ]
}

Additional Data examples

XML body example

<?xml version="1.0" encoding="utf-8"?>
<batchRequest>
  <batchItems>
    <batchItem>
      <query>/additionalData.json?geometries=00004631-3400-3c00-0000-0000673c4d2e</query>
    </batchItem>
    <batchItem>
      <query>/additionalData.json?geometries=00004631-3400-3c00-0000-0000673c42fe</query>
    </batchItem>
  </batchItems>
</batchRequest>

Above POST body contains example geometry ID values. Proper geometry ID values can be retrieved from a Search Request.

JSON body example

{
  "batchItems": [
    {"query": "/additionalData.json?geometries=00004631-3400-3c00-0000-0000673c4d2e"},
    {"query": "/additionalData.json?geometries=00004631-3400-3c00-0000-0000673c42fe"}
  ]
}

Above POST body contains example geometry ID values. Proper geometry ID values can be retrieved from a Search Request.

EV Charging Stations Availability examples

XML body example

<?xml version="1.0" encoding="utf-8"?>
<batchRequest>
  <batchItems>
    <batchItem>
      <query>/chargingAvailability.xml?chargingAvailability=00112233-4455-6677-8899-aabbccddeeff</query>
    </batchItem>
    <batchItem>
      <query>/chargingAvailability.xml?chargingAvailability=00112233-4455-6677-8899-001122334455</query>
    </batchItem>
  </batchItems>
</batchRequest>

Above POST body contains example charging availability ID values. Proper charging availability ID values can be retrieved from a Search Request.

JSON body example

{
  "batchItems": [
    {"query": "/chargingAvailability.json?chargingAvailability=00112233-4455-6677-8899-aabbccddeeff"},
    {"query": "/chargingAvailability.json?chargingAvailability=00112233-4455-6677-8899-001122334455"}
  ]
}

Above POST body contains example charging availability ID values. Proper charging availability ID values can be retrieved from a Search Request.


▲ 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 client.
400 Bad Request: Missing required parameters, exceeded maximum number of batch items, or parameters did not pass validation.
403 Forbidden: The API Key is missing, inactive, invalid, not entitled to use the Batch Search API over QPS or over QPD. It can also occur when using HTTP instead of HTTPS.
404 Not Found: The requested resource could not be found, but it may be available again in the future.
405 Method Not Allowed: The client used an HTTP method other than POST.
408 Request timeout.
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.

▲ Return to top

HTTP Response headers

The following table lists HTTP Response headers of particular interest to the service clients.

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
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: An identifier for the Request.

▲ Return to top

Successful Response structure

Each Batch Response consists of one or more XML <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.

Response example (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 example

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

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 the results of processing a single batch item.
statusCode
string
Status code of a Response from the underlying Search API endpoint for a given batch item.
response
object
Content of the Response from the underlying Search API endpoint for a 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 the 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 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 supported Search API suite responses

For details on a particular supported Search API suite endpoint's response structure, consult the respective API documentation pages available in the supported endpoints section.

Response errors

The error response content type depends on the outputFormat parameter.

Error Response (XML)

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<batchResponse xmlns="http://api.tomtom.com/batch" formatVersion="0.0.1">
    <error description="Parsing of batch item 1 failed."/>
</batchResponse>

Error Response (JSON)

{
    "formatVersion": "0.0.1",
    "error": {
        "description": "Parsing of batch item 1 failed."
    }
}

Error response fields

Error response fields
Field Description
batchResponse
object
Root element of the batch error Response.
formatVersion
float
Version of a batch error Response format.
error
object
Element describing the error.
description
string
Error description string.

▲ Return to Top

You are here