Batch requests API

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"

Job execution and 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.