Skip to content

Commit caab3fb

Browse files
FuzzyStringFuzzyString
authored
Merge pull request #33 from dvla/feature/postman-paf-js
Feature/postman paf js
2 parents b9aa68d + 83b1eb8 commit caab3fb

2 files changed

Lines changed: 155 additions & 0 deletions

File tree

‎content/open-source/index.md‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -46,8 +46,18 @@ This gem provides a lightweight logger that adds functionality to the built in o
4646

4747
This gem encapsulates a way of having a predefined set of properties within a test pack, built to work in tandem with the World functionality in Cucumber
4848

49+
### [postman-paf](https://github.com/dvla/postman-paf)
50+
51+
Open Source library to apply Royal Mail Rules & Exceptions to PAF (Postcode Address File) addresses when converting to a printable format.
52+
4953
# Dynamics 365
5054

5155
### [dataverse-helper](https://github.com/dvla/dataverse-helper)
5256

5357
This gem helps you integrate with Microsoft Dynamics using Microsoft Dataverse Web API. You can create, retrieve, delete or update a record without worrying about authentications as it's automatically managed behind the scenes.
58+
59+
# JavaScript
60+
61+
### [postman-paf-js](https://github.com/dvla/postman-paf-js)
62+
63+
Open Source library to apply Royal Mail Rules & Exceptions to PAF (Postcode Address File) addresses when converting to a printable format.

‎content/posts/2025-02-postman-paf/index.md‎

