Other/API Reference - Ideal Postcodes

Find Place

v1.0.0

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:

Retrieve place suggestions via /places
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

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

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

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

Input

{
  "type": "object",
  "properties": {
    "bias_country_iso": {
      "type": "string",
      "description": "Bias by country ISO code. Uses 3 letter country code (ISO 3166-1) standard.\nBias by multiple countries with a comma separated list. E.g. `GBR,IRL`"
    },
    "bias_ip": {
      "type": "string",
      "description": "Biases search based on approximate geolocation of IP address.\nSet `bias_ip=true` to enable.",
      "enum": [
        "true"
      ]
    },
    "bias_lonlat": {
      "type": "string",
      "description": "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"
    },
    "country_iso": {
      "type": "string",
      "description": "Filter by country ISO code. Uses 3 letter country code (ISO 3166-1) standard.\nFilter by multiple countries with a comma separated list. E.g. `GBR,IRL`"
    },
    "query": {
      "type": "string"
    }
  },
  "additionalProperties": false
}

Output

{
  "type": "object",
  "required": [
    "code",
    "message",
    "result"
  ],
  "properties": {
    "code": {
      "type": "integer",
      "format": "int32",
      "enum": [
        2000
      ]
    },
    "message": {
      "type": "string",
      "enum": [
        "Success"
      ]
    },
    "result": {
      "type": "object",
      "required": [
        "hits"
      ],
      "properties": {
        "hits": {
          "type": "array",
          "description": "List of up to 10 matching places\n",
          "items": {
            "type": "object"
          }
        }
      }
    }
  }
}