Submit A Bulk Geocode Job

Developing

POST

/api/v1/public/geocode/bulk

Queues up to 200 addresses for background geocoding and returns a bulkRef immediately — no results are included in this response. The whole batch is rejected if the wallet cannot cover the per-address geocode fee times the number of addresses, though the wallet is debited by the background worker as rows are processed, not on submission. An email is sent when the job finishes.

Request

Authorization

API Key

Add parameter in header

X-Api-Key

Example:

X-Api-Key: ********************

Body Params application/jsonRequired

Examples

Responses

🟢200

application/json

Job accepted and queued. Poll the job endpoint for results.

Bodyapplication/json

🟠400

🟠401

Request Example

Shell

JavaScript

Java

Swift

curl --location '/api/v1/public/geocode/bulk' \
--header 'X-Api-Key: <api-key>' \
--header 'Content-Type: application/json' \
--data '{
    "addresses": [
        {
            "fullAddress": "12 Adeola Odeku Street, Victoria Island, Lagos"
        },
        {
            "fullAddress": "3 Awolowo Road, Ikoyi, Lagos"
        }
    ]
}'

Response Example

200 - Example 1

{
    "status": true,
    "message": "Operation successful.",
    "data": {
        "bulkRef": "f167f2c8-a214-41f6-b5ed-298b411ca68e",
        "message": "Details received. You will be notified via email once the job is completed.",
        "itemCount": 150
    }
}

Modified at 2026-08-06 11:58:31

Geocode An Address

List Bulk Geocode Jobs