API reference

# Reverse geocoding

Look up the nearest addresses from coordinates. If no house is in range, results may fall back to a street, then a nearby locality. Results are ordered nearest first.

Use cases, pricing and how it compares: [Reverse geocoding API →](https://opengeocoding.com/reverse-geocoding-api) 

1 credit per successful call · Authentication and account rate limit apply.

POST GET /v1/reverse

## Request body

`application/json` · Up to 64 KiB. Unknown fields are rejected. Send your key in [x-api-key](https://opengeocoding.com/docs/authentication). With GET, send the same fields as URL query parameters instead; nested fields use dots, such as `focus.lat`. Unknown or repeated parameters return 400\. The key still goes in a header.

* `lat` number  
Latitude in degrees, from -90 to 90\. Omission uses 0.
* `lon` number  
Longitude in degrees, from -180 to 180\. Omission uses 0.
* `radiusM` integer  
Search radius in metres. Omitted or 0 uses 500.  
Default: `500`. Range: 0–2000.
* `size` integer  
Maximum results. Omitted or 0 uses 1.  
Default: `1`. Range: 0–10.

## Response 200

Default scalar values and empty lists may be omitted. Treat absent lists as empty and absent scalars as their protobuf defaults.

* `results` ReverseResult\[\]  
Nearest first. Empty or omitted when nothing is in range.

  * `address` FullAddress  

    * `addressDetails` AddressDetails  

      * `aerialway` string
      * `aeroway` string
      * `allotments` string
      * `amenity` string
      * `borough` string
      * `boundary` string
      * `bridge` string
      * `city` string
      * `cityBlock` string
      * `cityDistrict` string
      * `club` string
      * `commercial` string
      * `continent` string
      * `country` string
      * `countryCode` string
      * `county` string
      * `craft` string
      * `croft` string
      * `district` string
      * `emergency` string
      * `farm` string
      * `farmyard` string
      * `hamlet` string
      * `highway` string
      * `historic` string
      * `houseName` string
      * `houseNumber` string
      * `industrial` string
      * `isolatedDwelling` string
      * `landuse` string
      * `leisure` string
      * `manMade` string
      * `military` string
      * `mountainPass` string
      * `municipality` string
      * `natural` string
      * `neighbourhood` string
      * `office` string
      * `place` string
      * `postcode` string
      * `province` string
      * `quarter` string
      * `railway` string
      * `region` string
      * `regionCodes` ISO3166\_2\[\]  
            ISO 3166-2 codes for the address.

        * `adminLevel` integer  
                    Administrative level.  
                    Range: 0–4294967295.
        * `code` string  
                    ISO 3166-2 region code.
      * `regions` Region\[\]  
            Administrative regions for the address.

        * `adminCode` string  
                    ISO 3166-2 administrative region code.
        * `adminLevel` integer  
                    Administrative level.  
                    Range: 0–4294967295.
        * `countryCode` string  
                    ISO 3166-1 alpha-2 country code.
        * `countryName` string  
                    Country name.
        * `enName` string  
                    English region name.
        * `localName` string  
                    Local region name.
        * `parentAdminCode` string  
                    Parent administrative region code, when available.
      * `residential` string
      * `retail` string
      * `road` string
      * `shop` string
      * `state` string
      * `stateDistrict` string
      * `subdivision` string
      * `suburb` string
      * `tourism` string
      * `town` string
      * `tunnel` string
      * `village` string
      * `waterway` string
    * `displayName` string  
      Human-readable address or place name.
    * `geoCoordinates` GeoCoordinates  

      * `boundingBox` BoundingBox  

        * `maxLat` number  
                    Northern latitude in degrees.
        * `maxLon` number  
                    Eastern longitude in degrees.
        * `minLat` number  
                    Southern latitude in degrees.
        * `minLon` number  
                    Western longitude in degrees.
      * `lat` number  
            Latitude in degrees, from -90 to 90\. Omission uses the protobuf default of 0.
      * `lon` number  
            Longitude in degrees, from -180 to 180\. Omission uses the protobuf default of 0.
    * `goodMatch` boolean  
      True for a good match. False or omitted for a partial match, such as a street without the requested house number.
  * `distanceM` number  
  Distance from the requested point, in metres.
  * `layer` string  
  address: a house in range; street: no house in range; locality: neither, so the nearest locality within about 50 km.

## Errors

| HTTP | Code                | Meaning                                                                                                                                                                                                                                                                                                    |
| ---- | ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 400  | invalid\_argument   | Invalid JSON, unknown fields, unknown or repeated query parameters, unsupported Connect protocol version, oversized body, invalid query or unverifiable client address.                                                                                                                                    |
| 401  | unauthenticated     | The API key is missing, invalid, expired or revoked.                                                                                                                                                                                                                                                       |
| 403  | permission\_denied  | A browser key was used without an Origin header, from an origin not in its allowed list, or over gRPC.                                                                                                                                                                                                     |
| 404  | not\_found          | The suggestion ID is unknown or belongs to an older index. Request autocomplete suggestions again.                                                                                                                                                                                                         |
| 429  | resource\_exhausted | The per-second limit was reached, a billable operation has no remaining credits, or the client IP is temporarily locked after failed API authentication. Autocomplete and regions remain available with zero credits. IP lockouts include Retry-After and also block valid keys from that IP until expiry. |
| 503  | unavailable         | The API is starting or the geocoder is temporarily unavailable.                                                                                                                                                                                                                                            |

[Error handling and retries →](https://opengeocoding.com/docs/errors)

## Make a request

Example language

cURL 

```
curl 'https://api.opengeocoding.com/v1/reverse' \
  -H 'x-api-key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
  "lat": 55.676,
  "lon": 12.568,
  "radiusM": 500,
  "size": 1
}'
```

The production API base URL is `https://api.opengeocoding.com`. Keep secret keys server-side; in web pages, use a [browser key](https://opengeocoding.com/docs/authentication#browser-keys). JavaScript example uses Node.js; Python uses only the standard library.

## GET request

cURL 

```
curl --get 'https://api.opengeocoding.com/v1/reverse' \
  -H 'x-api-key: YOUR_API_KEY' \
  --data-urlencode 'lat=55.676' \
  --data-urlencode 'lon=12.568' \
  --data-urlencode 'radiusM=500' \
  --data-urlencode 'size=1'
```

## Example response

200 · application/json 

```
{
  "results": [
    {
      "address": {
        "displayName": "Example nearby address",
        "geoCoordinates": {
          "lat": 55.6761,
          "lon": 12.5683
        }
      },
      "distanceM": 22,
      "layer": "address"
    }
  ]
}
```

Illustrative data, not a measured API result.

Build with your own tools

Import the OpenAPI specification into Postman, Insomnia or a client generator.

[Download openapi.json ↓](https://opengeocoding.com/openapi.json)

Canonical page: https://opengeocoding.com/docs/reverse