WhenFresh Address Matching

For scenarios where you don't already have a UPRN for your addresses, we offer an address matching service that will exactly match an address string to Royal Mail PAF and return the corresponding UPRN and SpatialAddress Resource Catalog URI 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/Address Matching#Ordnance Survey/Spatial/Address/Unique Property Reference Number",
            "address": "flat 4, de vecti house, Westgate, Peterborough"
        }
    ]       
}

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

• value: the UPRN 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 SpatialAddress catalog URI you can use to purchase 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/Ordnance Survey/Spatial#Address/Unique Property Reference Number",
         "confidence": 100,
         "price": {
            "@type": "MonetaryAmount",
            "currency": "GBP",
            "value": 0.01
         },
         "value": "10008069962",
         "valueReference": [
            {
               "@type": "https://api.whenfresh.com/ontologies/WhenFresh/Core#Catalog/ResourceCatalogOfSpatialAddress",
               "value": "https://api.whenfresh.com/world/GB/uprns/10008069962/catalog",
               "variable": {
                  "@id": "https://api.whenfresh.com/vars/WhenFresh/Spatial Address#WhenFresh/Core/Catalog/ResourceCatalogOfSpatialAddress",
                  "@type": "Variable"
               }
            }
         ],
         "variable": {
            "@id": "https://api.whenfresh.com/vars/WhenFresh/Address Matching#Ordnance Survey/Spatial/Address/Unique Property Reference Number",
            "@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.