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.

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

      Represents a possible place given an autocomplete query.

      • id string

        Unique identifier for place

        Example

        geonames_7296662

      • name string

        Place name

        Example

        Strumpshaw

      • descriptive_name string

        Longer form description of the place.

        Example

        Strumpshaw, Norfolk, England

      • country_iso string

        3 letter country code (ISO 3166-1)

        Example

        GBR

The result sits inside the standard { result, code, message } envelope — see the API reference for the wrapper format.

Rate limiting

This endpoint returns rate-limit headers:

X-RateLimit-Limitnumber

Maximum requests per 5 minutes

X-RateLimit-Remainingnumber

Remaining requests in current window

X-RateLimit-Resetnumber

Unix timestamp when limit resets

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

Request

URL

https://api.ideal-postcodes.co.uk/v1/places?api_key=ak_test&query=london

curl

curl -G 'https://api.ideal-postcodes.co.uk/v1/places' \
  -d 'api_key=ak_test' \
  -d 'query=london'

JavaScript

const response = await fetch(
  'https://api.ideal-postcodes.co.uk/v1/places?' +
  new URLSearchParams({
    api_key: 'ak_test',
    query: 'london',
  })
);

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

Python

import requests

response = requests.get(
    "https://api.ideal-postcodes.co.uk/v1/places",
    params={
        "api_key": "ak_test",
        "query": "london",
    },
)
result = response.json()["result"]

Ruby

require "net/http"
require "json"

uri = URI("https://api.ideal-postcodes.co.uk/v1/places")
uri.query = URI.encode_www_form(api_key: "ak_test", query: "london")
result = JSON.parse(Net::HTTP.get(uri))["result"]

PHP

<?php
$response = file_get_contents(
  "https://api.ideal-postcodes.co.uk/v1/places?" .
  http_build_query([
    "api_key" => "ak_test",
    "query" => "london",
  ])
);
$result = json_decode($response, true)["result"];

Response

200 OK

{
  "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

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