Share your code. npm Orgs help your team discover, share, and reuse code. Create a free org »


    Build Status Dependency Status

    UK Clear Addressing

    This module converts UK address fragments into a properly formatted address recognised by Royal Mail according to its Clear Addressing Guidelines. This consists of 1-3 address lines, a post town line and a postcode line.

    Correct Addressing

    Originally created in conjunction with Royal Mail Postcode Address File, it maps field name for field name if you were to pull the address straight from this database. If you don't have access to PAF, it can still be used as long as you know which parameters correspond to what data you have available. Parameters listed below

    For anyone who has tried this, properly formatting addresses to Royal Mail's standard is a bit of a nightmare because of all the edge cases. I've covered as many of them as I could find, these are documented in the test suite.

    Getting Started

    npm install uk-clear-addressing

    Try it

    var Address = require('uk-clear-addressing');
    // Pass in your address fragments 
    var address = new Address({
        postcode: "WS11 5SB",
        post_town: "CANNOCK",
        dependant_locality: "",
        double_dependant_locality: "",
        thoroughfare: "PYE GREEN ROAD",
        building_number: "",
        building_name: "FLOWER HOUSE 189A",
        sub_building_name: "",
        dependant_thoroughfare: "",
        organisation_name: "S D ALCOTT FLORISTS",
    //  {  
    // postcode: 'WS11 5SB', 
    //   post_town: 'CANNOCK', 
    //   line_1: 'S D Alcott Florists', 
    // line_2: 'Flower House', 
    //   line_3: '189a Pye Green Road', 
    // premise: "Flower House, 189a" 
    // } 


    As mentioned, 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.

    Premises Elements

    • Sub Building Name (e.g. ‘Flat 1’)
    • Building Name (e.g. ‘Rose Cottage’)
    • Building Number (e.g. ‘22’)
    • Organisation Name (e.g. ‘Cath’s Cakes’)
    • PO Box number

    Thoroughfare elements

    • Dependent Thoroughfare Name (e.g. ‘Cheshunt’)
    • Dependent Thoroughfare Descriptor (e.g. ‘Mews’ or ‘Court’)
    • Thoroughfare Name (e.g. ‘Cypress’)
    • Thoroughfare Descriptor (e.g. ‘Road’ or ‘Street’)

    Locality elements

    • Double Dependent Locality (e.g. ‘Tyre Industrial Estate’)
    • Dependent Locality (e.g. ‘Blantyre’)
    • Post Town (e.g. ‘GLASGOW’)



    • formattedAddress() now returns a premise attribute. This is a computed attribute to isolate the premise name taking into account all available information.


    • Added fallback for 4 line addresses (very rare edge case): When an address spills over 3 lines, the remaining lines (lines 4 or more) are appended to line 3 and separated by commas
    • Added fallback for address with only a sub_building_name (very rare edge case): See weirdRule in index.js
    • Performance Improvement: Result of formattedAddress is cached
    • Performance Improvement: Removal of string dependency


    npm i uk-clear-addressing

    Downloadslast 7 days







    last publish


    • avatar