Ideal Postcodes

API Reference - Ideal Postcodes

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…

Maps & location#openapi#location

Fork copies the collection into your workspace, without the publisher's secrets, so you can add your own key and send requests. Star saves it to your starred APIs (Account › Marketplace) and helps others find it.

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 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.

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 CodeAPI CodeDescription
2002000Success. Request was completed successfully.

400 Bad Request

The request could not be understood due to some input error.

HTTP CodeAPI CodeDescription
4004000Invalid syntax submitted. Some part of your request was malformed or did not match our specifications.
4004001Validation failed on your submitted data. Some of the data you provided did not meet our validation requirements, e.g. string length.
4004005Invalid start date. Please ensure start dates are provided as a UTC Timestamp in milliseconds.
400 …

Endpoints 26

Address Search

  • GETFind Address/autocomplete/addresses?api_key=ak_test&query=string&context=string&limit=5&postcode_outward=1AA&postcode=SW1A 2AA&postcode_area=SW&postcode_sector=SW1A 2&post_town=London&uprn=100023336956&country=England&postcode_type=L&su_organisation_indicator=Y&box=2.095,57.15,-2.096,57.14&bias_postcode_outward=string&bias_postcode=/addresses?postcode=SW1A2AA&q=10&bias_postcode_area=The postcode area of SW1A 2AA and N1 6RT are SW and N respectively&bias_postcode_sector=SW1A 2AA is SW1A 2&bias_post_town=string&bias_thoroughfare=string&bias_country=string&bias_lonlat=-2.095,57.15,100&bias_ip=trueThe address autocomplete API returns a list of address suggestions that match the query ordered by relevance. This API can be used to power realtime address…
  • GETResolve Address (GBR)/autocomplete/addresses/:address/gbr?api_key=ak_testResolves an address autocompletion by its address ID. Resolved addresses (including global addresses) are returned in a UK format (up to 3 address lines)…
  • GETResolve Address (USA)/autocomplete/addresses/:address/usa?api_key=ak_testResolves an address autocompletion by its address ID. Resolved addresses (including global addresses) are returned in a US format (up to 2 address lines)…

Place Search

  • GETFind Place/places?api_key=ak_test&query=string&country_iso=GBR&bias_country_iso=GBR&bias_lonlat=-2.095,57.15,100&bias_ip=trueQuery for geographical places across countries. Each query will return a list of place suggestions, which consists of a place name, descriptive name and id.…
  • GETResolve Place/places/$:place?api_key=ak_testResolves a place autocompletion by its place ID.

