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.

Synchronous and asynchronous batch processing

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

Synchronous API overview

The Synchronous API is recommended for lightweight routing requests with quickly-expiring results (e.g., due to changing traffic conditions).

• In this case, when the service receives a request, it responds as soon as the routes of the batch are calculated, and the results cannot be retrieved later.
• The Synchronous API returns 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

1. A client sends a request to the Synchronous batch endpoint.
2. The server will respond with one of the following:

• An HTTP 200 batch processing result: The calculation finishes before the timeout, allowing the client to download the results immediately.
• 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 large 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 returns an HTTP 404 (Not Found) response.

Sequence of Asynchronous API client actions

1. A client sends a request to the Asynchronous Batch Submission endpoint.
2. The server will respond with one of the following:

• HTTP 202 or HTTP 303: This depends on the redirectMode parameter with the Location header, which points to the Asynchronous Batch Download endpoint.
• Another HTTP error: See the Asynchronous Batch Submission HTTP status codes.

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 a client calls the Asynchronous Batch Download endpoint, the possible scenarios are:
   • The batch response is calculated before the timeout (by default, this is 120 seconds. The timeout can be changed using the waitTimeSeconds parameter).
     • The client receives HTTP 200.
     • The batch response is ready and is streamed to the client.
   • The batch response is not ready before the timeout.
     • The client receives HTTP 202.
     • The batch request is accepted for processing.
     • The client downloads batch results from the URL specified by the Location header (see point 3).