This document tracks changes to our API services and client libraries

October 2018

9.0.3 Release. Minor updates and fixes. Many related to docker improvements

  • Fix: /outcodes endpoint returned a result attribute rather than an error attribute for a not found response
  • Docker Related: Application gracefully exits from SIGTERM
  • Docker Related: Application writes logs to stdout when NODE_ENV=production
  • DockerFile:
    • Added healthcheck
    • Run application as non-root user (node)
    • Reduced image size: delete npm cache, added .dockerignore
    • New docker file that builds a postgresql container that preloads dataset Sublicensees API. The daily limit was not configurable when a sublicensee was registered for the first time. This has been fixed

September 2018

  • Sublicensees API. The daily limit was not configurable when a sublicensee was registered for the first time. This has been fixed

August 2018

9.0.2 Release

  • Updated ONSPD dataset to August 2018
  • Updated OS Names dataset to July 2018

June 2018

9.0.1 Release

  • Fixed regression. WGS84 geolocations for points with no assigned geolocation (in postcodes and terminated_postcodes relations) returned 0 and 99.9999 (ONSPD default identifiers for no geolocation) instead of null and null.
  • Updated pg_dump released in 9.0.0 to incorporate above fix
  • Updated noticeboard

9.0.0 Release

  • Breaking Change Updated postcode and terminated_postcode models for the new schema in ONSPD CSV file. This means >9.0.0 will not be able to import ONSPD CSV files produced before May 2018. pg_dump imports will not be affected
  • Added package.lock file
  • Updated wards, districts, nuts, ccgs GSS Codes
  • Updated ONSPD dataset to May 2018
  • Updated OS Names dataset to April 2018

May 2018

GDPR Related Updates

  • Overview of the changes and our current data protection strategy as a data processor can be found here
  • Updated Terms of Service. This document now includes a Data Protection section which will provide contractual assurance that we shall uphold the requirements of GDPR as a [sub]processor of personal data
  • deprecation
  • /keys/:key/lookups data redaction. IP Address, search and URL data will be redacted if older than 28 days by default

March 2018


  • 3.0.7 release
  • Fix: Custom API endpoint can be passed to setup configuration object
  • Fix: Class Methods lookupPostcode, lookupAddress and checkKey accept custom endpoint
  • Reduce library size. Commented out optional configuration attributes which currently serve as documentation. Will be removed altogether in final minified payload

8.0.0 Release

  • Breaking Change Terminated Postcode schema has been updated to include geolocation attributes: longitude, latitude, northings, eastings and location
  • Extended /terminated_postcodes endpoint to include longitude and latitude
  • Updated parishes GSS Codes
  • Tidy up of ONSPD and Open Names import scripts. Now named postcodesio-onspd and postcodesio-oson respectively. Dropped unmaintained update script
  • Updated ONSPD dataset to Feb 2018
  • Updated OS Names dataset to Jan 2018

January 2018

7.0.0 Release

  • Fixed performance regression on /places endpoint where postgresql's unaccent() causing index miss

November 2017


  • 3.0.6 release
  • Fix: Sublicensee key now passed into key checking API calls if check_key: true
  • Added placeholder to input field. The placeholder is determined by the placeholder_label attribute
  • Added onDropdownDestroyed destroyed callback, invoked when dropdown is removed from DOM following a new search


  • 1.0.0 release
  • Backwards Breaking Change. Now supports CommonJS and AMD imports. ideal-postcodes-core will be available globally as IdealPostcodes even if module system is detected. To remove this from the global object use IdealPostcodes.removeGlobalReference

July 2017

  • IP Forwarding. You may now forward IP addresses for daily individual usage limiting via a IDPC-Source-IP header, if enabled from the dashboard. Read the documentation to find out more

April 2017


  • 0.2.1 release
  • Fix: Pass licensee information into autocomplete requests

March 2017

  • HTTP2 Enabled. HTTP2 has been enabled across all webservers


  • 0.3.5 release
  • Add Opera 12.16 and below to legacy browser support

February 2017

  • Licensee Authentication. licensee may now be included in the Authorization header. The schema is as follows: Authorization: IDEALPOSTCODES api_key="iddqd" licensee="licensee_key".


  • 0.3.4 release
  • Fix client side caching
  • Fix caching of UDPRN and UMPRN queries
  • Extend autocomplete callback to return original request options
  • Export searchFilter interface
  • Added postcode_outward and post_town parameters to lookupAutocomplete and lookupAddress methods
  • Added limit parameter to lookupAutocomplete method
  • Fixed caching to account for pagination and other query parameters
  • Expose methods to enable, disable and clear cache


  • Set query filters for post town and outward codes with controller.setSearchFilter
  • Enforce strict ordering autocomplete suggestions
  • Use default pointer and more consistent styling for error messages
  • Add titleizePostTown config parameter which converts post towns into title case (from upper case)

