This document tracks changes to our API services and client libraries

July 2019

core-node 1.1.0 (2019-07-18)


  • Agent Configuration: Allow GOT config (7d367f7)

June 2019

core-interface 1.3.0 (2019-06-09)


  • Error: Add specific 402 errors (270cfed)
  • Error: Allow optional metadata attribute (9d082a7)

core-interface 1.2.0 (2019-06-07)

Bug Fixes

  • Karma-Typescript: Explicitly exclude typings module (b11e9e3)


  • Client#checkKeyUsability: Implement key check (df6a611)
  • Client#lookupAddress: Implement address lookup (a53fb67)
  • Client#lookupPostcode: Implement and document postcode lookup (21e591e)
  • Client#lookupPostcode: Make results paginateable (a155f9f)
  • Client#lookupUdprn: Implement and document udprn search (e709853)
  • Client#lookupUmprn: Implement UMPRN lookup (14227c3)
  • Error: Export errors on Client (ff111f0)

core-interface 1.1.1 (2019-06-06)

Bug Fixes

  • Karma-Typescript: Explicitly exclude typings module (ff40c04)

core-interface 1.1.1 (2019-06-06)

Bug Fixes

  • Karma-Typescript: Explicitly exclude typings module (ff40c04)

core-interface 1.1.0 (2019-06-05)

Bug Fixes

  • Resource: Escape ID by default (b94d4f3)


  • Client: Export client config (8dd2a37)

core-interface 1.0.0 (2019-06-04)

Bug Fixes

  • Error: Invalid keys should return authorisation error (6bea2fb)


  • Addresses: Implement addresses resource (a37f907)
  • Addresses: Implement autocomplete (d6f940e)
  • Keys: Implement keys usage method (e005900)
  • Keys: Implement keys.retrieve (d7710f7)
  • Semantic Release: Automate git and npm releases (13b56a7)
  • UDPRN: Add udprn resource (e7c4e0f)
  • UMPRN: Implement UMPRN resource (efd6a7a)

api-fixtures 0.1.0 (2019-06-04)


  • Fixture Generation: New run on 2019-06-04 (620a140)
  • Keys: Add definitions (38f1f8e)
  • Semantic Release: Add automated semantic releases (3d66131)

api-typings 1.1.0 (2019-06-04)

Bug Fixes

  • Typings: Limits should be nullable (f506085)


  • Key: Add key usage typings (da95ab7)
  • Semantic Release: Add automated semantic releases (c2119ba)

core-node 1.0.0 (2019-06-09)

Bug Fixes


  • Deprecation Notice. The node.js client has been deprecated in favour of core-node

May 2019

  • URL Whitelisting. When checking for an allowed URL, both the Referer and (now also) the Origin headers will be tested for a match.

April 2019


0.0.1 (24/04/2019) Initial Release.

paf-api converts UK Clear Addressing into a simple HTTP API which can easily be deployed as a docker image or node process.

The full documentation for this project can be found at


We have published a draft OpenAPI v3 spec. This is available on GitHub and

0.0.1 (16/04/2019)


2.0.0 (19/04/2019)

  • Breaking Change: Require minimum node.js of 8.0.0
  • Ported to typescript (now exports typings)
  • Provides a cleaner, more modern API to extract and parse while supporting old methods
    • Add static methods to extract single datapoints
    • Add a ValidPostcode class with accessor methods which can be destructured
  • Updated documentation:
  • Added benchmarking


2.2.2 (24/04/2019)

  • Update dependencies
  • Update documentation
    • Reference PAF API
    • Reference typedocs

2.2.1 (02/04/2019)

  • Fix: Handle building names that contain range on rule 6

March 2019


2.2.0 (11/03/2019)

  • Formatting updates with guidance and examples outlined in the latest PAF Programmers Guide (Edition 7, Version 6):
    • Where a building name exception exists in rule 3, these names are no longer lower cased as documented in Table 27a. They now adhere to the (conflicting) example defined in Table 22
    • Building ranges which contain specific prefixes (e.g. Back of, Stalls, Maisonette) are no longer broken up across lines
  • Added line_1, line_2, line_3 and premise accessor methods on Address instances
  • Standardise project with prettier and @cablanchard/tslint
  • Use stardardised compile options from @cablanchard/tsconfig
  • Added benchmark suite


