Sign Up for Free

RunKit +

Try any Node.js package right in your browser

This is a playground to test code. It runs a full Node.js environment and already has all of npm’s 1,000,000+ packages pre-installed, including paf-api with all npm packages installed. Try it out:

var pafApi = require("paf-api")

This service is provided by RunKit and is not affiliated with npm, Inc or the package authors.

paf-api v2.0.0

HTTP service that parses Postcode Address File records into a correctly formatted address


HTTP API that parses Postcode Address File records into correctly formatted address lines

CI Release Dependency Status Coverage Status npm version install size

Deploy to Netlify

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 via HTTP


  • Exposes UK Clear Addressing as a HTTP service
  • Deployable as a docker container or node.js application

Correct Addressing


Getting Started

Try on

curl -X POST \ \
  -H 'Content-Type: application/json' \
  -d '{ "sub_building_name": "Flat 8", "building_name": "Oxford House 110-114", "thoroughfare": "High Street" }'


This API responds to POST requests to /parse with a JSON payload representing a PAF Record

POST /parse

POST /parse

  "postcode": "WS11 5SB",
  "post_town": "CANNOCK",
  "thoroughfare": "Pye Green Road",
  "building_name": "Flower House 189A",
  "organisation_name": "S D Alcott Florists",
  "query": {
    "postcode": "WS11 5SB",
    "post_town": "CANNOCK",
    "thoroughfare": "Pye Green Road",
    "building_name": "Flower House 189A",
    "organisation_name": "S D Alcott Florists",
    "building_number": "",
    "sub_building_name": "",
    "dependant_locality": "",
    "double_dependant_locality": "",
    "dependant_thoroughfare": "",
    "po_box": "",
    "department_name": "",
  "formatted": {
    "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"

Available Payload Attributes

  building_number: string | number;
  building_name: string;
  sub_building_name: string;
  dependant_locality: string;
  double_dependant_locality: string;
  thoroughfare: string;
  dependant_thoroughfare: string;
  po_box: string;
  post_town: string;
  postcode: string;
  department_name: string;
  organisation_name: string;


Deploy as a docker container

Using the docker CLI

docker pull idealpostcodes/paf-api:latest

docker run -p 8080:8080 idealpostcodes/paf-api

Alternatively with docker-compose

git clone && cd paf-api

docker-compose up -d

Deploy as a node.js process

Requires node.js 8 or above

git clone && cd paf-api && npm install

npm start # Traffic served on 8080

NPM Module

The npm module exports an express app factory which takes a pino logger

const { App } = require("paf-api");

const app = App({ logger: pino() });



The following environment variables can be passed to the application.

PORT=8080 # Sets the port to listen on



RunKit is a free, in-browser JavaScript dev environment for prototyping Node.js code, with every npm package installed. Sign up to share your code.
Sign Up for Free