US Address Normalization

A TypeScript/JavaScript library for normalizing and hashing US addresses.

Purpose

The main purpose of this package is as the first layer of address normalization and standardization. Recommended use is to pre-parse/normalize an address and compare to an existing cache/record set using the hash functions.

Normalize US mailing addresses without the need for an external service.

Limitations

This is a very basic normalizer. It only handles US-based addresses (all 50 states plus US territories), and should not be considered dependable for strict address-to-address comparison. This normalizer does not verify the validity of the address! If you are dependent on accurate addresses, you need to be using some other means (3rd party service, most likely) to verify an address.

Installation

npm install us-address-normalization

Usage

Normalizing

import { Normalizer } from 'us-address-normalization';

const normalizer = new Normalizer();

// This returns an Address object with the parsed components
const address = normalizer.parse('204 southeast Smith Street Harrisburg, or 97446');

address.getAddressComponents();
/* output:
{
  number: '204',
  street: 'Smith',
  street_type: 'St',
  unit: null,
  unit_prefix: null,
  suffix: null,
  prefix: 'SE',
  city: 'Harrisburg',
  state: 'OR',
  postal_code: '97446',
  postal_code_ext: null,
  street_type2: null,
  prefix2: null,
  suffix2: null,
  street2: null,
}
*/

address.toString();
// "204 SE Smith St, Harrisburg, OR 97446"

Convenience Functions

import { parseAddress, parseAddressFromComponents } from 'us-address-normalization';

// Parse from a single string
const address = parseAddress('204 SE Smith St, Harrisburg, OR 97446');

// Parse from components
const address2 = parseAddressFromComponents(
  '204 SE Smith St',
  null, // address line 2
  'Harrisburg',
  'OR',
  '97446'
);

Comparing

import { Normalizer } from 'us-address-normalization';

const normalizer = new Normalizer();

const address1 = normalizer.parse('204 southeast Smith Street Harrisburg, or 97446');
const address2 = normalizer.parse('204 SE Smith St. Harrisburg, Oregon 97446');
// Same street, different number
const address3 = normalizer.parse('207 SE Smith St. Harrisburg, Oregon 97446');

address1.is(address2); // true
address2.is(address3); // false
address1.isSameStreet(address3); // true

// or compare hashes directly
address1.getFullHash() === address2.getFullHash(); // true

Formatting

import { Normalizer } from 'us-address-normalization';

const normalizer = new Normalizer();
const address = normalizer.parse('204 southeast Smith Street Harrisburg, or 97446');

address.toString();
// "204 SE Smith St, Harrisburg, OR 97446"

address.toArray();
// ['204 SE Smith St', 'Harrisburg, OR 97446']

Hashing

If you only need to make use of a consistent way of hashing (e.g. if you're starting with a dependable 5-part address, such as from a 3rd party service), you can build a SimpleAddress.

import { SimpleAddress } from 'us-address-normalization';

const address = new SimpleAddress('1234 Main St NE', null, 'Minneapolis', 'MN', '55401');
address.getHash(); // full hash minus zip
address.getFullHash(); // full hash including zip

// or do it all with the static method:
SimpleAddress.hashFromParts('1234 Main St NE', null, 'Minneapolis', 'MN', '55401');

// CANNOT hash street, since the component parts don't exist
address.getStreetHash(); // throws AddressNotNormalizedError

Hash Types

The library provides three different hash types for different comparison needs:

• getHash() - Hash of all address components MINUS the zip code. Since ~4% of ZIP codes change each month, this is often the better comparison for long-term address matching.
• getFullHash() - Hash of the complete address including zip code. Use for exact matching.
• getStreetHash() - Hash of just the street components (prefix, street name, type, suffix). Useful for finding addresses on the same street regardless of number.

Configuration Options

import { Normalizer } from 'us-address-normalization';

const normalizer = new Normalizer({
  strictMode: false, // When false, returns SimpleAddress on parse failure instead of null
  directionalLookups: { /* custom directional mappings */ },
  stateCodesLookups: { /* custom state code mappings */ },
  streetTypesLookups: { /* custom street type mappings */ },
});

Using with CommonJS

const { Normalizer, parseAddress } = require('us-address-normalization');

const normalizer = new Normalizer();
const address = normalizer.parse('1234 Main St, Minneapolis, MN 55401');
console.log(address.toString());

API Reference

Classes

• Normalizer - Main parser class
• Address - Normalized address with components and hashing
• SimpleAddress - Non-normalized address for hashing only
• AddressNotNormalizedError - Error thrown when street hash is requested from SimpleAddress

Functions

• parseAddress(address: string, options?) - Convenience function to parse an address string
• parseAddressFromComponents(addr1, addr2, city, state, zip, options?) - Convenience function to parse from components

Types

• NormalizerOptions - Configuration options for Normalizer
• ParsedAddress - Interface for parsed address components
• AddressComponents - Interface for address component getters

Lookup Tables

The library exports the default lookup tables which can be customized:

• directional - Directional abbreviations (N, S, E, W, NE, etc.)
• stateCodes - US state and territory codes
• streetTypes - Street type abbreviations (St, Ave, Blvd, etc.)

Credits

This is a TypeScript port of the PHP library zerodahero/address-normalization, which itself is based on the Perl module Geo::StreetAddress::US originally written by Schuyler D. Erle.

License

MIT