{"_id":"us-address-normalization","_rev":"2-5c4238ca61c6f3469c5a91d467fcf761","name":"us-address-normalization","dist-tags":{"latest":"1.0.1"},"versions":{"1.0.0":{"name":"us-address-normalization","version":"1.0.0","keywords":["address","normalization","parser","usps","postal","us-address","united-states","street-address"],"author":"","license":"MIT","_id":"us-address-normalization@1.0.0","maintainers":[{"name":"gmaniac","email":"grraymond101@gmail.com"}],"dist":{"shasum":"ff092b631bc97533948252476cc1a23c69cbbcb3","tarball":"https://registry.npmjs.org/us-address-normalization/-/us-address-normalization-1.0.0.tgz","fileCount":8,"integrity":"sha512-rgC6RV1r/U2fM90PocuZw3/P/8JnugIBjBXxbdbCqsicbxSN1OSNdHneKB8N3hgt9htfu4oRoYAjGnc4XbuEXg==","signatures":[{"sig":"MEYCIQC5VBba/cyG0nJu1iBqiPOsW3FlKCg+e12SEcEy2QkMMwIhANTtHd5+PUSR8NBUS8kq7hB99e3UdMy8MGXTExIcIxi8","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":195026},"main":"./dist/index.cjs","type":"module","types":"./dist/index.d.ts","module":"./dist/index.js","engines":{"node":">=18.0.0"},"exports":{".":{"import":{"types":"./dist/index.d.ts","default":"./dist/index.js"},"require":{"types":"./dist/index.d.cts","default":"./dist/index.cjs"}}},"gitHead":"967d93aeeecc74a34c9602893711bc79abecea80","scripts":{"dev":"tsup --watch","lint":"eslint src tests","test":"vitest run","build":"tsup","typecheck":"tsc --noEmit","test:watch":"vitest","prepublishOnly":"npm run build"},"_npmUser":{"name":"gmaniac","email":"grraymond101@gmail.com"},"_npmVersion":"11.6.2","description":"US address normalization and hashing library","directories":{},"_nodeVersion":"24.11.1","_hasShrinkwrap":false,"devDependencies":{"tsup":"^8.0.1","vitest":"^1.2.0","typescript":"^5.3.3","@types/node":"^20.11.0","@vitest/coverage-v8":"^1.6.1"},"_npmOperationalInternal":{"tmp":"tmp/us-address-normalization_1.0.0_1770774880063_0.941906783035201","host":"s3://npm-registry-packages-npm-production"}},"1.0.1":{"name":"us-address-normalization","version":"1.0.1","description":"US address normalization and hashing library","type":"module","main":"./dist/index.cjs","module":"./dist/index.js","types":"./dist/index.d.ts","exports":{".":{"import":{"types":"./dist/index.d.ts","default":"./dist/index.js"},"require":{"types":"./dist/index.d.cts","default":"./dist/index.cjs"}}},"scripts":{"build":"tsup","dev":"tsup --watch","test":"vitest run","test:watch":"vitest","typecheck":"tsc --noEmit","lint":"eslint src tests","prepublishOnly":"npm run build"},"keywords":["address","normalization","parser","usps","postal","us-address","united-states","street-address"],"author":"","license":"MIT","devDependencies":{"@types/node":"^20.11.0","@vitest/coverage-v8":"^1.6.1","tsup":"^8.0.1","typescript":"^5.3.3","vitest":"^1.2.0"},"engines":{"node":">=18.0.0"},"gitHead":"0ac56708853e2016d0b4c79dd3c3d88f01572fd3","_id":"us-address-normalization@1.0.1","_nodeVersion":"24.11.1","_npmVersion":"11.6.2","dist":{"integrity":"sha512-7hZlHhoEzCaZWeJEIBg6AIli79uQuhgFQBLx4zHQzBpPBo1dsfkPePpYOSzJD2Fr3qjS6y7L26dWe9biSJsotw==","shasum":"2593887e3d165a7b99363a7b6a477de6487229bb","tarball":"https://registry.npmjs.org/us-address-normalization/-/us-address-normalization-1.0.1.tgz","fileCount":8,"unpackedSize":208712,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCIEr83O73l+uXCvzztzMJfTZxjLJTdbprimfPmUkjX7TdAiBf5NSHhjZ4jqu2SRZ1pEmSeh0kfcVw5YZvnV0GXGyJ1w=="}]},"_npmUser":{"name":"gmaniac","email":"grraymond101@gmail.com"},"directories":{},"maintainers":[{"name":"gmaniac","email":"grraymond101@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/us-address-normalization_1.0.1_1770821803094_0.32784050261465314"},"_hasShrinkwrap":false}},"time":{"created":"2026-02-11T01:54:40.062Z","modified":"2026-02-11T14:56:43.370Z","1.0.0":"2026-02-11T01:54:40.201Z","1.0.1":"2026-02-11T14:56:43.249Z"},"license":"MIT","keywords":["address","normalization","parser","usps","postal","us-address","united-states","street-address"],"description":"US address normalization and hashing library","maintainers":[{"name":"gmaniac","email":"grraymond101@gmail.com"}],"readme":"# US Address Normalization\n\nA TypeScript/JavaScript library for normalizing and hashing US addresses.\n\n[![CI](https://github.com/gmaniac/us-address-normalization/actions/workflows/ci.yml/badge.svg)](https://github.com/gmaniac/us-address-normalization/actions/workflows/ci.yml)\n[![npm version](https://badge.fury.io/js/us-address-normalization.svg)](https://www.npmjs.com/package/us-address-normalization)\n\n## Purpose\n\nThe 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.\n\nNormalize US mailing addresses without the need for an external service.\n\n## Limitations\n\nThis 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.\n\n## Installation\n\n```bash\nnpm install us-address-normalization\n```\n\n## Usage\n\n### Normalizing\n\n```typescript\nimport { Normalizer } from 'us-address-normalization';\n\nconst normalizer = new Normalizer();\n\n// This returns an Address object with the parsed components\nconst address = normalizer.parse('204 southeast Smith Street Harrisburg, or 97446');\n\naddress.getAddressComponents();\n/* output:\n{\n  number: '204',\n  street: 'Smith',\n  street_type: 'St',\n  unit: null,\n  unit_prefix: null,\n  suffix: null,\n  prefix: 'SE',\n  city: 'Harrisburg',\n  state: 'OR',\n  postal_code: '97446',\n  postal_code_ext: null,\n  street_type2: null,\n  prefix2: null,\n  suffix2: null,\n  street2: null,\n}\n*/\n\naddress.toString();\n// \"204 SE Smith St, Harrisburg, OR 97446\"\n```\n\n### Convenience Functions\n\n```typescript\nimport { parseAddress, parseAddressFromComponents } from 'us-address-normalization';\n\n// Parse from a single string\nconst address = parseAddress('204 SE Smith St, Harrisburg, OR 97446');\n\n// Parse from components\nconst address2 = parseAddressFromComponents(\n  '204 SE Smith St',\n  null, // address line 2\n  'Harrisburg',\n  'OR',\n  '97446'\n);\n```\n\n### Comparing\n\n```typescript\nimport { Normalizer } from 'us-address-normalization';\n\nconst normalizer = new Normalizer();\n\nconst address1 = normalizer.parse('204 southeast Smith Street Harrisburg, or 97446');\nconst address2 = normalizer.parse('204 SE Smith St. Harrisburg, Oregon 97446');\n// Same street, different number\nconst address3 = normalizer.parse('207 SE Smith St. Harrisburg, Oregon 97446');\n\naddress1.is(address2); // true\naddress2.is(address3); // false\naddress1.isSameStreet(address3); // true\n\n// or compare hashes directly\naddress1.getFullHash() === address2.getFullHash(); // true\n```\n\n### Formatting\n\n```typescript\nimport { Normalizer } from 'us-address-normalization';\n\nconst normalizer = new Normalizer();\nconst address = normalizer.parse('204 southeast Smith Street Harrisburg, or 97446');\n\naddress.toString();\n// \"204 SE Smith St, Harrisburg, OR 97446\"\n\naddress.toArray();\n// ['204 SE Smith St', 'Harrisburg, OR 97446']\n```\n\n### Hashing\n\nIf 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`.\n\n```typescript\nimport { SimpleAddress } from 'us-address-normalization';\n\nconst address = new SimpleAddress('1234 Main St NE', null, 'Minneapolis', 'MN', '55401');\naddress.getHash(); // full hash minus zip\naddress.getFullHash(); // full hash including zip\n\n// or do it all with the static method:\nSimpleAddress.hashFromParts('1234 Main St NE', null, 'Minneapolis', 'MN', '55401');\n\n// CANNOT hash street, since the component parts don't exist\naddress.getStreetHash(); // throws AddressNotNormalizedError\n```\n\n### Hash Types\n\nThe library provides three different hash types for different comparison needs:\n\n- **`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.\n- **`getFullHash()`** - Hash of the complete address including zip code. Use for exact matching.\n- **`getStreetHash()`** - Hash of just the street components (prefix, street name, type, suffix). Useful for finding addresses on the same street regardless of number.\n\n### Configuration Options\n\n```typescript\nimport { Normalizer } from 'us-address-normalization';\n\nconst normalizer = new Normalizer({\n  strictMode: false, // When false, returns SimpleAddress on parse failure instead of null\n  directionalLookups: { /* custom directional mappings */ },\n  stateCodesLookups: { /* custom state code mappings */ },\n  streetTypesLookups: { /* custom street type mappings */ },\n});\n```\n\n### Using with CommonJS\n\n```javascript\nconst { Normalizer, parseAddress } = require('us-address-normalization');\n\nconst normalizer = new Normalizer();\nconst address = normalizer.parse('1234 Main St, Minneapolis, MN 55401');\nconsole.log(address.toString());\n```\n\n## API Reference\n\n### Classes\n\n- `Normalizer` - Main parser class\n- `Address` - Normalized address with components and hashing\n- `SimpleAddress` - Non-normalized address for hashing only\n- `AddressNotNormalizedError` - Error thrown when street hash is requested from SimpleAddress\n\n### Functions\n\n- `parseAddress(address: string, options?)` - Convenience function to parse an address string\n- `parseAddressFromComponents(addr1, addr2, city, state, zip, options?)` - Convenience function to parse from components\n\n### Types\n\n- `NormalizerOptions` - Configuration options for Normalizer\n- `ParsedAddress` - Interface for parsed address components\n- `AddressComponents` - Interface for address component getters\n\n### Lookup Tables\n\nThe library exports the default lookup tables which can be customized:\n\n- `directional` - Directional abbreviations (N, S, E, W, NE, etc.)\n- `stateCodes` - US state and territory codes\n- `streetTypes` - Street type abbreviations (St, Ave, Blvd, etc.)\n\n## Credits\n\nThis is a TypeScript port of the PHP library [zerodahero/address-normalization](https://github.com/zerodahero/address-normalization), which itself is based on the Perl module [Geo::StreetAddress::US](https://metacpan.org/pod/Geo::StreetAddress::US) originally written by Schuyler D. Erle.\n\n## License\n\nMIT\n","readmeFilename":"README.md"}