Asynchronous Batch Submission
Service version: 2
Last edit: 2019.11.29
On this page
Purpose
This endpoint allows the submission of a new batch for asynchronous processing. It responds with a redirect to the location at which the batch results can be obtained when the batch processing has completed.
Request data
HTTPS method: POST
URL format
For ease of viewing and identification:
- Constants and parameters enclosed in angle brackets (< >) must be replaced with their values.
- See the following Request parameters section with the Required and Optional parameters tables for these values.
https://<baseURL>/search/<versionNumber>/batch.<outputFormat>?key=<Your_API_Key>[&redirectMode=<redirectMode>][&waitTimeSeconds=<waitTimeSeconds>]
Example
https://api.tomtom.com/search/2/batch.json?key=Your_API_Key
HTTP Request headers
The following data table describes HTTP Request headers of particular interest to Batch Search service clients.
- Required headers must be used or the call will fail.
- Optional headers may be used.
Required headers | |
---|---|
Header | Description |
Content-Type string |
Specifies the MIME type of the body of the Request. Values:
|
Optional headers | |
Header | Description |
Tracking-ID string |
Specifies an identifier for the Request.
|
Request parameters
The following table describes the Request parameters.
- Required parameters must be used or the call will fail.
- Optional parameters, which are highlighted with [square brackets], may be used.
- If there is a default value that will be assumed when an optional parameter is not used, it is shown in the table.
- The order of Request parameters is not important.
Required parameters | |
---|---|
Parameter | Description |
baseURL string |
Base URL for calling the API. Value: api.tomtom.com |
versionNumber string |
Service version. Value: The current value is 2 . |
key string |
An API Key valid for the requested service. Value: Your valid API Key . |
outputFormat string |
The content type of the Response structure. Values:
|
Optional parameters | |
Parameter | Description |
[redirectMode] string |
Controls the HTTP code of the successful HTTP Response to the submission Request.
Location header is included.Default value: auto Other value: manual |
[waitTimeSeconds] integer |
Allows changing the maximum amount of time, in seconds, for which the client may have to wait for an Asynchronous Batch Download Response while the batch is being processed. Please note that provided 120 Value: It may be either:
|
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:
- Fuzzy Search
- Points of Interest Search
- Category Search
- Geometry Search
- Nearby Search
- Along Route Search
- Geocode
- Structured Geocode
- Reverse Geocode
- CrossStreet lookup
- Additional Data
- EV Charging Stations Availability
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 an Asynchronous API is 10000 . |
batchItem |
A single batch item. |
query |
A string used to build a request to one of the supported endpoints of the Search API suite.
When posting JSON to the Batch Search service, the <query> string values must be properly escaped; e.g., the " character should be escaped with a \ (backslash). More information is available in RFC 7159. |
post |
Contains data that is sent to the Geometry Search or Along Route Search services using the HTTP POST method.
|
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&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&idxSet=POI,PAD,Str,Xstr,Geo,Addr</query>
</batchItem>
<batchItem>
<query>/search/wroclaw.xml?limit=10&idxSet=POI,PAD,Str,Xstr,Geo,Addr</query>
</batchItem>
<batchItem>
<query>/search/berlin.xml?limit=10&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&lon=21.011422</query>
</batchItem>
<batchItem>
<query>/categorySearch/restaurant.xml?lat=38.925518&lon=76.990957</query>
</batchItem>
<batchItem>
<query>/categorySearch/hotel.xml?lat=34.016308&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&lon=-74.045358&radius=2000</query>
</batchItem>
<batchItem>
<query>/nearbySearch/.xml?lat=41.774831&lon=-87.771554&radius=2000</query>
</batchItem>
<batchItem>
<query>/nearbySearch/.xml?lat=48.141307&lon=17.117647&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&municipality=Paris&streetName=Avenue de Suffren&streetNumber=70</query>
</batchItem>
<batchItem>
<query>/structuredGeocode.xml?countryCode=ES&municipality=Madrid&streetName=Calle Mariblanca&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>
The preceding 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"}
]
}
The preceding 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>
The preceding 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"}
]
}
The preceding POST body contains example charging availability ID values. Proper charging availability ID values can be retrieved from a Search Request.Response data
Batch Submission Response
On a successful Batch Request submission, the Batch Search service responds with a HTTP 202
or a HTTP 303
. The response has a Location
header with a link to the Batch Download endpoint and no body. In case of an error, a body is present.
HTTP Status codes
Code | Meaning and Possible Causes |
---|---|
202 |
Accepted:
|
303 |
See Other:
|
400 |
Bad Request:
|
403 |
Forbidden:
|
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 a HTTP method other than POST. |
414 |
Requested URI is too long: Indicates that the URI requested by the client is longer than the server is willing to interpret. |
429 |
Too Many Requests: The API Key is over QPS (Queries per second). |
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 Response headers
Header | Description |
---|---|
Access-Control-Expose-Headers |
A comma separated list of HTTP header names that browsers are allowed to access. Value: Content-Length |
Access-Control-Allow-Origin |
A header instructing browsers to allow customer websites to contact the Batch Search service. Value: * |
Content-Encoding |
The Batch Search service applies gzip compression to the responses if it is requested by the client with the Accept-Encoding header.Value: gzip |
Content-Type |
The format of the Response as chosen by the client (see the contentType Request parameter).Values:
|
Location |
Indicates the location where the batch results can be downloaded. Value: URI |
Tracking-ID |
An identifier for the Request.
An identifier for the Request. |
Error Response
The error Response content type depends on the outputFormat
parameter.
Error Response example (XML)
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<batchResponse xmlns="http://api.tomtom.com/batch" formatVersion="0.0.1">
<error description="Validation of batch item 1 failed. Batch response format (XML) does not match content type of batch item query."/>
<detailedError>
<code>BadRequest</code>
<message>Bad Request</message>
<details>
<detail>
<code>MalformedBody</code>
<message>Validation of batch item 1 failed. Batch response format (XML) does not match content type of batch item query.</message>
<target>postBody</target>
</detail>
</details>
</detailedError>
</batchResponse>
Error Response example (JSON)
{
"formatVersion": "0.0.1",
"error": {
"description": "Validation of batch item 1 failed. Batch response format (JSON) does not match content type of batch item query."
},
"detailedError": {
"code": "BadRequest",
"message": "Bad Request",
"details": {
"code": "MalformedBody",
"message": "Validation of batch item 1 failed. Batch response format (JSON) does not match content type of batch item query",
"target": "postBody",
}
}
}
Error Response fields
Primary fields | |
---|---|
Field | Description |
formatVersion string |
Version of the batch error Response format. |
error object |
Simplified information about the error.error{} object |
detailedError object |
Detailed information about the error.detailedError{} object
|
error{} object |
|
Field | Description |
description string |
A human-readable description of the error. It is intended as an aid to developers and is not suitable for exposure to end users. |
detailedError{} object |
|
Field | Description |
code string |
One of the defined error codes. |
message string |
A human-readable description of the error code. It is intended as an aid to developers and is not suitable for exposure to end users. |
target string |
Optional. Target of the particular error. Values:
|
details array |
Optional. An array of root causes (more detailed errors) that led to this error. detailedError[] array
|
innerError object |
Optional. A higher level of details about this error. innerError{} object
|
innerError{} object |
|
Field | Description |
code string |
One of the defined error codes. |
message string |
Optional. A human-readable representation of the error code. It is intended as an aid to developers and is not suitable for exposure to end users. |
innerError object |
Optional. A higher level of details about this error. innerError{} object
|
Error code hierarchy
List of predefined, hierarchical, human-readable error codes.
- Top level codes relate to HTTP error codes.
- They may be refined by error codes in
details
orinnerError
. - Further levels of refinement are possible by nesting
innerError
insideinnerError
.
In the future, the list may be extended with additional codes. The application must be ready for the occurrence of an unknown error code (e.g., by stopping error processing at the last understood level of detail).
Error code | Description |
---|---|
BadArgument |
One of the request parameters was missing or did not pass validation.
The Possible inner errors:
|
BadRequest |
Top level code for Requests which resulted in a HTTP Possible root causes:
|
IllegalParameter |
Unsupported request parameter was specified. |
InvalidParameterValue |
The value of one of the parameters is invalid. |
InternalServerError |
Top level code for Requests which resulted in a HTTP 500 Internal Server Error .
The service cannot handle the request right now, an unexpected condition was encountered. |
MalformedBody |
POST body has unexpected format. |
MissingRequiredParameter |
One of the required parameters was not provided. |
NotFound |
Top level code for Requests which resulted in a HTTP 404 Not Found caused by providing incorrect Request path. |
ServiceUnavailable |
Top level code for Requests which resulted in a HTTP 503 Service Unavailable .
The service cannot handle the request right now, this is certainly a temporary state. |
ValueOutOfRange |
The value of one of the numeric parameters is out of the allowed range. |