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=parksideAlternatively, 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 Code | API Code | Description |
|---|---|---|
| 200 | 2000 | Success. Request was completed successfully. |
400 Bad Request
The request could not be understood due to some input error.
| HTTP Code | API Code | Description |
|---|---|---|
| 400 | 4000 | Invalid syntax submitted. Some part of your request was malformed or did not match our specifications. |
| 400 | 4001 | Validation failed on your submitted data. Some of the data you provided did not meet our validation requirements, e.g. string length. |
| 400 | 4005 | Invalid 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/jsontext/csv- Description format
- OpenAPI 3.0.3, API version
3.7.0 - Links
- Documentation · OpenAPI document · Terms of service · Support
- Listed from
- APIs.guru OpenAPI Directory (CC0-1.0)
Source updated
How to test the API Reference - Ideal Postcodes in Swastik Codes
- Open the APISelect “Fork & run in Swastik Codes” on this page. Sign in or create a free account if asked.
- Fork it into your workspaceChoose a workspace. You get your own copy of the API Reference - Ideal Postcodes collection, without the publisher's secrets.
- Add your credentialsOpen the collection's variables or an environment and enter your API key or token, if the API needs one.
- 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.