Developer Documentation

Getting Started

Create a Key

Sign up for an Ideal Postcodes account. Accounts and API keys are free. Once signed in, you may create keys via your dashboard and use them to query for addressing data.

Implement & Test

All keys are instantly usable on our API with test requests. We provide a wide range of test methods to allow you to develop a rigorous and correct implementation. Test requests do not affect your lookup balance.

Go Live

To take your key live and query genuine addressing data, you will need to purchase a lookup balance for your key. Requests that retrieve addressing data (i.e. using the /addresses and /postcodes API) will deduct one lookup from your balance. You can also setup automated top-ups to reload your balance when it runs low.

How-To Links

Endpoint

https://api.ideal-postcodes.co.uk

Methods

All API methods are either a GET, POST or OPTIONS request.

The API communicates over both HTTPS and plain HTTP using IPv4 and IPv6. We strongly recommend using HTTPS exclusively.

Responses

We use appropriate HTTP status codes where possible to indicate the request status.

All responses are returned in JSON.

Authentication

Most requests require an API key for authentication. Authenticate by passing an api_key as part of the query string.

For example:

https://api.ideal-postcodes.co.uk/v1/postcodes/ID11QD?api_key=iddqd

Alternatively, query string authentication can be returned in the Authorization header using the following scheme:

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

Versioning

This API is versioned with a simple prefix in the URL. The current version is /v1/. We will maintain backwards-compatibility by releasing breaking changes under a new version.

Please note that we consider the following changes backwards-compatible:

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

Error Handling

A successful lookup is accompanied with a HTTP status code of 200 and a response code of 2000 (found in the body).

An error has occurred if the HTTP status code is not 200. Errors can range from the a benign 404 (resource not found) to more urgent errors (your API Key ran out of credit, failed authentication, etc).

Note that JSONP requests respond with a HTTP status code of 200 as all other responses are ignored by most browsers.

Testing

Each method has a simple testing procedure available which does not affect your account balance. You can find these methods here.

JSONP

JSONP requests are supported. Simply include a callback= in your request as a query parameter and your result will be returned wrapped in a function designated by your request.

Metadata

Requests that affect your balance may be annotated with arbitrary metadata. This data is stored along with your lookup history and can be queried at a later date via the API or the dashboard. We call the ability to label your requests tagging.

Rate Limiting

Each IP address is rate limited at 25 requests per second. Tripping the rate limit will result in a 503 response.

The autocomplete API also has an additional rate limit. The relevant documentation can be found in the autocomplete documentation.

If you expect to breach the limit please contact us and we can move you to an endpoint with a higher limit.

Community Key

Our documentation and demos make heavy use of our community key iddqd, which allows convenient access for trialing the API.

Although many restrictions on this key are relaxed to allow developers make test requests, this key has a limit of 15 lookups per IP address per day as well as a daily usage cap. If you hit any limit restrictions, you can continue testing the API by creating a key of your own and using our free test methods.

Please be kind with the community key. We're trusting everyone to use it responsibly so that other developers may quickly trial the API. Thank you!

OpenAPI

We are currently building out an OpenAPI v3 specification. The repository for this can be found at github.com/ideal-postcodes/openapi.

The generated documentation can be found at openapi.ideal-postcodes.dev.