Lines changed: 145 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,145 @@
1+
---
2+
author: "Nathan Morris"
3+
title: "Postman-Paf-js"
4+
description: "Open Source library to apply Royal Mail Rules & Exceptions to PAF (Postcode Address File) addresses when converting to a printable format."
5+
draft: false
6+
date: 2025-02-06
7+
tags: ["JavaScript"]
8+
categories: ["JavaScript"]
9+
ShowToc: true
10+
TocOpen: true
11+
---
12+
13+
## Postman-Paf-js
14+
15+
We've recently released a library called [postman-paf-js](https://github.com/dvla/postman-paf-js) that we use to apply Royal Mail rules & exceptions to PAF (Postcode Address File) addresses when converting to a printable format. We also have a [ruby implementation](https://github.com/dvla/postman-paf).
16+
17+
## Why is Postman Paf required?
18+
19+
To put it simply, UK addresses are more complicated than they might seem. But aren't addresses just a few set lines that appear on your letters? Unfortunately, it's not that simple! Most addresses in the UK are stored in a database called the Postal Address File (PAF), which is owned and managed by the
20+
Royal Mail. This database includes over 30 million UK postal delivery addresses and 1.8 million postcodes. However, these addresses are not stored in the familiar format you
21+
see on your envelope. Instead, they are stored in a specific data structure, as shown
22+
[here](https://www.poweredbypaf.com/wp-content/uploads/2017/07/Latest-Programmers_guide_Edition-7-Version-6-1.pdf#page=12)
23+
24+
25+
Example of a PAF address
26+
```JSON
27+
{
28+
"thoroughfareName": "NORTH EAST SECTOR",
29+
"doubleDependentLocality": "BOURNEMOUTH INTERNATIONAL AIRPORT",
30+
"postcode": "BH23 6NE",
31+
"dependentLocality": "HURN",
32+
"postTown": "CHRISTCHURCH",
33+
"buildingName": "A B P 21",
34+
"organisationName": "BREATHE SAFETY LTD"
35+
}
36+
```
37+
38+
This data is structured very differently from the address format that appears on your envelope. Before these PAF addresses (which we at the DVLA call "Structured Addresses")
39+
can be used for postal mail, they must be converted into a format recognized by the Royal Mail. We refer to addresses in this format as "Unstructured Addresses."
40+
41+
42+
## Rules are rules
43+
44+
To convert addresses from a Structured format to an Unstructured format, certain rules must be applied to each element of the address to ensure it is ordered correctly.
45+
The Royal Mail has provided a developer guide detailing how to correctly perform this conversion, which includes several rules and exceptions that need to be followed
46+
in the correct order.
47+
48+
There are 4 ordering notes, 7 rules, and 4 exceptions that must be applied to a PAF address, all in the correct order, to ensure it is converted according to the Royal
49+
Mail's guidelines.
50+
51+
## Conversion example step by step
52+
53+
An example of the process followed on converting a Structured address to an unstructured address can be found below:
54+
```JSON
55+
{
56+
"structuredAddress": {
57+
"buildingName": "ENDEAVOUR QUAY",
58+
"subBuildingName": "THE DESIGN OFFICE",
59+
"thoroughfareName": "MUMBY ROAD",
60+
"postcode": "PO12 1AH",
61+
"postTown": "GOSPORT"
62+
}
63+
}
64+
```
65+
66+
### Step 1 - Order premises elements
67+
68+
Rule 6 applies Address has a sub building name and building name.
69+
70+
Check the format of Sub Building Name. If an Exception Rule applies, the Sub Building Name should appear on the same line as, and before, the Building Name
71+
Check format of Building Name, If an Exception Rule applies, the Building Name should appear at the beginning of the first Thoroughfare line, or the first Locality
72+
line if there is no Thoroughfare information.
73+
74+
In this case none of these exceptions apply.
75+
76+
Otherwise, the Sub Building Name should appear on a line preceding the Building Name, Thoroughfare and Locality information.
77+
78+
```JSON
79+
{
80+
"line1": "THE DESIGN OFFICE",
81+
"line2": "ENDEAVOUR QUAY"
82+
}
83+
```
84+
85+
### Step 2 - Order Thoroughfare/locality
86+
87+
```JSON
88+
{
89+
"line1": "THE DESIGN OFFICE",
90+
"line2": "ENDEAVOUR QUAY",
91+
"line3": "MUMBY ROAD"
92+
}
93+
```
94+
95+
### Step 3 - Add in post town and postcode
96+
97+
```JSON
98+
{
99+
"line1": "THE DESIGN OFFICE",
100+
"line2": "ENDEAVOUR QUAY",
101+
"line3": "MUMBY ROAD",
102+
"line5": "GOSPORT",
103+
"postcode": "PO12 1AH"
104+
}
105+
```
106+
107+
108+
## How we did it
109+
110+
Originally, the address converter library was written in Java and forked from an existing library: [paf-address-format](https://github.com/steinfletcher/paf-address-format). However, this library was relatively old (last updated 5 years ago) and did not conform to all the up-to-date rules and exceptions outlined in the latest Royal Mail Developers Guide.
111+
112+
To ensure the library could correctly handle every rule and exception, the DVLA team painstakingly tested each rule and exception individually. This process involved using the notes and examples from the Royal Mail Developer's Guide, testing sets of PAF addresses from a PAF dataset, and comparing results against the Royal Mail Postcode Finder. After the conversion library was manually tested, a comprehensive test pack was created consisting of 92 tests and 1,380 assertions to thoroughly verify each rule and exception.
113+
114+
Since JavaScript is widely used across the DVLA in applications requiring structured addresses to be converted, the team decided to undertake the task of creating a JavaScript version of the original Java library. The code was ported from Java to JavaScript and then thoroughly tested again using the same tests and tools developed during the improvements made to the Java library. The JavaScript library has since been posted publicly on GitHub to provide access to the developer community.
115+
116+
We currently use the library within our internal Addressing services where it is helping us handle millions of addresses per year UK driver and vehicle transactions.
117+
118+
## How to use the library
119+
120+
The library is simple to use, the convertStructuredToUnstructured function needs to be imported from the library then simply pass in a structured address.
121+
122+
```javascript
123+
const { convertStructuredToUnstructured } = require('postman-paf-js');
124+
125+
const structuredAddressToConvert = {
126+
buildingNumber: '1',
127+
thoroughfareName: 'Example Street',
128+
postTown: 'City',
129+
postcode: 'AA1 1AA',
130+
};
131+
132+
const convertedUnstructuredAddress = convertStructuredToUnstructured(structuredAddressToConvert);
133+
134+
```
135+
136+
The function will then return an unstructured (Address with up to 5 lines and a postcode ) in the royal mail format
137+
138+
```javascript
139+
convertedUnstructuredAddress = {
140+
line1: '1 Example Street',
141+
line5: 'City',
142+
postcode: 'AA1 1AA',
143+
};
144+
```
145+

0 commit comments

Comments
 (0)