addresser

1.1.20 verified Fri May 01 auth: no javascript

Street address parser for Node.js with normalization and secondary unit detection. Current stable version 1.1.20 (last released 2023). Parses US addresses into components (street number, name, suffix, direction, city, state, zip+4). Handles extra whitespace, trailing directionals, PO boxes, and secondary units without delimiters. Normalizes to Title Case and standardizes street suffixes. Includes utility functions for random city generation and city lookup. Ships TypeScript types. Limited to US addresses; no geocoding or validation against real addresses.

Common errors

error Cannot find module 'addresser' ↓

cause Package not installed or is installed in a different location.

fix

Run 'npm install addresser' in your project root, or ensure it is listed in package.json dependencies.

error addresser.parseAddress is not a function ↓

cause Importing incorrectly: using named import instead of default import.

fix

Use 'import addresser from 'addresser'' or 'const addresser = require('addresser')' in CommonJS.

error TypeError: addresser.randomCity is not a function ↓

cause Destructuring randomCity from the module incorrectly (e.g., const { randomCity } = require('addresser')).

fix

Import the whole module and call addresser.randomCity(): 'const addresser = require('addresser'); addresser.randomCity()'.

Warnings

gotcha Package only supports US addresses. Non-US addresses will produce undefined or incorrect fields. ↓

fix Ensure input addresses are US-based, or use a library like node-postal for international support.

gotcha parseAddress does not validate whether the address actually exists; it only parses the string into components. ↓

fix Use a geocoding service (e.g., Google Maps API) to verify address existence if needed.

gotcha Output formatting (Title Case, standardized suffixes) is hardcoded; no options to preserve original casing or abbreviations. ↓

fix Accept normalized output as-is; there is no configuration to modify this behavior.

gotcha Zip+4 handling: zipCodePlusFour field appears only when the input includes a +4 extension (e.g., '29526-1234'). It is not always present. ↓

fix Check for zipCodePlusFour property existence before using it; do not assume it is always present.

Install

npm install addresser

yarn add addresser

pnpm add addresser

Imports

addresser
wrong
```
const addresser = require('addresser')
```
correct
```
import addresser from 'addresser'
```
Package exports a default object with methods: parseAddress, randomCity, cities. TypeScript types are included; use default import.

parseAddress

wrong

import { parseAddress } from 'addresser'

correct

import addresser from 'addresser'; addresser.parseAddress(...)

parseAddress is a method on the default export, not a named export.

randomCity
wrong
```
const { randomCity } = require('addresser')
```
correct
```
import addresser from 'addresser'; addresser.randomCity()
```
randomCity is a method on the default export. CommonJS destructuring won't work because the library uses module.exports = {...}.

Quickstart

Parses a US address into components, demonstrates secondary unit handling, and shows random city generation.

import addresser from 'addresser';

// Parse a full US address
const result = addresser.parseAddress('400 South Orange Ave, South Orange, NJ 07079');
console.log(result.formattedAddress); // '400 South Orange Ave, South Orange, NJ 07079'
console.log(result.streetNumber);     // '400'
console.log(result.streetName);       // 'South Orange'
console.log(result.streetSuffix);     // 'Ave'
console.log(result.placeName);        // 'South Orange'
console.log(result.stateAbbreviation);// 'NJ'
console.log(result.zipCode);          // '07079'

// Handle secondary units
const unitResult = addresser.parseAddress('1301 Columbia College Drive Unit 101 Columbia, SC 29203');
console.log(unitResult.addressLine2); // 'Unit 101'

// Get a random city
const city = addresser.randomCity();
console.log(city.city); // e.g., 'Irwin'
console.log(city.state); // e.g., 'ID'