# Places API

Query for geographical places across countries. Each query will return a list of place suggestions, which consists of a place name, descriptive name and id.

This API returns geographical information such as countries, capitals, administrative areas and more. It is ideal for correctly identifying a place along with any other details like geolocation.

Loading...

```
<div id="my-autocomplete-container"></div>
<div id="json-result" style="display:none"></div>
```

```
import accessibleAutocomplete from "accessible-autocomplete";

const results = {};
const api_key = "ak_test";

accessibleAutocomplete({
  element: document.querySelector("#my-autocomplete-container"),
  id: "place",
  source: async (query, cb) => {
    if (query === "") cb([]);
    const url = `https://api.ideal-postcodes.co.uk/v1/places?api_key=${api_key}&country_iso=gbr&query=${query}`;
    const data = await (await fetch(url)).json();
    cb(
      data.result.hits.map((h) => {
        results[h.descriptive_name] = h.id;
        return h.descriptive_name;
      }),
    );
  },
  onConfirm: async (value) => {
    if (!value) return;
    const jsonResult = document.getElementById("json-result");
    jsonResult.style.display = "block";
    const url = `https://api.ideal-postcodes.co.uk/v1/places/${results[value]}?api_key=${api_key}`;
    const jsonObj = await (await fetch(url)).json();
    jsonResult.innerHTML = `<pre><code>${JSON.stringify(jsonObj, null, 2)}</code></pre>`;
  },
});
```

## Implementing Place Autocomplete[​](#implementing-place-autocomplete "Direct link to Implementing Place Autocomplete")

Extracting the full information of a place is a 2 step process:

1. Retrieve place suggestions via /places
2. Retrieve the entire place with the ID provided in the suggestion

## Suggestion Format[​](#suggestion-format "Direct link to Suggestion Format")

Each place suggestion contains a descriptive name which you can provide to users to uniquely identify a place.

## Rate Limiting[​](#rate-limiting "Direct link to Rate Limiting")

You can make up to 3000 requests to the autocomplete API within a 5 minute span. The HTTP Header contains information on your current rate limit.

| Header                  | Description                                                                            |
| ----------------------- | -------------------------------------------------------------------------------------- |
| `X-RateLimit-Limit`     | The maximum number of requests that can be made in 5 minutes                           |
| `X-RateLimit-Remaining` | The remaining requests within the current rate limit window                            |
| `X-RateLimit-Reset`     | The time when the rate limit window resets in Unix Time (seconds) or UTC Epoch seconds |

## Pricing[​](#pricing "Direct link to Pricing")

This API currently does not affect your balance. However, resolving a suggestion into a full place requires a paid request.

info

Please note, this API is not intended as a standalone free resource. Integrations that consistently make autocomplete requests without a paid request to resolve a place may be disrupted via tightened rate limits.