---
title: "Reverse geocode a coordinate"
method: GET
path: "/api/v1/geocoding/reverse"
tags: ["Geocoding"]
---

# Reverse geocode a coordinate

`GET /api/v1/geocoding/reverse`

Convert a lat/lon coordinate into the nearest OpenStreetMap place at the requested `zoom` level (0 country, 18 building). Intended for one-shot lookups, not live autocomplete. Data is (C) OpenStreetMap contributors (ODbL 1.0).

## Query parameters

- `lat` number, required — Latitude in decimal degrees (WGS84).
- `lon` number, required — Longitude in decimal degrees (WGS84).
- `zoom` integer — Address-detail zoom level: 0 country, 3 continent, 5 state, 8 county, 10 city, 14 suburb, 16 major street, 17 minor street, 18 building.
- `addressdetails` boolean — Include the structured address breakdown on the result.

## Response `200`

Nearest OSM place at the requested zoom, (C) OpenStreetMap contributors (ODbL 1.0).

- EnvelopeNominatimReversePayload
  - `data` NominatimReversePayload, required — Response payload for `/api/v1/geocoding/reverse`.
    - `lat` number, required — Query latitude echoed from the request.
    - `lon` number, required — Query longitude echoed from the request.
    - `zoom` integer, required — Address-detail zoom level echoed from the request (0 country, 18 building).
    - `result` NominatimPlace — Single geocoded place returned by Nominatim. (C) OpenStreetMap contributors (ODbL 1.0).
      - `place_id` integer, nullable — Internal Nominatim place identifier. Stable within a single database snapshot but not across reindexes; prefer the `(osm_type, osm_id)` pair for long-term identity.
      - `osm_type` string, nullable — OSM element variant: `node`, `way`, or `relation`.
      - `osm_id` integer, nullable — Stable OpenStreetMap identifier within the `osm_type` namespace.
      - `lat` number, nullable — Representative point latitude in decimal degrees (WGS84).
      - `lon` number, nullable — Representative point longitude in decimal degrees (WGS84).
      - `display_name` string, nullable — Locale-dependent comma-separated human-readable place name.
      - `name` string, nullable — Primary name of the place in the requested language.
      - `category` string, nullable — OSM top-level classification (e.g. `boundary`, `place`, `amenity`).
      - `type` string, nullable — OSM sub-classification within the `category` (e.g. `administrative`, `city`).
      - `place_rank` integer, nullable — Nominatim rank 0-30, lower = more important (country=4, state=8, city=16, building=30).
      - `importance` number, nullable — Nominatim importance score 0.0-1.0 derived from Wikipedia link density and admin level.
      - `addresstype` string, nullable — Category label for the result (`city`, `town`, `road`, `building`, ...).
      - `boundingbox` number[], nullable — Bounding box `[minLat, maxLat, minLon, maxLon]` in decimal degrees (WGS84).
      - `address` NominatimAddress — Structured address breakdown returned when `addressdetails=1`. Field set is open-ended - Nominatim uses OSM address tagging keys, which vary by country (German `Hausnummer` vs English `house_number` etc.). This model declares the most common keys; extra keys pass through via Pydantic's default behaviour.
        - `house_number` string, nullable — House or building number from OSM `addr:housenumber`.
        - `road` string, nullable — Street name from OSM `addr:street` or the road `name` tag.
        - `neighbourhood` string, nullable — Neighbourhood label from OSM `place=neighbourhood`.
        - `suburb` string, nullable — Suburb or district label from OSM `place=suburb`.
        - `quarter` string, nullable — Quarter label from OSM `place=quarter`.
        - `borough` string, nullable — Borough or sub-municipal district label.
        - `city` string, nullable — City or locality name.
        - `town` string, nullable — Town name (used when no `city` level applies).
        - `village` string, nullable — Village name (used for rural settlements).
        - `municipality` string, nullable — Municipality name (administrative level).
        - `county` string, nullable — County or district name.
        - `state` string, nullable — State, province, or region name.
        - `state_district` string, nullable — State sub-district label.
        - `postcode` string, nullable — Postal code from OSM `addr:postcode`.
        - `country` string, nullable — Country name in the requested language.
        - `country_code` string, nullable — ISO 3166-1 alpha-2 country code, lowercase.
    - `attribution` string — ODbL 1.0 attribution required on every surface that displays this data.
  - `meta` SugraMeta, required — Metadata attached to every /api/v1/* response envelope.
    - `endpoint` string, required — Requested endpoint path.
    - `data_time` string, required — ISO 8601 UTC timestamp of the source data, not of the request.
    - `response_time` string, required — ISO 8601 UTC timestamp when this response was produced.
    - `provider` string, required — API name and version.
    - `source` string, nullable — Identifier of the primary upstream source used for this response.
    - `attribution` string, nullable — Human-readable attribution mandated by an upstream source (e.g. a securities regulator or self-regulatory organization). Present only on responses whose source requires the owner and source to be clearly identified. Do not remove or alter it when using the response.
    - `fallback_used` boolean, nullable — True when the primary source failed and a fallback produced the data.
    - `fallback_chain` string[], nullable — Ordered list of sources attempted, in the order they were tried.
    - `cached` boolean, nullable — True when this response was served from the internal cache.
    - `stale` boolean, nullable — True when the cached response was returned after the upstream rate-limited or errored. Clients can use this to detect degraded data.

## Other responses

- `401` — Missing or invalid `x-api-key` header. JSON body with a stable `code` distinguishing `missing_api_key` (no header sent) from `invalid_api_key` (header sent, key not accepted); any other 401 source carries the generic `unauthorized` with its detail as `reason`. Plus `hint`. `plan` is always null on 401 - an unauthenticated request has no plan; quota exhaustion is 429, not 401.
- `422` — Validation Error
- `429` — Daily rate limit exceeded. Check `X-RateLimit-Reset` for the next window.
- `503` — Upstream source is temporarily unavailable. Retry after a short delay.

---

[API](https://skmtc.net/sugra/apis/sugra-api.md) · [All operations](https://skmtc.net/sugra/apis/sugra-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/sugra/sugra-api/versions/4c4530760ba1/schema)