0.0.4 (25/03/2019)

  • Updated documentation
  • Add timestamp for each test run
  • Add runkit demo
  • Restructure test directory


2.0.3 (14/03/2019)

  • Standardise tsconfig
  • Standardise tslint
  • Apply new code formatting standards

10.1.3 Patch

  • Enable prometheus endpoint
  • .env files loaded upon application start. These are overwritten with explicit ENV variables

10.1.2 Patch

  • Fix: npm run setup on ubuntu
  • Dependency Update: switch from pmx to @pm2/io
  • Add abiltiy to define google analytics key with environment variable

10.1.1 Patch

10.1.0 Release

  • Updated ONSPD dataset to February 2019
  • Updated OS Names dataset to January 2019
  • Rebuild GSS codes for NHSHA and NUTS datasets
  • Dropped bunyan as dependency. Replaced with pino, a faster and actively maintained logging library
  • Log destination can now be assigned via env variable LOG_DESTINATION
    • "/absolute/path/to/file" logs to file
    • "stdout" logs to stdout
    • "perf" logs to stdout in extreme mode
  • Added ability to export prometheus metrics by basic auth protected /metrics endpoint. To enable include PROMETHEUS_USERNAME and PROMETHEUS_PASSWORD as environment variables. Those environment variables are required to authenticate using HTTP basic authentication
  • Updated dependencies
  • Added ability to configure application limits using environment variables
  • Amended npm run setup bash script to accept more configuration arguments

February 2019


2.0.2 (12/02/2019)

  • Move typescript into dev dependencies
  • Drop unused dependencies
  • Add runkit example


2.1.2 (12/02/2019)

  • Add runkit example
  • Use whitelist to generate npm package


1.0.1 (12/02/2019)

  • Add runkit example
  • Rename github repo to ideal-postcodes/postcode

1.0.0 (12/02/2019)

  • Support node 8 and above
  • Dependency updates


1.0.1 (12/02/2019)

  • Fix module import
  • Update documentation

1.0.0 (12/02/2019) Initial Release.

api-typings contains Typescript typings for the Ideal Postcodes API (

It specifies typings that define:

  • The basic JSON objects returned by our APIs (e.g. addresses Address, autocomplete suggestions AddressSuggestion, API key status KeyStatus)
  • The overall shape of JSON responses returned by the API (e.g. postcode lookups PostcodesResponse, address autocomplete queries AddressSuggestionResponse, address search queries AddressQueryResponse)

The full documentation for these types can be found at


0.0.3 (12/02/2019)

  • Fix: Pass Multiple Residence key to Multiple Residence address query


0.2.1 (11/02/2019)

  • Produce smaller build sizes by dropping extraneous package artefacts

 January 2019


0.0.2 Release. Initial Release

The @ideal-postcodes/api-fixtures javascript library provides HTTP API response data for This data is exported as Fixture object, containing a JSON response body (body) and HTTP Status Code (httpStatus).

These test objects may be readily imported into a test suite to stub out test methods or API requests.

Automatically generated documentation can be found at:

10.0.1 Release. Minor fixes

  • Fix: default config.js file would fail to load under NODE_ENV=production (thanks to @g-wilson)
  • Update dependencies
  • Added link to new Python lib (thanks to @raigad)
  • Clean up documentation

 November 2018

10.0.0 Release. ONSPD update. Backward breaking changes

  • Breaking Change Install dependencies upgraded. Going forward, only the following minimum versions will be tested:
    • Node.js 8
    • PostgreSQL 10
  • Postcode responses now include County Electoral Districts (ceds)
  • Updated documentation (outcodes, installation)
  • Updated dependencies
  • Updated GSS codes for missing wards
  • Updated ONSPD dataset to November 2018
  • Updated OS Names dataset to 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

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