Forward and reverse geocoding backed by OpenStreetMap Nominatim, with normalized results, confidence scores, batch lookups, and a 24-hour cache.
This calls the live Geocoding API. Turn a place name into coordinates, or pick coordinates and get the structured address back.
| displayName | lat | lon | confidence |
|---|---|---|---|
| Loading live response... | |||
Why Geocoding API
Forward and reverse
Free-form text to coordinates, or lat/lon to a structured address with road, city, state, postcode, and country fields.
Confidence scores
Every forward match carries a confidence object with a numeric score and a high/medium/low level derived from provider importance.
Batch lookups
POST /batch runs up to 25 mixed forward and reverse queries in order and returns a per-item statusCode with each payload.
Query shaping
Tune forward results with limit, language, countryCodes filters, and viewbox/bounded hints; control reverse detail with zoom.
24-hour cache
Responses are cached for a day with a 1 req/s upstream throttle, keeping repeat lookups fast and well within provider etiquette.
Provider-agnostic contract
Adapter-based provider selection (Nominatim today) behind one stable response shape, so integrations never chase upstream changes.
/api/v1/geocoding
Forward geocoding
Requires q. Resolves free-form place text to normalized matches with coordinates and confidence.
Reverse geocoding
Requires lat and lon. Returns a structured address for the coordinate pair.
Batch lookups
1 to 25 mixed forward and reverse queries executed in order, each with its own statusCode.
Service health
Status, service name, version, active provider, and correlationId.
Prometheus metrics
Request counts and latency histograms in Prometheus exposition format.
| Parameter | Type | Required | Description |
|---|---|---|---|
| q | string | forward | Free-form location text, trimmed, 1 to 256 characters. |
| lat / lon | number | reverse | Coordinates: lat -90..90, lon -180..180. |
| limit | integer | no | Max forward results, 1 to 10. Default 5. |
| language | string | no | Preferred response language, e.g. en or en-US. |
| countryCodes | string | no | Comma-separated ISO country filters for forward lookups, e.g. us,ca. |
| viewbox / bounded | string / boolean | no | Bounding-box hint (left,top,right,bottom); bounded=true restricts results to the box. |
| zoom | integer | no | Reverse detail level, 0 to 18. |
| addressdetails | boolean | no | Include normalized address components in reverse output. Default true. |
| queries | array | batch | 1 to 25 batch items; each is forward ({q}) or reverse ({lat, lon}) with the same options. |
Error reference
Failures return success: false with an error message, a machine-readable reason where relevant, and a correlationId.
Missing or invalid q, lat, or lon, or malformed batch queries. The details array lists each failing field.
Missing or invalid gateway API key. Send x-api-key or api_key with every request.
Unknown route. Valid paths are /forward, /reverse, and /batch under /api/v1/geocoding.
More than 120 requests in a 15-minute window. The response includes retryAfter seconds.
The geocoding provider did not respond; reason is upstream-unavailable. Cached lookups keep working.
Unexpected service failure. Include the correlationId when reporting the issue.
Example error response
{
"success": false,
"error": "Invalid query parameters",
"details": [
"\"lat\" must be less than or equal to 90"
],
"correlationId": "abc-123"
}FAQ
Forward geocoding (GET /forward?q=...) turns free-form text like a place name or street address into coordinates with normalized metadata. Reverse geocoding (GET /reverse?lat=...&lon=...) turns a coordinate pair into a structured address with road, city, state, postcode, and country fields.
Every forward match includes a confidence object with a numeric score and a high/medium/low level derived from the provider's importance ranking, so you can threshold matches or ask users to disambiguate.
Yes. POST /batch accepts 1 to 25 items, each either forward ({"q": ...}) or reverse ({"lat": ..., "lon": ...}), and returns results in order with a per-item statusCode.
The current provider is OpenStreetMap Nominatim behind an adapter layer, with a 24-hour cache and a 1 req/s upstream throttle. The response contract is provider-agnostic, so future providers will not change your integration.
Send your Datpaq API key as an x-api-key header or an api_key query parameter. Keys are created in the Datpaq dashboard and a free tier is included.
Forward, reverse, and batch geocoding with confidence scores and a stable response contract. No provider accounts, no cache to build.