> Validate & parse UK postcodes  [](https://codecov.io/gh/ideal-postcodes/postcode) [](https://david-dm.org/ideal-postcodes/postcode) [](https://github.com/ideal-postcodes/postcode/actions) [](https://bundlephobia.com/result?p=postcode) [](https://www.npmjs.com/package/postcode) [](https://npm.runkit.com/postcode) Utility methods for UK Postcodes, including validating the shape of a postcode, extracting postcode elements (like incodes, outcodes, areas and [more](#Definitions)). Tested against ~1.7 million postcodes on ONSPD. ## Features - [Check](#validate) whether a postcode conforms to the [correct format](https://en.wikipedia.org/wiki/Postcodes_in_the_United_Kingdom#Formatting) - [Single purpose static methods](#static-methods) - Tested against a list of ~1.7 million postcodes listed on ONS Postcode Directory - [Extract](#parse) useful elements of a postcode like incode, outcode, sector - Tree-shakeable  ## Links - [GitHub Repository](https://github.com/ideal-postcodes/openapi) - [API Documentation](https://postcodejs.ideal-postcodes.dev) - [Try postcode.js on RunKit](https://npm.runkit.com/postcode) - [Postcode element definitions](#definitions) - [Notes](#notes) - [NPM Package](https://www.npmjs.com/package/postcode) ## Guides - [UK Postcode Format](https://ideal-postcodes.co.uk/guides/uk-postcode-format). An overview of the UK postcode format and its constituent parts - [Postcode Validation](https://ideal-postcodes.co.uk/guides/postcode-validation). An overview of the many approaches to postcode validation and the tradeoffs ## Getting Started ### Installation ```bash npm install postcode ``` ### Validate ```javascript import { isValid } from "postcode"; isValid("AA1 1AB"); // => true ``` ### Parse Pass a string to `parse`. This will return a valid or invalid postcode instance which can be easily destructured. #### Valid Postcode `ValidPostcode` type definition ```javascript import { parse } from "postcode"; const { postcode, // => "SW1A 2AA" outcode, // => "SW1A" incode, // => "2AA" area, // => "SW" district, // => "SW1" unit, // => "AA" sector, // => "SW1A 2" subDistrict, // => "SW1A" valid, // => true } = parse("Sw1A 2aa"); ``` #### Invalid Postcode `InvalidPostcode` type definition ```javascript const { postcode, // => null outcode, // => null incode, // => null area, // => null district, // => null unit, // => null sector, // => null subDistrict, // => null valid, // => false } = parse(" Oh no, ): "); ``` #### Type Guard The TypeScript compiler can infer if you have a valid postcode type from `parse` by checking the `valid` attribute ```javascript import { parse } from "postcode"; const postcode = parse("SW1A 2AA"); if (postcode.valid) { // `postcode` adheres to the `ValidPostcode` interface processString(postcode.outcode.toLowerCase()); // TypeScript compiler knows `outcode` to be a string processString(postcode.subDistrict.toLowerCase()); // And it will throw errors on common gotchas (e.g. subdistrict can be `null` on a valid postcode) } else { // `postcode` adheres to the `InvalidPostcode` interface processInvalidPostcode(postcode); } ``` #### Valid Postcode Object | Postcode | .outcode | .incode | .area | .district | .subDistrict | .sector | .unit | |----------|----------|---------|-------|-----------|--------------|---------|-------| | AA9A 9AA | AA9A | 9AA | AA | AA9 | AA9A | AA9A 9 | AA | | A9A 9AA | A9A | 9AA | A | A9 | A9A | A9A 9 | AA | | A9 9AA | A9 | 9AA | A | A9 | `null` | A9 9 | AA | | A99 9AA | A99 | 9AA | A | A99 | `null` | A99 9 | AA | | AA9 9AA | AA9 | 9AA | AA | AA9 | `null` | AA9 9 | AA | | AA99 9AA | AA99 | 9AA | AA | AA99 | `null` | AA99 9 | AA | ### Exported Methods If you're just after a single value, you can import a single method. #### Validation ```javascript isValid("Sw1A 2aa"); // => true ``` #### Formatting ```javascript import { toNormalised, toOutcode, toIncode, toArea, toDistrict, toSubDistrict, toSector, toUnit, } from "postcode"; toNormalised("Sw1A 2aa"); // => "SW1A 2AA" toOutcode("Sw1A 2aa"); // => "SW1A" toIncode("Sw1A 2aa"); // => "2AA" toArea("Sw1A 2aa"); // => "AA" toDistrict("Sw1A 2aa"); // => "SW1" toSubDistrict("Sw1A 2aa"); // => "SW1A" toSector("Sw1A 2aa"); // => "SW1A 2" toUnit("Sw1A 2aa"); // => "AA" ``` #### Fix `fix` Attempts to correct and clean up a postcode without validating by replacing commonly misplaced characters (e.g. mixing up `0` and `"O"`, `1` and `"I"`). This method will also uppercase and fix spacing. The original input is returned if it cannot be reliably fixed. ```javascript fix("SWIA 2AA") => "SW1A 2AA" // Corrects I to 1 fix("SW1A 21A") => "SW1A 2IA" // Corrects 1 to I fix("SW1A OAA") => "SW1A 0AA" // Corrects O to 0 fix("SW1A 20A") => "SW1A 2OA" // Corrects 0 to O // Other effects fix(" SW1A 2AO") => "SW1A 2AO" // Properly spaces fix("SW1A 2A0") => "SW1A 2AO" // 0 is coerced into "0" ``` Aims to be used in conjunction with parse to make postcode entry more forgiving: ```javascript const { inward } = parse(fix("SW1A 2A0")); // inward = "2AO" ``` If the input is not deemed fixable, the original string will be returned ```javascript fix("12a") => "12a" ``` #### Extract & Replace `match`. Retrieve valid postcodes in a body of text ```javascript const matches = match("The PM and her no.2 live at SW1A2aa and SW1A 2AB"); // => ["SW1A2aa", "SW1A 2AB"] // Perform transformations like normalisation using `.map` and `toNormalised` matches.map(toNormalised); // => ["SW1A 2AA", "SW1A 2AB"] matches.map(toOutcode); // => ["SW1A", "SW1A"] // No matches yields empty array match("Some London outward codes are SW1A, NW1 and E1"); // => [] ``` `replace`. Replace postcodes in a body of text, returning the updated corpus and any matching postcodes ```javascript const { match, result } = replace("The PM and her no.2 live at SW1A2AA and SW1A 2AB"); // => match: ["SW1A2AA", "SW1A 2AB"] // => result: "The PM and her no.2 live at and " // Add custom replacement replace("The PM lives at SW1A 2AA", "Downing Street"); // => { match: ["SW1A 2AA"], result: "The PM lives at Downing Street" }; // No match replace("Some London outward codes are SW1A, NW1 and E1"); // => { match: [], result: "Some London outward codes are SW1A, NW1 and E1" } ``` ## Version 5.0.0 5.0.0 brings changes which allows for better treeshaking and interopability with ES Modules. It also deprecates legacy class based APIs in favour of single purpose methods. ### Breaking Changes - `postcode` no longer exports a class. Legacy `new Postcode()` functionality has been removed. Methods attached to `Postcode` are all available as named exports. - `postcode` no longer uses default exports. All exports are named. E.g. ```javascript // In <= 4.0.0 import Postcode from "postcode"; Postcode.parse("SW1A 2AA"); // In >= 5.0.0 import { parse } from "postcode"; parse("SW1A 2AA"); ``` In many cases, migration can be achieved by changing `import Postcode from "postcode"` to `import * as Postcode from "postcode"`, however this gives up treeshaking advantages. ### New Features - `postcode` now exports a ES Module build - Exports regular expressions - `match` accepts a string and returns all valid postcodes - `replace` accepts a string and replaces valid postcodes with an optional second argument. Default replacement text is empty string `""` ## Definitions [See the postcode format guide](https://ideal-postcodes.co.uk/guides/uk-postcode-format/) for a glossary of postcode component terms. ## Notes Postcodes cannot be validated just with a regular expression (however complex). True postcode validation requires having a full list of postcodes to check against. Relying on a regex will produce false postives/negatives. [See the postcode validation guide](https://ideal-postcodes.co.uk/guides/postcode-validation) for an overview of the approaches and tradeoffs associated with postcode validation. ## Testing ```bash npm test ``` ## License MIT Contains Ordnance Survey Data © Crown Copyright & Database Right