<commit_before><h1 align="center">
  <img src="https://img.ideal-postcodes.co.uk/UK%20Clear%20Addressing%20Logo@3x.png" alt="UK Clear Addressing">
</h1>

> Correctly parse and format UK Addresses in Royal Mail's Postcode Address File

[![CircleCI](https://circleci.com/gh/ideal-postcodes/uk-clear-addressing.svg?style=svg)](https://circleci.com/gh/ideal-postcodes/uk-clear-addressing)
[![Dependency Status](https://david-dm.org/ideal-postcodes/uk-clear-addressing.png)](https://david-dm.org/ideal-postcodes/uk-clear-addressing)
[![Coverage Status](https://coveralls.io/repos/github/ideal-postcodes/uk-clear-addressing/badge.svg?branch=master)](https://coveralls.io/github/ideal-postcodes/uk-clear-addressing?branch=master)
[![Try uk-clear-addressing on RunKit](https://badge.runkitcdn.com/uk-clear-addressing.svg)](https://npm.runkit.com/uk-clear-addressing)

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.

## Features

![Correct Addressing](https://img.ideal-postcodes.co.uk/correct_address.gif)

- Correctly format UK addresses using Royal Mail's Postcode Address File
- Produces 3 address lines and premise attributes based on `building_name`, `sub_building_name` and `building_number`
- Address sorting function
- Extensive test suite

## Links

- [API Documentation](https://uk-clear-addressing.ideal-postcodes.dev)
- [More information on Postcode Address File data attributes](https://ideal-postcodes.co.uk/documentation/paf-data)
- [PAF Programmer's Guide](https://js.ideal-postcodes.co.uk/guide.pdf)
- [Try uk-clear-addressing on RunKit](https://npm.runkit.com/uk-clear-addressing)

## Getting Started

### Installation

```bash
npm install uk-clear-addressing
```

### Formatting Addresses

#### Extract formatted address lines

```javascript
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,
  post_town,
  postcode
} = new Address(pafRecord);
```

#### Extract a formatted address object

```javascript
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',
//    premise: "Flower House, 189a"
//  }
```

### Sorting Addresses

`Address.sort` implements a comparison function, which allows you to compare `Address` instances. This can readily be passed into `Array.prototype.sort`

```javascript
const addresses = await query("SELECT * FROM postcode_address_file LIMIT 10");

addresses<commit_msg>Add links to docs<commit_after><h1 align="center">
  <img src="https://img.ideal-postcodes.co.uk/UK%20Clear%20Addressing%20Logo@3x.png" alt="UK Clear Addressing">
</h1>

> Correctly parse and format UK Addresses in Royal Mail's Postcode Address File

[![CircleCI](https://circleci.com/gh/ideal-postcodes/uk-clear-addressing.svg?style=svg)](https://circleci.com/gh/ideal-postcodes/uk-clear-addressing)
[![Dependency Status](https://david-dm.org/ideal-postcodes/uk-clear-addressing.png)](https://david-dm.org/ideal-postcodes/uk-clear-addressing)
[![Coverage Status](https://coveralls.io/repos/github/ideal-postcodes/uk-clear-addressing/badge.svg?branch=master)](https://coveralls.io/github/ideal-postcodes/uk-clear-addressing?branch=master)
[![Try uk-clear-addressing on RunKit](https://badge.runkitcdn.com/uk-clear-addressing.svg)](https://npm.runkit.com/uk-clear-addressing)

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.

## Features

![Correct Addressing](https://img.ideal-postcodes.co.uk/correct_address.gif)

- Correctly format UK addresses using Royal Mail's Postcode Address File
- Produces 3 address lines and premise attributes based on `building_name`, `sub_building_name` and `building_number`
- Address sorting function
- Extensive test suite

## Links

- [API Documentation](https://uk-clear-addressing.ideal-postcodes.dev)
- [More information on Postcode Address File data attributes](https://ideal-postcodes.co.uk/documentation/paf-data)
- [PAF Programmer's Guide](https://js.ideal-postcodes.co.uk/guide.pdf)
- [Try uk-clear-addressing on RunKit](https://npm.runkit.com/uk-clear-addressing)

## Getting Started

### Installation

```bash
npm install uk-clear-addressing
```

### Formatting Addresses

#### Extract formatted address lines

Use the [Address](https://uk-clear-addressing.ideal-postcodes.dev/classes/address.html) class to parse a [PAF Record](https://uk-clear-addressing.ideal-postcodes.dev/interfaces/pafrecord.html)

[Formatted address lines](https://uk-clear-addressing.ideal-postcodes.dev/interfaces/formattedaddress.html) can be extracted using instance accessors like `line_1`, `line_2`, `line_3` and `premise`.

```javascript
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,
  post_town,
  postcode
} = new Address(pafRecord);
```

#### Extract a formatted address object

Alternatively extract a [formatted address object](https://uk-clear-addressing.ideal-postcodes.dev/interfaces/formattedaddress.html) using [`.formattedAddress`](https://uk-clear-addressing.ideal-postcodes.dev/classes/address.html#formattedaddress).

```javascript
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 <NAME>ists',
});

console.log(address.formattedAddress());
//  {
//    postcode: 'WS11 5SB',
//    post_town: 'CANNOCK',
//    line_1: '<NAME>',
//    line_2: 'Flower House',
//    line_3: '189a Pye Green Road',
//    premise: "Flower House, 189a"
//  }
```

### Sorting Addresses

[`Address.sort`](https://uk-clear-addressing.ideal-postcodes.dev/classes/address.html#sort) implements a comparison function, which allows you to compare [`Address`](https://uk-clear-addressing.ideal-postcodes.dev/classes/address.html) instances. This can readily be passed into `Array.prototype.sort`

```javascript
const addresses = await query("SELECT * FROM postcode_address_file LIMIT 10");

addresses
{'fraction_non_alphanumeric': 0.14328443241703462, 'fraction_numerical': 0.01153681811707734, 'mean_word_length': 5.0326460481099655, 'pattern_counts': {'":': 0, '<': 11, '<?xml version=': 0, '>': 13, 'https://': 35, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 2, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '152132', 'n_tokens_mistral': 2385, 'n_tokens_neox': 2248, 'n_words': 512}