Find Place

GET 
/places

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.

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

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

Rate Limiting and Cost

The rate limit for the Autocomplete API is 3000 requests per 5 minutes. HTTP Headers inform about the current rate limit.

Autocomplete API usage does not impact your balance, but resolving a suggestion to a full address requires a paid request. Autocomplete requests without subsequent paid requests may result in rate limitation or suspension.

Request

Query Parameters

api_key string
API Key
Your unique identifier that allows access to our APIs.
Begins ak_. Available from your dashboard
Example: ak_test
query string

Specifies the place you wish to query. Query can be shortened to q=

country_iso string
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
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
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 metres] Only one geospatial bias may be provided
Example: -2.095,57.15,100
bias_ip string

Possible values: [true]

Bias by Geolocation of IP

Biases search based on approximate geolocation of IP address.

Set bias_ip=true to enable.

Responses

200

Success

Response Headers

• X-RateLimit-Limit number

  The maximum number of requests that can be made in 5 minutes

• X-RateLimit-Remaining number

  The remaining requests within the current rate limit window

• X-RateLimit-Reset number

  The time when the rate limit window resets in Unix Time (seconds) or UTC Epoch seconds.

application/json

Schema

Schema

code int32required

Possible values: [2000]

message stringrequired

Possible values: [Success]

result objectrequired
hits object[]required
List of up to 10 matching places
Array [
oneOf
Place Description
name Place Namerequired
Place name
descriptive_name Descriptive Place Namerequired
Longer form description of the place.
country_iso Countryrequired
3 letter country code (ISO 3166-1)
id IDrequired
Unique identifier for place
]

Example (from schema)

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

Result

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

application/json

Schema

Schema

code int32required

API Response Code. Non 2xxx code indicates a failure. This code will provide a more specific reason when a failure occurs and facilitates debugging.

message stringrequired

Human readable error message supplied with every error response.

errors object[]
Array [
message stringrequired
Indicates location of error in request query or URL parameter
path stringrequired
Indicates location of error in request query or URL parameter
errorCode string
]

Example (from schema)

{
  "code": 0,
  "message": "string",
  "errors": [
    {
      "message": "should have required property 'type'",
      "path": ".query.type",
      "errorCode": "required.openapi.validation"
    }
  ]
}

Loading...