API reference

# Resolve regions

Resolve ISO 3166-2 administrative regions for coordinates. The response uses the same region entries as List regions.

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

POST /v1/resolve-region

## Request body

`application/json` · Up to 64 KiB. Unknown fields are rejected. Send your key in [x-api-key](https://opengeocoding.com/docs/authentication). 

* `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.

## Response 200

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

* `regions` Region\[\]  
Countries and administrative regions known to the index.

  * `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.

## 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/resolve-region' \
  -H 'x-api-key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
  "lat": 55.6761,
  "lon": 12.5683
}'
```

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.

## Example response

200 · application/json 

```
{
  "regions": [
    {
      "adminCode": "DK-84",
      "adminLevel": 4,
      "countryCode": "dk",
      "countryName": "Denmark",
      "enName": "Capital Region",
      "localName": "Region Hovedstaden"
    }
  ]
}
```

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/resolve-region