API reference

# Autocomplete

Complete an address or place while the last word is still unfinished. Free of credit charges, authenticated and rate-limited, including with zero credits. Returns labels and opaque IDs without coordinates or bounding boxes. Call /v1/retrieve with a selected ID to get its location for one credit. Filter by country, bias toward a position, or include notable landmarks linked to Wikidata.

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

No credits consumed · Authentication and account rate limit apply.

POST GET /v1/autocomplete

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

* `text` string required  
Address or place prefix. The last word may be unfinished. Trimmed; cannot be blank.  
Up to 500 characters.
* `countryCode` string  
Optional ISO 3166-1 alpha-2 country filter, for example dk.
* `focus` SuggestFocus  
Optional: the user's position. Places near it rank higher.

  * `lat` number  
  Latitude of the position to bias results toward.
  * `lon` number  
  Longitude of the position to bias results toward.
  * `scaleKm` integer  
  Distance scale of the location bias, in kilometres. Omitted or 0 uses 100.  
  Default: `100`. Range: 0–20000.
* `includeLandmarks` boolean  
Include notable OSM landmarks linked to Wikidata. Coverage is uneven; this is not a general business directory.  
Default: `false`.
* `limit` integer  
Maximum suggestions. Omitted or 0 uses the default of 5.  
Default: `5`. Range: 0–15.

## Response 200

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

* `suggestions` Suggestion\[\]  
Ranked suggestions.

  * `category` string  
  Landmarks only: airport, station, attraction, museum, university, hospital or stadium. Empty or omitted otherwise.
  * `countryCode` string  
  ISO 3166-1 alpha-2 country code.
  * `displayName` string  
  Human-readable label.
  * `id` string  
  Opaque identifier, stable for one index.
  * `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/autocomplete' \
  -H 'x-api-key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
  "countryCode": "dk",
  "focus": {
    "lat": 55.676,
    "lon": 12.568,
    "scaleKm": 100
  },
  "includeLandmarks": true,
  "limit": 5,
  "text": "Copenh"
}'
```

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/autocomplete' \
  -H 'x-api-key: YOUR_API_KEY' \
  --data-urlencode 'countryCode=dk' \
  --data-urlencode 'focus.lat=55.676' \
  --data-urlencode 'focus.lon=12.568' \
  --data-urlencode 'focus.scaleKm=100' \
  --data-urlencode 'includeLandmarks=true' \
  --data-urlencode 'limit=5' \
  --data-urlencode 'text=Copenh'
```

## Example response

200 · application/json 

```
{
  "suggestions": [
    {
      "countryCode": "dk",
      "displayName": "Copenhagen, Denmark",
      "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/autocomplete