us-address-parser

Parse US address strings into street, city, state, and zip components.

Handles messy real-world formats: apartments, suites, buildings, lots, multi-word city names, partial addresses, mixed case, and more.

Installation

npm install us-address-parser

Usage

CommonJS

const { parseAddress } = require('us-address-parser');

ESM

import { parseAddress } from 'us-address-parser';

TypeScript

import { parseAddress, ParsedAddress } from 'us-address-parser';

Examples

parseAddress('14620 W Encanto Blvd STE 110 Goodyear AZ 85395')
// → { street: '14620 W Encanto Blvd STE 110', city: 'Goodyear', state: 'AZ', zip: '85395' }

parseAddress('1316 W University Dr, Mesa, AZ 85201, USA')
// → { street: '1316 W University Dr', city: 'Mesa', state: 'AZ', zip: '85201' }

parseAddress('14510 W Shumway Dr STE 100 Sun City West AZ 85375')
// → { street: '14510 W Shumway Dr STE 100', city: 'Sun City West', state: 'AZ', zip: '85375' }

parseAddress('1033 N PARKSIDE DR D413 TEMPE, AZ 85288')
// → { street: '1033 N PARKSIDE DR D413', city: 'TEMPE', state: 'AZ', zip: '85288' }

parseAddress('5740 N 59TH AVE APT 1137 BLDG 15 GLENDALE, AZ 85301')
// → { street: '5740 N 59TH AVE APT 1137 BLDG 15', city: 'GLENDALE', state: 'AZ', zip: '85301' }

parseAddress('77 E. Columbus Ave')
// → { street: '77 E. Columbus Ave', city: '', state: '', zip: '' }

parseAddress('Phoenix, AZ 85012')
// → { street: '', city: 'Phoenix', state: 'AZ', zip: '85012' }

What it handles

| Format | Example | |--------|---------| | Standard comma-separated | 123 Main St, Springfield, IL 62701 | | No commas | 123 Main St Springfield IL 62701 | | With USA or United States suffix | 123 Main St, Mesa, AZ 85201, USA | | Apartments / units | 163 E Glenn St APT 1102 Tucson AZ 85705 | | Suites | 926 E McDowell Rd STE 100 Phoenix AZ 85006 | | Buildings | 5740 N 59th Ave BLDG 15 APT 1137 Glendale AZ 85301 | | Lot numbers | 8301 N 103rd Ave LOT 73 Peoria AZ 85345 | | Trailers | 1775 N Broad St Trailer 72 Globe AZ 85501 | | Alphanumeric units | 1033 N Parkside Dr D413 Tempe AZ 85288 | | Multi-word cities | 36453 N Gantzel Rd San Tan Valley AZ 85140 | | Facility names | 14502 W Meeker Blvd Banner Del Webb ER Sun City West AZ 85375 | | Mixed / ALL CAPS | 7012 N 56TH AVE GLENDALE, AZ 85301 | | Street-only (partial) | 77 E. Columbus Ave | | City/state/zip-only (partial) | Phoenix, AZ 85012 |

Return value

{
  street: string;  // Street address + unit info
  city: string;    // City name
  state: string;   // 2-letter state abbreviation
  zip: string;     // 5-digit ZIP code
}

All fields return an empty string "" if not found.

Adding cities

The parser uses a built-in list of common US cities. If you need to support additional or less common cities, you can extend the parser for your use case — the KNOWN_CITIES array in index.js is the place to add them.

License

MIT