UK

  • GETExtract Addresses/addresses?api_key=ak_test&query=string&limit=5&page=0&filter=line_1,line_2,line_3&lon=-0.12767&lat=51.503541&postcode_outward=1AA&postcode=SW1A 2AA&postcode_area=SW&postcode_sector=SW1A 2&post_town=London&uprn=100023336956&country=England&postcode_type=L&su_organisation_indicator=Y&box=2.095,57.15,-2.096,57.14&bias_postcode_outward=string&bias_postcode=/addresses?postcode=SW1A2AA&q=10&bias_postcode_area=The postcode area of SW1A 2AA and N1 6RT are SW and N respectively&bias_postcode_sector=SW1A 2AA is SW1A 2&bias_post_town=string&bias_thoroughfare=string&bias_country=string&bias_lonlat=-2.095,57.15,100Extract a list of complete addresses that match the query ordered by relevance score. This query accepts an optional limit and page query (defaults to 10 and…
  • POSTCleanse/cleanse/addresses?api_key=ak_testThe address cleanse API attempts to return the closest matching address for any given address inputs. We also return a number of Match Level indicators that…
  • GETLookup Postcode/postcodes/:postcode?api_key=ak_test&filter=line_1,line_2,line_3&page=0Returns the complete list of addresses for a postcode. Postcode searches are space and case insensitive. The Postcode Lookup API provides a JSON interface to…
  • GETRetrieve by UDPRN/udprn/:udprn?api_key=ak_test&filter=line_1,line_2,line_3Returns an address as identified by its Unique Delivery Point Reference Number (UDPRN). You may find it useful to store UDPRN information as it can be used to…
  • GETRetrieve by UMPRN/umprn/:umprn?api_key=ak_test&filter=line_1,line_2,line_3Returns a multiple occupancy address identifited via its UMPRN (Multiple Residence Unique ID). UMPRNs are a unique numeric code for any Multiple Residence…

Keys

  • GETAvailability/keys/:keyReturns public information on key. Currently only returns whether the key is currently useable via the available property. Use this to discover if the key is…
  • GETDetails/keys/:key/details?user_token=uk_B59ScW1p1HHouf1VqclEPZUxReturns private data on the key including remaining lookups, available datasets and usage limits.
  • GETLogs (CSV)/keys/:key/lookups?start=1418556452651&end=1418556477882&licensee=sk_hk71kco54zGSGvF9eXXrvvnMOLLNhReports lookup information on a key for paid lookups. This method requires a user_token, which can be found on your accounts page. A maximum interval of 90…
  • GETUsage Stats/keys/:key/usage?start=1418556452651&end=1418556477882&tags=foo,bar&licensee=sk_hk71kco54zGSGvF9eXXrvvnMOLLNhReports the number of lookups consumed on a key for a range of days. A maximum interval of 90 days can be provided for analysis. If no start or end date is…

Licensees

  • GETList/keys/:key/licensees?starting_after=0&user_token=uk_B59ScW1p1HHouf1VqclEPZUx&limit=5&query=stringReturns a list of licensees for a key.
  • POSTCreate/keys/:key/licensees?user_token=uk_B59ScW1p1HHouf1VqclEPZUxCreate a licensee for the specified API Key.
  • GETRetrieve/keys/:key/licensees/:licensee?user_token=uk_B59ScW1p1HHouf1VqclEPZUxReturns licensee information as identified by the licensee key.
  • PUTUpdate/keys/:key/licensees/:licensee?user_token=uk_B59ScW1p1HHouf1VqclEPZUxUpdate Licensee
  • DELETECancel/keys/:key/licensees/:licensee?user_token=uk_B59ScW1p1HHouf1VqclEPZUxCancels a licensee key. This renders a licensee unusable. This action can be reversed if you get in contact with us.

Configs

  • GETList/keys/:key/configs?user_token=uk_B59ScW1p1HHouf1VqclEPZUxLists configurations associated with a key
  • POSTCreate/keys/:key/configs?user_token=uk_B59ScW1p1HHouf1VqclEPZUxCreate a config
  • GETRetrieve/keys/:key/configs/:configRetrieve config object by name
  • POSTUpdate/keys/:key/configs/:config?user_token=uk_B59ScW1p1HHouf1VqclEPZUxUpdates configuration object
  • DELETEDelete/keys/:key/configs/:config?user_token=uk_B59ScW1p1HHouf1VqclEPZUxPermanently deletes a configuration object.

Emails

  • GETEmail Validation/emails?api_key=ak_test&query=stringQuery for and validate email addresses.

Phone Numbers

  • GETPhone Number Validation/phone_numbers?api_key=ak_test&query=stringQuery for and validate phone numbers.

API details

Base URL
https://api.ideal-postcodes.co.uk/v1
Authentication
None declared in the description
Operations
26 operations on 20 pathsGET 19POST 4DELETE 2PUT 1
Main resources
Configs 5Licensees 5UK 5Keys 4Address Search 3Place Search 2Emails 1Phone Numbers 1
Response formats
application/json text/csv
Description format
OpenAPI 3.0.3, API version 3.7.0
Listed from
APIs.guru OpenAPI Directory (CC0-1.0)
Source updated

How to test the API Reference - Ideal Postcodes in Swastik Codes

  1. Open the APISelect “Fork & run in Swastik Codes” on this page. Sign in or create a free account if asked.
  2. Fork it into your workspaceChoose a workspace. You get your own copy of the API Reference - Ideal Postcodes collection, without the publisher's secrets.
  3. Add your credentialsOpen the collection's variables or an environment and enter your API key or token, if the API needs one.
  4. Send a requestPick an endpoint, for example “Find Address” (GET /autocomplete/addresses?api_key=ak_test&query=string&context=string&limit=5&postcode_outward=1AA&postcode=SW1A 2AA&postcode_area=SW&postcode_sector=SW1A 2&post_town=London&uprn=100023336956&country=England&postcode_type=L&su_organisation_indicator=Y&box=2.095,57.15,-2.096,57.14&bias_postcode_outward=string&bias_postcode=/addresses?postcode=SW1A2AA&q=10&bias_postcode_area=The postcode area of SW1A 2AA and N1 6RT are SW and N respectively&bias_postcode_sector=SW1A 2AA is SW1A 2&bias_post_town=string&bias_thoroughfare=string&bias_country=string&bias_lonlat=-2.095,57.15,100&bias_ip=true), and press Send. Check the response, add tests and run the whole collection with the runner.

Frequently asked questions

What is the API Reference - Ideal Postcodes?

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… It is listed under Maps & location and has 26 endpoints.

Who publishes the API Reference - Ideal Postcodes?

It is listed from Ideal Postcodes's public API description (an OpenAPI document), not published by Ideal Postcodes on Swastik Codes. Anyone who controls ideal-postcodes.co.uk can claim the profile by adding a DNS TXT record.

What is the base URL of the API Reference - Ideal Postcodes?

Requests go to https://api.ideal-postcodes.co.uk/v1. Endpoint paths are added to this base URL.

How do I authenticate with the API Reference - Ideal Postcodes?

Its OpenAPI description does not declare an authentication scheme. Some endpoints may be open; check the provider's documentation before relying on that.

How many endpoints does the API Reference - Ideal Postcodes have?

26 operations on 20 paths (19 GET, 4 POST, 2 DELETE, 1 PUT). The largest groups are Configs, Licensees, UK, Keys.

Is forking the API Reference - Ideal Postcodes free?

Yes. Forking copies the collection into your workspace for free. It has been starred 0 times and forked 0 times.

Suggest an API

Tell us which public API is missing. We check it, then add it here with its endpoints when it has an OpenAPI (Swagger) description.