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:

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.

Learn more

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

Learn more