API reference

# Retrieve suggestion

Retrieve the exact suggestion selected from autocomplete. A successful response costs one credit. IDs are opaque and tied to an index snapshot; a stale or unknown ID returns 404\. Request suggestions again after an index update. Unverified floor or unit suffixes are not part of the retrieved building.

Use cases, pricing and how it compares: [Address autocomplete API →](https://opengeocoding.com/address-autocomplete-api) 

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

POST GET /v1/retrieve

## 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.

* `id` string required  
Opaque ID returned by autocomplete. Do not parse or construct it.  
Up to 256 characters.

## Response 200

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

* `category` string  
Landmarks only: airport, station, attraction, museum, university, hospital or stadium. Empty for every other type.
* `countryCode` string
* `displayName` string
* `geoCoordinates` GeoCoordinates  
The point of the place, street, house, postcode or landmark. Places also carry their bounding box.

  * `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.
* `id` string  
Stable for one index, and opaque: a place, street, house, postcode or landmark.
* `type` string  
country, region, county, municipality, city, town, village, neighbourhood, street, address, postcode or landmark.
* `unverifiedSuffix` string  
User-entered floor/unit text, also kept in display\_name. Not verified: id and point still identify the building. Empty when no suffix interpretation was needed.

## 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/retrieve' \
  -H 'x-api-key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
  "id": "example-place-id"
}'
```

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/retrieve' \
  -H 'x-api-key: YOUR_API_KEY' \
  --data-urlencode 'id=example-place-id'
```

## Example response

200 · application/json 

```
{
  "countryCode": "dk",
  "displayName": "Copenhagen, Denmark",
  "geoCoordinates": {
    "lat": 55.676,
    "lon": 12.568
  },
  "id": "example-place-id",
  "type": "city"
}
```

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/retrieve