# Find Place

**GET** `/v1/places`

Returns place suggestions for a query, ranked by relevance. Places cover countries, administrative areas, capitals and other administrative seats.

## Implementing Place Autocomplete

Retrieving a full place takes two requests:

1. Fetch suggestions from `/places`
2. Fetch the place using the `id` on a suggestion

A query returns at most 10 suggestions. An empty query returns an empty result set. Show users the `descriptive_name`. The API drops suggestions that share one, so each name in a response identifies a single place.

## Rate Limiting and Cost

The rate limit is 3,000 requests per 5 minutes.

`/places` does not decrement your lookup balance, but resolving a suggestion to a full place does. We rate limit and then suspend integrations that repeatedly call `/places` without resolving.

## Example request

**URL**

```http
https://api.addresszen.com/v1/places?api_key=ak_test&query=london
```

**curl**

```bash
curl -G 'https://api.addresszen.com/v1/places' \
  -d 'api_key=ak_test' \
  -d 'query=london'
```

**JavaScript**

```javascript
const response = await fetch(
  'https://api.addresszen.com/v1/places?' +
  new URLSearchParams({
    api_key: 'ak_test',
    query: 'london',
  })
);

const { result } = await response.json();
```

**Python**

```python
import requests

response = requests.get(
    "https://api.addresszen.com/v1/places",
    params={
        "api_key": "ak_test",
        "query": "london",
    },
)
result = response.json()["result"]
```

**Ruby**

```ruby
require "net/http"
require "json"

uri = URI("https://api.addresszen.com/v1/places")
uri.query = URI.encode_www_form(api_key: "ak_test", query: "london")
result = JSON.parse(Net::HTTP.get(uri))["result"]
```

**PHP**

```php
<?php
$response = file_get_contents(
  "https://api.addresszen.com/v1/places?" .
  http_build_query([
    "api_key" => "ak_test",
    "query" => "london",
  ])
);
$result = json_decode($response, true)["result"];
```

## Example response

**200 OK**

```json
{
  "result": {
    "hits": [
      {
        "id": "geonames_2643743",
        "name": "London",
        "descriptive_name": "London, Greater London, England",
        "country_iso": "GBR"
      },
      {
        "id": "geonames_4517009",
        "name": "London",
        "descriptive_name": "London, Madison County, Ohio",
        "country_iso": "USA"
      },
      {
        "id": "geonames_4298960",
        "name": "London",
        "descriptive_name": "London, Laurel County, Kentucky",
        "country_iso": "USA"
      }
    ]
  },
  "code": 2000,
  "message": "Success"
}
```

**400 Bad Request**

response.json

```json
{
  "code": 4000,
  "message": "Invalid request"
}
```

## Query parameters

* `api_key` string optional

  **API Key**

  Your unique identifier that allows access to our APIs.

  Begins `ak_`. Available from your dashboard.

  Example: `ak_test`

* `query` string optional

  Specifies the place to query. Can be shortened to `q=`

* `country_iso` string optional

  **Filter by Country**

  Filter by country ISO code. Uses 3 letter country code (ISO 3166-1) standard.

  Filter by multiple countries with a comma separated list. E.g. `GBR,IRL`

  Example: `GBR`

* `bias_country_iso` string optional

  **Bias by Country** Bias by country ISO code. Uses 3 letter country code (ISO 3166-1) standard. Bias by multiple countries with a comma separated list. E.g. `GBR,IRL`

  Example: `GBR`

* `bias_lonlat` string optional

  **Bias by Geolocation**

  Bias search to a geospatial circle determined by an origin and radius in metres. Max radius is `50000`. Uses the format bias\_lonlat=\[longitude],\[latitude],\[radius in metres]. Only one geospatial bias may be provided.

  Example: `-2.095,57.15,100`

* `bias_ip` string optional

  **Bias by Geolocation of IP**

  Biases search based on approximate geolocation of IP address.

  Set `bias_ip=true` to enable.

  Enum: "true"

## Response

The `result.hits` array contains place suggestions. Each suggestion includes a unique ID for resolving the full place record via `/places/{place}`.

* `result` object

  * `hits` object\[]

    List of up to 10 matching places

    * PlaceSuggestion

The `result` sits inside the standard `{ result, code, message }` envelope — see the [API reference](/docs/api/api-reference.md) for the wrapper format.

### Rate limiting

This endpoint returns rate-limit headers:

`X-RateLimit-Limit`number

Maximum requests per 5 minutes

`X-RateLimit-Remaining`number

Remaining requests in current window

`X-RateLimit-Reset`number

Unix timestamp when limit resets

Autocomplete requests do not affect your lookup balance. However, resolving suggestions to full places requires a paid request.