All requests require X-Api-Key: <your-key> header — except the health check.
· Rate limit: 250 req/s sustained, 500 burst.
· Default precision: P4 (11 m cell, Uganda-optimised).
Endpoints
Method
Path
What it does
GET
/api/v1/health
Check API, database, and Nominatim status. No auth required.
POST
/api/v1/reverse
Reverse geocode one coordinate. Returns cached result instantly; calls Nominatim on a miss and caches the result for 180 days.
POST
/api/v1/reverse/bulk
Geocode up to 5,000 coordinates in one synchronous call. Best when most points are already cached. Returns 413 if >500 are uncached — submit an async job instead.
POST
/api/v1/reverse/jobs
Submit a large batch (up to 100,000 coords) as an async job. Returns a job_id immediately; workers geocode in background at ~20/s. Cached points are resolved at submission time.
GET
/api/v1/reverse/jobs/{id}
Poll job progress. Compare completed_points to total_points. Poll every 3–5 seconds.
GET
/api/v1/reverse/jobs/{id}/results
Download results with limit + offset pagination (max 1,000 per page). Can be called while the job is still running.
When to use what
Situation
Recommended endpoint
Live vehicle ping
POST /api/v1/reverse
Small batch (<5,000), mostly routes already seen
POST /api/v1/reverse/bulk
Any batch with many fresh / unseen coordinates
POST /api/v1/reverse/jobs then poll
Historical import (10k–100k coordinates)
POST /api/v1/reverse/jobs → poll → paginate results