Skip to main content

API Reference

A REST service over HTTPS, returning JSON and authenticated with an API key.

Getting Started​

All API methods are a GET, POST, PUT, DELETE or OPTIONS request. The API communicates over both HTTPS and plain HTTP using IPv4 and IPv6. We recommend HTTPS only, although HTTP is available. Appropriate HTTP status codes indicate the request status wherever possible.

Authentication​

Most requests require an API key. Authenticate by passing api_key in the query string:

api.ideal-postcodes.co.uk/v1/autocomplete/addresses?api_key=iddqd&q=parkside

Alternatively, pass it via the Authorization header:

Authorization: api_key="iddqd" [other_key="foo"]

Versioning​

The API is versioned with a URL prefix. The current version is /v1/. Breaking changes are released under a new version. The following changes are backwards-compatible and do not trigger a version bump:

  • Adding new properties to existing responses
  • Adding new endpoints
  • Adding new optional request parameters
  • Changing the order of properties in existing responses
  • Changing the autocomplete address suggestion format

Rate Limiting​

Each IP address is rate limited at 30 requests per second. Tripping the limit returns a 503. The autocomplete API carries an additional rate limit. If you expect to breach the limit, contact us and we can move you to a higher-limit endpoint.

Error Handling​

A successful lookup returns HTTP 200 and a response code of 2000 in the body. An error has occurred if the HTTP status code is not 200, ranging from a benign 404 (resource not found) to more urgent errors (insufficient balance, failed authentication, etc). See the Error Codes guide for the full list.

Response Codes​

The API returns two status indicators:

  • The HTTP Status in the status line, adhering to HTTP/1.1 wherever possible. 2XX indicates success; 4XX and 5XX indicate client and server errors respectively.
  • The API response code in the code property of the body, giving a more specific reason when a failure occurs.

Metadata​

Requests that affect your balance can be annotated with arbitrary metadata, stored with your lookup history and queryable later via the API or dashboard. See tagging.

Testing​

Each new account comes with a free test balance. Contact us if you need more for testing and integration.

OpenAPI Specification​

The machine-readable specification is available at:

Support​