Identifying an address

Introduction

WhenFresh assigns a single postal address file key to each postal address in the UK, which we commonly refer to as the address key.

With this identifier, you can access the details about an address, purchase variables from its resource catalog, or navigate to resources of interest (postcodes, titles, spatial address).

We provide multiple ways to discover that postal address file key.

Address matching

When you hold on file a number of addresses, and you only hold parts of that address, WhenFresh provides an address matching service.

You provide us with a flat file containing the addresses you hold on file, over a secure SFTP connection, and we ship back an "append": we provide you with the address key appended to each row in that file.

You can then store the resulting dataset, and start purchasing our variables immediately.

Please contact us for more details.

Royal Mail PAF

Royal Mail publishes the Postal Address File, commonly called PAF, which contains all known delivery points in the United Kingdom. It contains over 29 million addresses used daily to deliver the mail.

WhenFresh derives its address key from two identifiers defined in Royal Mail datasets:

  • The first one uniquely identifies a specific "post box", and is called the Unique Delivery Point Reference Number, or UDPRN.
  • The second one comes from another Royal Mail dataset, the Multi Residency file. It allows identification of addresses that may share the same postbox, such as student accommodations, businesses or camping sites, using another unique identifier called the Unique Multiple Residence Reference Number, or UMRRN.

To obtain the address key from those two numbers, you can compute the base36 encoding of each, and separate them with the unicode character U+00B7 middle dot (·), which can be URI encoded as %C2%B7.

When the UMRRN is not available, its value is set to 0.

For example, with a UDPRN of 23747771, and no UMRRN, the former gets Base36-encoded as e4zwb, the UMRRN becomes 0, the resulting address key is e4zwb·0, the URI encoded version of this key is e4zwb%C2%B70.

From this WhenFresh address key, you can start interacting with the API with the following two URI templates, in which you'll replace {key} with the address key defined above.

The Postal Address URI template: https://api.whenfresh.com/world/GB/addresses/{key}

The Postal Address Resource Catalog URI (to purchase variables): https://api.whenfresh.com/world/GB/addresses/{key}/catalog

Searching by postcode

You can search for an address by providing a postcode to the postcode search resource.

We will return, for any postcode, the list of address keys, and a label, containing a concatenation of the various lines in an address.

This is useful if you wish to provide an interactive application, similar to our demo sites, or if you wish to try and match an address manually.

Ordnance Survey Spatial Address

Ordnance Survey is Great Britain's national mapping agency. They publish multiple datasets, such as OS AddressBase and OS MasterMap.

In each of those datasets, Ordnance Survey uses a unique identifier called the Unique Property Reference Number, or UPRN, which identify anything from a lamp post to a postal address.

The WhenFresh API allows you to purchase a list of address keys from an Ordnance Survey UPRN, and to purchase the UPRN for a Postal Address.

To get a Postal Address Key from a UPRN, you can create a URI from the OS UPRN Uri Template by using the URI template described in our Purchasing from a Resource Catalog documentation page, and chose the variable from the CLS OS MasterMap dataset using the following variable ID: https://api.whenfresh.com/vars/CLS/OS MasterMap#Royal Mail/Postal Address File/Postal Address/Property Address Key as described in our Catalog Browser.

Title deeds

Properties may be associated with title deeds, which record their chain of ownership.

Using the WhenFresh API, you can retrieve address keys from Land Registry in England & Wales (using a dataset provided by CLS), as well as from Register of Scotland in Scotland.

It's equally possible to purchase title numbers from an address key.

Please contact us for more details.

Integrate with external address pickers

Most address picker services will provide you with Royal Mail Postal Address UDPRN. To help you get started more quickly, we've put together some samples.