Australia Address Parser

1.0.1 · active · verified Tue Apr 21

The `australia-address-parser` package offers a dedicated, regex-based utility for programmatically parsing Australian street addresses and street intersections from unstructured user-provided strings. Its core functionality involves dissecting an address into constituent parts such as street number, name, type, suburb, state, and postcode. A key differentiator is its ability to explicitly identify and return the street type (e.g., Road, Street, Avenue), a detail often generalized or omitted by more comprehensive mapping services like Google APIs. The package is currently at version 1.0.1, although its README indicates it is still under active development, suggesting that its API might evolve, and new features or refinements to its parsing logic could be introduced with a potentially frequent release cadence. It's suitable for applications requiring structured address data extraction, data validation, or enhancing geo-coding efforts by providing more granular address components for Australian locations.

Common errors

```
ReferenceError: require is not defined
```
cause Attempting to use `require()` in an ECMAScript Module (ESM) context without proper configuration or a bundler that transpiles CommonJS.

fix If working in a pure ESM Node.js environment, consider using a tool like `createRequire` from the `module` module, or using a build step to transpile CommonJS to ESM. For browser use, ensure the `auAddressParser.min.js` script is loaded via a `<script>` tag.
```
TypeError: parser.parseLocation is not a function
```
cause The default export of the package was not correctly imported or accessed, or the global object in the browser was not loaded.

fix Ensure you are using `const parser = require('australia-address-parser');` for Node.js CommonJS. In a browser, verify that `auAddressParser.min.js` is loaded and you are calling `auAddressParser.parseLocation(...)`.
```
Output object is missing expected fields or contains incorrect values after parsing.
```
cause The regex-based parser failed to correctly interpret an address string due to an unsupported format, ambiguity, or missing patterns.

fix Review the input address string for unusual formatting. Consult the package's GitHub issues for similar reports or consider contributing improvements to its regex patterns for better coverage.

Warnings

breaking Despite being at version 1.0.1, the project's README explicitly states it is 'currently in development'. This indicates that the API or parsing logic may undergo significant changes, potentially introducing breaking changes without major version increments.
Fix: Monitor the GitHub repository for updates and test thoroughly after package upgrades. Consider locking to a specific patch version if stability is critical.
gotcha As a regex-based parser, `australia-address-parser` might not cover all possible address variations or ambiguous cases found in real-world Australian addresses. Edge cases or unconventional formatting could lead to incorrect or incomplete parsing results.
Fix: Validate parsing results against a diverse set of real-world addresses. Consider pre-processing addresses to normalize common patterns if parsing failures are observed.
gotcha The package does not provide TypeScript type definitions, meaning TypeScript projects will need to declare modules or use `@ts-ignore` to import it without type errors.
Fix: Create a `declarations.d.ts` file with `declare module 'australia-address-parser';` or a more specific definition for `parseLocation` to provide basic type safety.

Install

npm install australia-address-parser npm
yarn add australia-address-parser yarn
pnpm add australia-address-parser pnpm

Imports

parser
wrong:
```
import parser from 'australia-address-parser';
```
correct:
```
const parser = require('australia-address-parser');
```
The package is designed for CommonJS environments in Node.js. Direct ESM import (`import ... from '...'`) without a transpilation step or a CommonJS wrapper will result in an error in pure ESM projects.
auAddressParser
```
// The 'auAddressParser' global object is available after loading auAddressParser.min.js via a script tag.
```
When used directly in a browser environment by including `auAddressParser.min.js` via a `<script>` tag, the parsing functions become available under the global `auAddressParser` object.

Quickstart

Demonstrates how to parse various Australian address formats (standard, intersection, with unit) using the `parseLocation` method.

const parser = require('australia-address-parser');

// Example 1: Standard Street Address
const standardAddress = '1 Darling Island Road, Pyrmont NSW 2009';
const parsedStandard = parser.parseLocation(standardAddress);
console.log('Standard Address:', parsedStandard);
/* Output:
{
  streetNumber: '1',
  streetName: 'Darling Island',
  streetType: 'Road',
  suburb: 'Pyrmont',
  state: 'NSW',
  postcode: '2009'
}*/

// Example 2: Intersection of Roads
const intersectionAddress = 'Breakfast Creek Rd & Austin St, Newstead QLD 4006';
const parsedIntersection = parser.parseLocation(intersectionAddress);
console.log('Intersection Address:', parsedIntersection);
/* Output:
{
  streetName1: 'Breakfast Creek',
  streetType1: 'Rd',
  streetName2: 'Austin',
  streetType2: 'St',
  suburb: 'Newstead',
  state: 'QLD',
  postcode: '4006',
  streetName: 'Breakfast Creek Rd & Austin St'
}*/

// Example 3: Address with Unit Number
const unitAddress = '13A Burlina Cct, Elizabeth Hills NSW 2171';
const parsedUnit = parser.parseLocation(unitAddress);
console.log('Unit Address:', parsedUnit);
/* Output:
{
  unitType: 'unit',
  unitNumber: 'A',
  streetName: 'Burlina',
  streetType: 'Cct',
  suburb: 'Elizabeth Hills',
  state: 'NSW',
  postcode: '2171'
}*/

view raw JSON →