January 2017

  • Address Search. The address search API now allows results to be filtered by outward codes (postcode_outward=)
  • Autocomplete Search. The autocomplete API now allows results to be filtered by outward codes (postcode_outward=)

December 2016

  • Autocomplete testing. The autocomplete API will now return a test response for a query which matches /ID1\s?1QD/
  • Address, UDPRN, UMPRN testing. The /addresses/:udprn, /udprn/:id/ and /umprn/:id/ endpoints now return additional test addresses for IDs -10 and -11

October 2016

  • Autocomplete limit. The address autocomplete suggestion endpoint now accepts a limit= parameter to raise or lower the number of suggestions you would like to receive


  • 0.1.1 release
  • Prevent interface attaching if it already exists
  • CSS fix for .hidden dropdown

September 2016


  • 0.1.0 initial release
  • Enable licensee checking for key usability
  • Enable tagging, licensee checking and filtering on address ID lookup

August 2016

  • Daily Usage Limit for Sublicensed Keys. You may now set a daily limit on sublicensed keys and receive notifications when these limits have been reached


  • 0.2.0 release
  • checkKeyUsability now accepts options as first argument
  • Added JSONP fallback
  • Restructured library
  • Removed IIFE from compiled output
  • Autocomplete uses querystring auth unless strictly enabled

July 2016

  • URL Whitelisted for Sublicensed Keys. You may now provide up to 5 URLs to be whitelisted on a per-licensee basis
  • Additional behaviour /keys/:key for sublicensed keys. The public keys endpoint now performs additional checks for sublicensed keys. Specifically, if a licensee key is present and if a URL whitelisting check fails


  • 0.1.2 initial release


  • 3.0.4 release
  • Added shouldLookupTrigger callback

June 2016

  • Autocomplete endpoint. Our new autocomplete endpoint is available
  • UDPRN and UMPRN endpoints. New endpoints for resolving autocomplete suggestions by ID are available
  • Querying for licensees. You may now query for licensees on /keys/:key/licensees using the query= querysting

May 2016


  • 3.0.3 release
  • Added licensee attribute to configuration object
  • API Request timeouts now bubble up to API. Default request timeout increased to 10 seconds

April 2016

  • HTTP Header Authentication. api_key and user_token may be dropped in favour of using the Authorization header. The schema is as follows: Authorization: IDEALPOSTCODES api_key="iddqd" [user_token="my_secret_token"].
  • UMPRN data. UMPRN number (for multiple residence households) is now available.
  • /v1/addresses. The address search API now supports common abbreviations like 'rd', 'ln' and 'st'.
  • Channel Islands & Isle of Man Geolocation. High level (approximate) geolocations have been allocated to the Channel Islands & Isle of Man based on outward code for the address.

March 2016

  • /v1/postcodes pagination. A small fraction of postcodes with Multiple Residence addresses yield more than 100 residences and so is cut off by the API. Multiple Residence keys allow for pagination on the postcodes (/v1/postcodes) endpoint.
  • /v1/addresses postcode match. Previously an exact postcode match on the addresses (/v1/addresses) endpoint would ignore user specified page or limit and return the entire address list (similar to the behaviour of the postcodes endpoint). We've now also allowed the addresses endpoint to be sensitive to page number for an exact postcode match. However user specified limit will continue to be discarded and fixed at 100 results.

February 2016

  • Address Sort. Address sorting has been improved to better handle a number of corner case addresses.

January 2016

  • Result Filtering. /postcodes/:postcode, /addresses?query and /addresses/:udprn endpoints now accept a filter argument that whitelist address attributes to be returned. This is ideal for use cases when HTTP payload size is particularly important.


  • 3.0.1 release
  • Significant API backwards incompatible API changes
  • Simplified $.idealPostcodes.lookupPostcode and $.idealPostcodes.lookupAddress APIs
  • Added request tagging read more here
  • Added new callbacks and renamed existing callbacks
  • onLookupSuccess is now onSearchCompleted
  • Added callbacks onAddressesReceived, onDropdownCreated, onLookupTriggered, onSearchError
  • Added ability to insert error messages into custom containers

December 2015

  • Sublicensed Keys Beta. Beta programme for Sublicensed Keys is open. Sublicensed Keys allow you to license other organisations or individuals under Royal Mail's terms under a single key that you control

