Documentation / Introduction

Ideal Postcodes API Overview

Getting Started

  1. Create a key by signing up and creating an API Key
  2. Integrate in minutes using your key combined with our HTTPS endpoint or a library. Our test methods are listed in Resources documentation
  3. Take your key live by agreeing to the terms and conditions and purchasing some lookups

I Know What I Want! Take me to...

API Endpoint


All API methods are either a GET or POST request.

The API uses HTTPs only. Any plain HTTP connection is refused.


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

All responses are returned in JSON.


Each request requires an API key for authentication. Authenticate by passing an api_key with your unique key through the query string of the url.

For example,

Your API key can be found on your dashboard.


This API is versioned, so when we introduce a backwards incompatible update, you can rest assured that your app won't break.

Error Handling

A successful lookup is accompanied with a HTTP status code of 200 and a response code of 2000 (found in the body). To check for errors, simply check the HTTP status code for a non-200 response. Non-200 responses can range from the relatively benign 404 (your postcode was not found) to more urgent errors (your API Key ran out of credit, authentication failure, etc).

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


Each resource has a simple testing procedure available which does not utilise your account balance.


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.

$ curl

# result => 
foo && foo({"result":[
        "postcode":"ID1 1QD",
        "line_1":"Kingsley Hall",
        "line_2":"Powis Road",
        "organisation_name": "",
        "building_name": "Kingsley Hall",
        "udprn": 12345678,
        ... truncated ...

Rate Limiting

Each IP address is rate limited at 10 requests per second for version 1 of the API. Tripping the rate limit will result in a 503 HTTP Status response.

If you expect to breach the limit please contact us and we can move you to a high volume endpoint.