Addressit Freeform Street Address Parser

1.8.2 · active · verified Tue Apr 21

addressit is a JavaScript library designed to parse freeform street address text into a structured object. The current stable version is 1.8.2. Recent releases have primarily focused on maintenance and minor feature additions, indicating an irregular but active release cadence. Its primary differentiator is its specialized focus on extracting the street parsing components (unit, building number, street name, and street type). Broader geographical details like city, state, or country are collected into a generic `regions` array, requiring further application-specific processing. This design choice acknowledges the vast variability of global address formats and avoids attempting a universal, country-specific identification within the core library. It is best suited for applications where extracting the fundamental street information from unstructured text is paramount, rather than providing comprehensive geopolitical address validation.

Common errors

```
Error: Cannot find module 'addressit'
```
cause The `addressit` package has not been installed or is not accessible in the current project's `node_modules`.

fix Run `npm install addressit` or `yarn add addressit` in your project directory to install the dependency.
```
TypeError: addressit is not a function
```
cause This error typically occurs if the module is imported incorrectly (e.g., `require('addressit').addressit`) when the module itself exports the function directly as its default.

fix Ensure you are using `const addressit = require('addressit');` for CommonJS or `import addressit from 'addressit';` for ESM setups.
```
TypeError: Cannot read properties of undefined (reading 'split')
```
cause This error occurs if the `addressit()` function is called without a string input, or with a `null` or `undefined` value, leading to attempts to call string methods on a non-string.

fix Always pass a valid string as the first argument to the `addressit()` function, ensuring it's not null or undefined.

Warnings

gotcha Running `addressit` versions 1.8.1 and later on Node.js environments older than v16 may encounter issues due to the updated `package-lock.json` format introduced in these versions.
Fix: Ensure that Node.js v16 or a newer version is used for both development and production environments when working with `addressit` v1.8.1 or later.
gotcha The library's core functionality is focused on parsing street names, numbers, and unit information. Broader geographical components (such as city, state, or country) are not individually identified but are instead aggregated into a generic `regions` array, which requires additional application-specific parsing.
Fix: Implement custom logic or integrate with external geographical data services to further process the `regions` array if detailed city, state, or country identification is required.

Install

npm install addressit npm
yarn add addressit yarn
pnpm add addressit pnpm

Imports

addressit
wrong:
```
import { addressit } from 'addressit';
```
correct:
```
const addressit = require('addressit');
```
The library primarily uses CommonJS `require()`. For ESM environments, `import addressit from 'addressit'` might work with bundlers or specific Node.js configurations, but it is not officially demonstrated.

Quickstart

Demonstrates parsing a street address string and logging the structured output.

const addressit = require('addressit');

// Parse a made-up address string
const address = addressit('Shop 8, 431 St Kilda Rd Melbourne');

// Log the parsed address object
console.log(address);

/* Expected output:
{
  text: '8/431 ST KILDA RD MELBOURNE',
  parts: [],
  unit: 8,
  country: undefined,
  number: 431,
  street: 'ST KILDA RD',
  regions: [ 'MELBOURNE' ]
}
*/

view raw JSON →