Place Search

Find Place

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.

get/places

Request

  • Base URL: https://api.addresszen.com/v1
  • URL: https://api.addresszen.com/v1/places
  • Auth: HTTP bearer

Query parameters

api_keystring

API Key

Your unique identifier that allows access to our APIs.

Begins ak_. Available from your dashboard.

querystring

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

country_isostring

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

bias_country_isostring

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

bias_lonlatstring

Bias by Geolocation

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

bias_ip'true'

Bias by Geolocation of IP

Biases search based on approximate geolocation of IP address.

Set bias_ip=true to enable.

Response

Success

code2000 required
message'Success' required

Example response

{
  "result": {
    "hits": [
      {
        "id": "geonames_7296662",
        "name": "Strumpshaw",
        "descriptive_name": "Strumpshaw, Norfolk, England",
        "country_iso": "GBR"
      }
    ]
  }
}

Changes

No recorded changes to this operation across all 1 revision of this API.