Batch Routing service
Purpose
Batch Routing works as a subset of the Routing API suite. This service enables you to dispatch batches of Calculate Route and Calculate Reachable Range requests with ease.
Synchronous and Asynchronous batch processing
You can call Batch Routing APIs to run either synchronously or asynchronously.
Synchronous Batch
The Synchronous Batch endpoint allows you to submit a new batch for synchronous processing.
Asynchronous Batch Submission
The Asynchronous Batch Submission endpoint allows the submission of a new batch for asynchronous processing.
Asynchronous Batch Download
The Asynchronous Batch Download endpoint fetches results of the asynchronous batch processing.
Synchronous API overview
The Synchronous API is recommended for lightweight routing requests with quickly-expiring results (e.g., due to changing traffic conditions).
- In such a case, when the service receives a request, it will respond as soon as the routes of the batch 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.
- The number of batch items is limited to 100 for this API.
Sequence of Synchronous API client actions
- A client sends a request to the Synchronous Batch endpoint.
- The server will respond with one of the following:
- An HTTP
200
Batch processing result: The calculation is finished before timeout and the client downloads results straight away. - An HTTP
408
request timeout error: This occurs if the request takes longer than 60 seconds and cannot be finished in this timeframe. - Another HTTP error: See the Synchronous Batch response codes.
Asynchronous API overview
The Asynchronous API is appropriate for processing big volumes of relatively complex routing requests.
- It allows the retrieval of 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.
- The number of batch items is limited to
700
for this API.
Data retention period notice
Please be aware that batches processed by an Asynchronous API are available for download for 14 days, after which a results download will return a HTTP 404
(Not Found) response.
Sequence of Asynchronous API client actions
- A client sends a request to the Asynchronous Batch Submission endpoint.
- The server will respond with one of the following:
- HTTP
202
or HTTP303
: This depends on theredirectMode
parameter with theLocation
header, which points to the Asynchronous Batch Download endpoint. - Another HTTP error: See the Asynchronous Batch Submission HTTP status codes.
- After getting an HTTP
202
or HTTP303
response, the client should follow the redirect to the Asynchronous Batch Download endpoint which is a blocking long poll request. - When a client calls the Asynchronous Batch Download endpoint the possible scenarios are:
- Batch response is calculated before timeout (by default this is 120 seconds it can be changed by using the
waitTimeSeconds
parameter).- The client receives HTTP
200
. - Batch response is ready and it gets streamed to the client.
- The client receives HTTP
- 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).
- The client receives HTTP
- Batch response is calculated before timeout (by default this is 120 seconds it can be changed by using the