Correctly parse and format UK Addresses in Royal Mail's Postcode Address File
Parses Postcode Address File records into correctly formatted address recognised by Royal Mail according to its Clear Addressing Guidelines.
Produces consistent address lines, a post town line and a postcode line.
premise
, number
and unit
attribute, which is a sensible almagamation of building_name
, sub_building_name
and building_number
npm install uk-clear-addressing
Use the Address class to parse a PAF Record
Formatted address lines can be extracted using instance accessors like line_1
, line_2
, line_3
, premise
, number
and unit
const { Address } = require("uk-clear-addressing");
const pafRecord = {
postcode: "WS11 5SB",
post_town: "CANNOCK",
thoroughfare: "Pye Green Road",
building_name: "Flower House 189A",
organisation_name: "S D Alcott Florists",
};
const {
line_1,
line_2,
line_3,
premise,
number,
unit,
post_town,
postcode
} = new Address(pafRecord);
Alternatively extract a formatted address object using .formattedAddress
.
const { Address } = require('uk-clear-addressing');
const address = new Address({
postcode: "WS11 5SB",
post_town: "CANNOCK",
thoroughfare: "Pye Green Road",
building_name: "Flower House 189A",
organisation_name: 'S D Alcott Florists',
});
console.log(address.formattedAddress());
// {
// postcode: "WS11 5SB",
// post_town: "CANNOCK",
// line_1: "S D Alcott Florists",
// line_2: "Flower House",
// line_3: "189a Pye Green Road",
// number: "189a",
// unit: "",
// premise: "Flower House, 189a"
// }
building_number
, building_name
and sub_building_name
represent raw data from Royal Mail's PAF and can be difficult to parse if you are unaware of how the PAF premise fields work together. For this reason, uk-clear-addressing
also provides computed attributes, which attempt to reasonable capture common premise concepts like building number and unit.
Due to years of accumulated complexity, few assumptions should be made of ways UK addresses can be described in terms of number, name and unit. It's recommeded to simply consume the address lines (line_1
, line_2
, line_3
) outlined in Royal Mail's Programmers Guide. Building number, unit and PAF premise attributes should be stored as useful extras.
Some examples of this complexity include:
10A
are not necessarily the building number. In some instances they represent a premise with building number 10
and sub building idenitifer A
building_number
of an address may be split across building_name
, building_number
and sub_building_name
sub_building_name
but no building number or name1 Ashgate Rise, Raw Gap, HG50HZ
, 1 Ashgate Rise
appears in building_name
. The numeric element should not be separated into number
because the property is numbered into the building and not the thoroughfareFurther keep in mind that UK addresses are manually added and updated by thousands of postal workers, thousands of times a day across this UK. Although Royal Mail strives to keep address formatting in accordance with its internal guidance, it is possible for building numbers and units may be incorrectly designated for a time.
premise
attributeThe premise
attribute is designed to capture only the premise specific elements of an address (i.e. no thoroughfare, localities, etc). It attempts to sensibly combine building_number
, building_name
and sub_building_name
.
premise
omits organisation, department and PO boxes.
Examples include:
10B Barry Tower, 13
Flat 1-3, 10
Flat 3, Nelson House, 2
Mansion House
Suite 1-3
number
attributeThe number
attribute attempts to capture the building number element of an address, in other words how a premise is numbered into a thoroughfare. For simple use cases, this attribte may be prefered over Royal Mail's building_number
attribute.
Royal Mail's building_number
field is not suited to this task as the upstream data schema only allows this to be integers. Therefore, mixed numbers (like e.g. 1A
and 1-3
) and ordinal building identifiers (like A
,B
,C
, etc) are not captured in building_number
.
Examples include:
10
A
1-3
10A
unit
attributeThe unit
attribute attempts to capture the "sub building" element of a building with its own number, name or both. For simple use cases, this attribute may be preferred to Royal Mail's sub_building_name
field.
Examples include:
A
Flat 1
Basement Flat
Caretakers Flat
Address.sort
implements a comparison function, which allows you to compare Address
instances. This can readily be passed into Array.prototype.sort
const addresses = await query("SELECT * FROM postcode_address_file LIMIT 10");
addresses
.map(address => new Address(address)) // Instantiate an `Address` instances
.sort(Address.sort) // Now sort
// Print an example to console
.forEach(address => console.log(address.line_1));
// "190 Elm Road"
// "190a Elm Road"
// "191 Elm Road"
// "191a Elm Road"
// "192 Elm Road"
// "193 Elm Road"
// "193a Elm Road"
// "197 Elm Road"
// "197a Elm Road"
// "199 Elm Road"
Many of the regular and edge cases are documented in the test. To run the test suite:
npm test
If you find an edge case, please feel free to make a pull request. However be sure to include a test which documents the specific case being handled.
Below is a list of address fragments. For the address to be properly formatted, you need to pass in all the address fragments available to you.
MIT
Merges premise elements ordered by precedence into a formatted address
Takes an Address
instance and returns a building number, first checking for
name exceptions in building_name and sub_building_name fields
Formats an address element
Test for whether a string begins with a unit prefix
E.g. Back of 10A
=> true
Returns true if string matches rule (iii) of exception rule (above)
Non-desctructively return last elem
Exception Rule indicators: i) First and last characters of the Building Name are numeric (eg ‘1to1’ or ’100:1’) ii) First and penultimate characters are numeric, last character is alphabetic (eg 12A’) iii) Building Name has only one character (eg ‘A’)
PO Box Rule
Returns an array of localities according to precedent recorded in
localityElements
Rule 1 - No building name, number or sub building name No premise elements detected (typically organisation name)
Rule 2 - Building number only
Rule 3 - Building name only
Check format of Building Name (see note (a) above). If the Exception Rule applies, the Building Name should appear at the beginning of the first Thoroughfare line, or the first Locality line if there is no Thoroughfare information.
When a building has a name AND a number range, both must be held in the Building Name field because the Building Number field can only hold numeric characters.
If an address has a building name with text followed by a space and then completed by numerics/numeric ranges with the numeric part an exception (see Note (a) above), the numerics/numeric range are treated as a building number, and the text part is treated as the Building Name and the numerics/numeric range are split off to appear at the beginning of the first Thoroughfare line, or the first Locality line if there is no Thoroughfare.
Rule 4 - Building Name and Number
The Building Name should appear on the line preceding the Thoroughfare and/or Locality information. The Building Number should appear at the beginning of the first Thoroughfare line. If there is no Thoroughfare information then the Building Number should appear at the beginning of the first Locality line.
Rule 5 - Sub Building Name and Building Number
The Sub Building Name should appear on the line preceding the Thoroughfare and Locality information. The Building Number should appear at the beginning of the first Thoroughfare line. If there is no Thoroughfare information then the Building Number should appear at the beginning of the first Locality line.
Rule 6 - Sub building name and building name
Check the format of Sub Building Name (see Note (a) above). If the Exception Rule applies, the Sub Building Name should appear on the same line as, and before, the Building Name.
Otherwise, the Sub Building Name should appear on a line preceding the Building Name, Thoroughfare and Locality information
Check format of Building Name (see note (a) above) If the Exception Rule applies, the Building Name should appear at the beginning of the first Thoroughfare line, or the first Locality line if there is no Thoroughfare information. Otherwise, the Building Name should appear on a line preceding the Thoroughfare and Locality information.
Rule 7 - Sub building name, building name and building number
If the Exception Rule applies, the Sub Building Name should appear on the same line as and before the Building Name.
Undocumented Rule
This rule should not exist as it is not listed in the developer docs. But some records in the wild only have a sub building name
Detects whether a building name contains a range