September 2015

  • IPv6 is here. API now accepts IPv6 requests.

July 2015

  • New Addressing Data. API now returns additonal "Multiple Residence Dataset". To access this data, a new Multiple Residence key needs to be created. Find out more here.

June 2015

  • Update. /addresses?query returns a maximum of 100 addresses per search and a default of 10.

May 2015

  • Method Extended. /keys/:key now provides information on lookup purchases such as the number of lookups consumed and when that batch will expire.
  • Request Metadata Added. Requests that affect your lookup balance now accepts metadata in the form of tags= in your query string. Find out more here.

April 2015

  • New County Data. Added more county data. API now returns traditional_county, postal_county and administrative_county. county field now returns postal county. If no postal county exists, this field falls back to administrative county and then traditional county. County data source has been switched from ONS to Royal Mail.

  • Update. /keys/:key/usage now returns dates in UTC (rather than local time) for daily usage counts.

March 2015

  • New Method. Added /keys/:key/lookups. You can now request a CSV download of paid requests made on your key. This will list individual requests made on your key over a custom time interval.


  • 2.2.4 release
  • Configuration object now accepts dropdown_container to specify a custom container to display the results dropdown

February 2015

  • New Method. Added /keys/:key/usage. You can now query your key's API usage (for paid methods) over a custom time interval using this endpoint.


  • 2.2.2 release
  • onLookupSuccess is now also triggered when pre-flight postcode validation fails

January 2015

  • The address query API, /addresses?q=:address now returns a full list of addresses if the query is a match for a postcode. These queries will ignore limit and page arguments.

December 2014

  • The API now allows for plain HTTP requests to accommodate certain users. Although this option is available, please use HTTPS whenever possible. All our current and future libraries will continue to use encryption.

November 2014


  • 2.2.1 release
  • Added optional max_results for address searches
  • Added fallback to address search if address_search: true. Any postcode search which does not validate as a postcode will be passed through to the address search API
  • Key checks are only performed against the API if the plugin is invoked in the DOM and not upon initialisation
  • Results from a key check are now cached and multiple calls to the same key are merged into the same request

August 2014

  • /keys/:key now accepts an optional secret user token. If provided, this lookup will reveal additional private information about the key such as lookups remaining and key settings.
  • Addresses model now also returns a premise attribute.

July 2014

  • New Method. Added /addresses. You can now query for addresses (e.g. "10 Downing Street") using the addresses resource. This resource also comes with a new method /addresses/:udprn to extract an address given its UDPRN.
  • Free routes (like geolocation lookups) are now also subject to your custom URL and Daily limits placed on your key.
  • Addresses now return country data.


  • 2.1.1 release
  • Changed lookup behaviour. Looking up a new postcode no longer clears existing results

June 2014

  • Added /keys/:key endpoint. Method can be used to find out if an API Key is in a usable state.
  • Requests to /postcodes/:postcode has been expanded to include administrative county, district and ward data.
  • Added county, district and ward data to address results.


  • 2.1.0 release
  • Changed lookup behaviour. Looking up a new postcode no longer clears existing results
  • Added option to strip organisation name from address lines
  • Deprecated old configuration method of .setup() followed by $.fn.setupPostcodeLookup
  • Added pre-initialisation checks
  • Added callbacks: onLoaded, onCheckFailed
  • Bug fix for IE7

May 2014

  • Added CORS support to /postcodes routes.

January 2014

  • Rate limit has been bumped to 10 requests per second per IP address for version 1 of the API. Anyone expecting to breach this limit should contact us so we can make arrangements for you.

October 2013

  • Integrated location data from the Ordnance Survey
  • Requests to /postcodes/:postcode will now yield longitude and latitude (WGS84/ETRS89) as well as northings and eastings (National Grid), accurate to the postcode level.
  • Looking up longitude and latitude on the postcodes resource, /postcodes?lonlat=, will provide nearest postcodes (in order of distance) with optional radius and limit parameters to control lookup radius and maximum result size respectively. For example,
curl \
    -d lonlat=-0.2086443627,51.48994883 \
    -d api_key=iddqd

September 2013

  • Requests to /postcodes/:postcode has been expanded to return all PAF data (not just formatted 3 lined addresses, a post town and postcode).
  • We have revised the documentation to reflect the availability of new address data. To see the changes please visit the postcodes resource document and for a definition of these new data points please visit the new address data document.
  • The jQuery plugin, Ruby wrapper and Node wrapper have all been updated accordingly.