Ordnance Survey Address Matching

All datasets available on the WhenFresh API are keyed against unique identifiers for a resource. In the UK, this usually means a Royal Mail PAF Unique Delivery Point Number, or UDPRN.

Sometimes, address lookup services don't provide UDPRNs, and sometimes existing books have only collected textual information about an address.

With Address Matching, you can process textual information about an address and get back reusable unique identifiers, and start accessing the billions of datapoints available today on the WhenFresh API.

Ordnance Survey's AddressBase Premium

AddressBase Premium is a dataset provided by Ordnance Survey, containing over 40 million addresses, as well as providing all the information relating to an address from creation to retirement. It includes data from Local Authority, Ordnance Survey and Royal Mail, and is integrated in the WhenFresh API so you can go from text to buying data in an instant.

Matching an address with a postcode

Ordnance Survey's address matching function 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

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

Ordnance Survey's Address Matchhing 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/Ordnance Survey/AddressBase#Royal Mail/Postal Address File/Postal Address/Property Address Key",
            "address": "flat 4, de vecti house, Westgate, Peterborough"
        }
    ]       
}

Ordnance Survey returns up to 100 postal addresses for the search string.

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

value: the WhenFresh property address key matched to the provided address
day: the last modified date of the address base record
modified: the time at which we processed the address match request
description: A one-line address description
confidence: The confidence score for the match
valueReference: Additional datums of interest, including Royal Mail PAF's UDPRN, Ordnance Surveys UPRN and the catalog URI you can use to purchase additional data about a property.

{
  "@context": "https://api.whenfresh.com/.hydra/context.jsonld",
  "@id": "https://api.whenfresh.com/world/GB/postcodes/PE1 1PX/catalog",
  "@type": "ResourceCatalogOfPostcode",
  "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,
      "day": "2023-06-23",
      "description": "FLAT 4, DE VECTI HOUSE, WESTGATE, PETERBOROUGH, PE1 1PX",
      "modified": "2023-06-26T09:59:21.2065380+00:00",
      "price": {
        "@type": "MonetaryAmount",
        "currency": "GBP",
        "value": 0.05
      },
      "value": "ulc7a·0",
      "valueReference": [
        {
          "@type": "https://api.whenfresh.com/ontologies/Ordnance Survey/Spatial#Address/Unique Property Reference Number",    
          "value": "10008069962",
          "variable": {
            "@id": "https://api.whenfresh.com/vars/Ordnance Survey/AddressBase#Ordnance Survey/Spatial/Address/Unique Property Reference Number",
            "@type": "Variable"
          }
        },
        {
          "@type": "https://api.whenfresh.com/ontologies/Royal Mail/Postal Address File#Postal Address/Unique Delivery Point Reference Number",
          "value": "51384070",
          "variable": {
            "@id": "https://api.whenfresh.com/vars/Ordnance Survey/AddressBase#Royal Mail/Postal Address File/Postal Address/Unique Delivery Point Reference Number",
            "@type": "Variable"
          }
        },
        {
          "@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/Ordnance Survey/AddressBase#WhenFresh/Core/Catalog/ResourceCatalogOfPostalAddress",
            "@type": "Variable"
          }
        }
      ],
      "variable": {
        "@id": "https://api.whenfresh.com/vars/Ordnance Survey/AddressBase#Royal Mail/Postal Address File/Postal Address/Property Address Key",
        "@type": "Variable",
        "offered": "Available",
        "yield": {
          "@type": "QuantitativeValue",
          "value": 1
        }
      }
    }
}

The confidence level for a match is defined by Ordnance Survey as follows:

100: Exact

note: extra information in the input address that doesn't match the ABPREM version is ignored
80 – 90: Good

most of the address matches, but a part of it may be different, such as a different postcode
70: Partial

address could represent the same address but has some significant differences
< 70 No Match