Identifying Addresses

Introduction

The WhenFresh API uses the Ordnance Survey Unique Property Reference Number (UPRN) as its primary identifier for addresses in the UK.

With a UPRN, you can access the details about an address, purchase variables from its resource catalog, or navigate to related resources (postcodes, titles).

We provide multiple ways to discover a UPRN for an address:

Address matching

For scenarios where you don't already have an identifier (e.g. UPRN, Title Number) for your addresses, we offer a number of address matching functions that will take a postcode and address string and return the appropriate UPRN for the address.

API

Exact matching

For non-interactive scenarios via the API we have the WhenFresh Address Matching function. This will exactly match an address string to Royal Mail PAF and return the corresponding UPRN for the address.

Multiple potential matches

For interactive scenarios via the API, or for fallback when exact matching has been unsuccessful, we have the Ordnance Survey Address Matching function. This will match an address string to Ordnance Survey AddressBase Premium and return multiple potential matches (along with confidence scores), with the corresponding UPRN for each of the addresses.

Batch

You can 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 UPRN appended to each row in that file.

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

If this is of interest to you, please contact us for more details.

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 spatial addresses with their UPRNs 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.

From a UPRN, you can start interacting with the API using the following URI template, in which you'll replace {uprn} with the UPRN.

The Spatial Address URI template: https://api.whenfresh.com/world/GB/spatial/addresses/{uprn}

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

Title deeds

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

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

Please contact us for more details.

Integrate with external address pickers

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