Geoapify Batch Requests

You can send multiple API requests within one call with Batch service. For example, this could be useful when you need to find a location for a range of addresses or calculate multiple routes / isolines. Geoapify batch requests can contain up to 1000 inputs.

Asynchronous processing

Batch requests are processed asynchronously:

Batch API workflow
  • First, you submit a batch job with an HTTP POST request and specify inputs in the request body. You get the job id as a result of the request.
  • Then request the job results with the job id with some interval. We recommend setting at least 60000ms (= 1 minute) time interval for big jobs.
  • The response code of the processing job is 202.
  • As soon as the job is finished you get response code 200 and the result.

The job result is available for the next 24 hours and can be requested multiple times.

API reference: create a job

Geoapify Batch service is used to send multiple API requests with one call. This allows optimizing the costs and makes the API calls more convenient when processing a big amount of data.

Create a batch job

Send an HTTP POST request to set a batch job. The body of the request should contain a JSON object with the specified below fields.

Request URL


POST https://api.geoapify.com/v1/batch?apiKey=YOUR_API_KEY


Request body structure

Name Description
api API path. Supported values: /v1/geocode/search, /v1/geocode/reverse, /v1/routing, /v1/isoline.
params API request parameters common for all inputs (e.g. language).
body Optional JSON body (for APIs like Map Matching that accept data in request body) common for all inputs (e.g. "mode")
inputs Array of individual inputs. The array can contain up to 1000 elements.
Input structure
Name Description
id Optional id of the input, that can help you to identify the result later
params Specific API request parameters (e.g. "text" for Geocoding or "waypoints" for Routing request)
body Specific JSON body for APIs like Map Matching that accept data in request body (e.g. "waypoints")

If params or body are specified on both request and input level, they will be merged. Keys & values specified on the input level will override ones specified at request level.

Body object example

Here is an example of the body object for the batch Routing API request:

{
    "api": "/v1/routing",
    "params": {
        "mode": "drive",
        "lang": "de"
    },
    "inputs": [
        {
            "id": "optional-input-id1",
            "params": {
                "waypoints": "48.3821666,10.8839706053042|48.3562084,10.9051509"
            }
        },
        {
            "id": "optional-input-id2",
            "params": {
                "waypoints": "48.39502045,11.0691551568873|48.369782877329,11.0481118237265|48.3545535,10.99449785"
            }
        },
                {
            "id": "optional-input-id3",
            "params": {
                "waypoints": "48.5494131,10.8698944|48.5343427618592,10.8362023492961|48.4715186146168,10.8169862931277"
            }
        }
    ]
}

Use Batch Request Playground to generate a body object for a required API.

Response

You will get the job ID and current job status as the response of the requests. The Response Status is HTTP 202.

Name Description
id The job ID
status The job status is "pending"

API reference: get results

Send repeatedly HTTP GET requests with the job id to monitor the job execution and get results.

URL


GET https://api.geoapify.com/v1/batch?id=JOB_ID&apiKey=YOUR_API_KEY


Response HTTP Status codes

Name Description
200 The job execution is completed. Results are available in the response object.
202 The job is processing
404 The job is not found. Job results are available for the next 24 hours after completion, the results are deleted afterward.

Response object

Name Description
id The job ID
status The job status. The status is missing if HTTP Status Code is 200.
results Array of results objects. Keeps the same order as inputs array. The results available if HTTP Status Code is 200.

Result object

Name Description
id ID of the input if provided
result A result object returned by the specified API. Is GeoJSON.FeatureCollection for the most of Geoapify APIs.

Pricing

Batch requests allow you to process more data at a lower price.

Geoapify provides special plans for Batch requests where API call cost is at least 2 times lower than a single API call. For other pricing plans, all API calls made with the Batch service are counted with a coefficient of 0.5 (2 times cheaper).

Counting usage for batch requests:

  • Each input is counted as a one API call
  • Setting a job a counted as a one API call
  • Each result request is counted as a one API call

For example, when you set a batch job with 1000 inputs and then in 1 minute query and get a result it's counted as:

1000 inputs + 1 job call + 1 result call = 1002 API calls