API Reference - Ideal Postcodes API

Overview

# Getting Started ## Overview ### Access 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 recommend using HTTPS only although HTTP is available. We use appropriate HTTP status codes where possible to indicate the request status. ### Rate Limiting Each IP address is rate limited at 30 requests per second. Tripping the rate limit will result in a 503 response. The autocomplete API also has an additional rate limit. If you expect to breach the limit please contact us and we can move you to an endpoint with a higher limit. ### JSONP [JSONP](http://en.wikipedia.org/wiki/JSONP) requests are supported. Include a `callback=` in your request as a query parameter. Your results return wrapped in a function designated by your request. ## Authentication Most requests require an **API key** for authentication. Authenticate by passing an `api_key` as part of the query string. For example: ``` api.ideal-postcodes.co.uk/v1/autocomplete/addresses?api_key=iddqd&q=parkside ``` Alternatively, authentication can be transmitted via the `Authorization` header using the following scheme: ``` Authorization: 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 the following changes are 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 a benign 404 (resource not found) to more urgent errors (your API Key ran out of credit, failed authentication, etc). ## Testing Each new account comes with a free test balance. Contact us if you need more for testing and integration. ### Community Key Our documentation and demos make heavy use of our community key `iddqd`. This allows for convenient access for trialing the API. 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 trial the API. Thank you! ## 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](https://docs.ideal-postcodes.co.uk/docs/guides/tags). # Response Codes The API returns two indicators to help you to determine the status of each HTTP request. The first is the **HTTP Status**, which is found in the status-line of all HTTP requests. The API will return status codes that adhere to HTTP /1.1 Specifications wherever possible. `2XX` status codes indicates success while `4XX` and `5XX` indicate client and server errors respectively. The second is the **API response code**, which can be found in the `code` property of the response body. This code will provide a more specific reason if a failure has occurred and can point you in the right direction when debugging. Please use the glossary of code numbers and HTTP status codes below when debugging your requests. ## 200 Request Success | HTTP Code | API Code | Description | | --------- | -------- | -------------------------------------------- | | 200 | 2000 | Success. Request was completed s

API Reference - Ideal Postcodes is a geocoding API from ideal-postcodes.co.uk. It needs no API key. It is served over HTTPS. Its OpenAPI description documents 26 endpoints.

At a glance

Authentication

No auth

HTTPS

Yes

CORS

Unknown

Category

Geocoding

Base URL

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

Version

3.7.0

Endpoints

26

OpenAPI

Specification ↗

Spec updated

2023-03-06

Make a first request

Replace the placeholders; the documentation says exactly where credentials go.

curl -X GET "https://api.ideal-postcodes.co.uk/v1/addresses" \
  -H "Accept: application/json"

const response = await fetch("https://api.ideal-postcodes.co.uk/v1/addresses", {
  method: "GET",
  headers: {
    "Accept": "application/json",
  },
});
const data = await response.json();
console.log(data);

import requests

response = requests.request(
    "GET",
    "https://api.ideal-postcodes.co.uk/v1/addresses",
    headers={
    "Accept": "application/json",
    },
    timeout=30,
)
print(response.json())

Endpoints

Questions