WhenFresh Address Matching

For scenarios where you don't already have an identifier (e.g. Royal Mail PAF UDPRN) for your addresses, we offer an address matching service that will exactly match a an address string to Royal Mail PAF and return the appropriate WhenFresh Property Address Key for the address.

Matching an address

A combination of both a Postcode and an address string is required to use this function, as it is available on the UK postcode resource catalog.

https://api.whenfresh.com/world/GB/postcodes/{postcode}/catalog

The postcode resource catalog template follows the URI template specification.

For example, the postcode PE1 1PX would result in a postcode resource catalog URI of https://api.whenfresh.com/world/GB/postcodes/PE1%201PX/catalog (note spaces have been converted to their percent-encoded values). This is the URI you will send your address match request to.

Formatting the address string

The next step is to prepare the various elements of an address you are trying to resolve, by concatenating them with ,.

For example, given a stored address:

Flat 4, De Vecti House
Westgate
Peterborough

The address query would be concatenated as:

Flat 4, De Vecti House, Westgate, Peterborough

Our Address Matching function can be invoked by passing the address query as follows:

POST https://api.whenfresh.com/world/GB/postcodes/PE1%201PX/catalog
Content-Type: application/ld+json
Accept: application/ld+json
Authorization: Bearer ...

{
    "@context": "http://api.whenfresh.com/.hydra/context.jsonld",
    "variables": [
        {
            "@id": "https://api.whenfresh.com/vars/WhenFresh/Postal Address#Royal Mail/Postal Address File/Postal Address/Property Address Key",
            "address": "flat 4, de vecti house, Westgate, Peterborough"
        }
    ]       
}

The datum returned by the api contains the following fields of interest:

value: the WhenFresh Property Address Key matched to the provided address
confidence: The confidence score for the match. As this specific function is exact matching only, this will always be 100.
valueReference: Additional datums of interest, including the catalog URI you can use to purchase additional data about a property.

{
   "@context": "https://api.whenfresh.com/.hydra/context.jsonld",
   "@type": "ResourceCatalogPurchase",
   "manages": {
      "property": "rdf:type",
      "object": "Datum"
   },
   "member": [
      {
         "@type": "https://api.whenfresh.com/ontologies/Royal Mail/Postal Address File#Postal Address/Property Address Key",
         "confidence": 100,
         "price": {
            "@type": "MonetaryAmount",
            "currency": "GBP",
            "value": 0.01
         },
         "value": "ulc7a·0",
         "valueReference": [
            {
               "@type": "https://api.whenfresh.com/ontologies/WhenFresh/Core#Catalog/ResourceCatalogOfPostalAddress",
               "value": "https://api.whenfresh.com/world/GB/addresses/ulc7a·0/catalog",
               "variable": {
                  "@id": "https://api.whenfresh.com/vars/WhenFresh/Postal Address#WhenFresh/Core/Catalog/ResourceCatalogOfPostalAddress",
                  "@type": "Variable"
               }
            }
         ],
         "variable": {
            "@id": "https://api.whenfresh.com/vars/WhenFresh/Postal Address#Royal Mail/Postal Address File/Postal Address/Property Address Key",
            "@type": "Variable"
         }
      }
   ]
}

This function is exact matching only. As such you will only ever get either a single datum returned (when a match is made), or no datum (when an exact match has not been possible).

In the case when no match is found, or more generally if your use case is interactive in nature, we also have an Ordnance Survey Address Matching function that will return multiple possible matches with varying confidence scores.