Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP

A Javascript/Coffeescript library to parse address strings into their constituent elements

branch: master

Fetching latest commit…

Octocat-spinner-32-eaf2f5

Cannot retrieve the latest commit at this time

Octocat-spinner-32 build
Octocat-spinner-32 lib
Octocat-spinner-32 test
Octocat-spinner-32 .gitignore
Octocat-spinner-32 .gitmodules
Octocat-spinner-32 .travis.yml
Octocat-spinner-32 Cakefile
Octocat-spinner-32 LICENSE
Octocat-spinner-32 README.md
Octocat-spinner-32 package.json
README.md

SnailMailAddressParser

Build Status

A Javascript library for parsing valid address strings into their constituent elements.

SnailMailAddressParse has a page for testing over at: brianmhunt/SnailMailAddressParser.

Purpose

This project exists to crowdsource the difficult problem of parsing addresses. It is intended to assist with the verification that addresses are properly formatted, and where they are properly formatted to parse and return their respective constituents.

At the moment this project does not aim to verify that an address is consistent with reality. For example, this library shall not verify that a given address in California has a Californian zip-code.

Usage

An example in node.js:

> smap = require('snailmailaddressparser')

> smap.parse("100 Bay Street\nToronto, ON M5H 1T1\nCanada")
{ suite: '',
  addressee: '',
  street_number: '100',
  street_name_2: '',
  municipality: 'Toronto',
  province: 'ON',
  postal: 'M5H 1T1',
  country: 'Canada',
  street_name: 'Bay Street' }

API

smap = require('snailmailaddressparser')

Return an instance of the Address Parser.

smap.parse(address_string, defaultCountry)

Parse the address_string, returning an object or throwing an exception where the address cannot be parsed.

If the address_string ends in a valid country name, that country is used, otherwise defaultCountry is used.

The object returned will contain the elements corresponding to the given country.

TODO Where the address_string is ambiguous, return a message indicating that the string is ambiguous, and provide the multiple matching results so that the user can choose which is correct.

Contributing

Drop me a message or send along a pull request on GitHub. I would be delighted to co-ordinate support for addresses that may interest you.

The project is intended to divide-and-conquer. Each country has a strategy for parsing addresses, which strategy may be broken down into a variety of sub-strategies. In this way, I hope edge cases can eventually be shored up.

The built-in tests allow for easy verification that addresses return the expected fields, and the tests are in easilly accessible .yaml files.

Browser Installation

To install on the browser you can simply copy build/snailmailaddressparser.js or build/snailmailaddressparser.min.js to your project and include it in your project with eg the RequireJS require('snailmailaddressparser').

  • lodash
  • XRegExp
  • AMD eg requirejs and require('snailmailaddressparser') or <script src='snailmailaddressparser.js'></script> tag

Requirements for testing

  • Node.js: brew install node With Homebrew

  • Coffee-script npm install -g coffee-script

Install with npm install snailmailaddressparser. To run the build one will need cake, which is part of Coffee-script. One can install Coffee-script with npm-install -g coffee-script.

Cakefile targets

cake toast

Convert the coffeescript in the lib/ directory into a usable javascript AMD modules build/snailmailaddressparser.js and build/snailmailaddressparser.min.js by calling cake toast.

cake test

Run Mocha-based tests on the project.

Fun tip: You can combine targets e.g. run cake toast test to build then test.

Future

It is challenging to correctly parse the plethora of possible addresses, so contributions to the parsing and testing are most welcome.

Some ideas for future builds includes:

  • Integration with libraries or services that provide address verification
  • Geocoding integration

License

This project is licensed under the MIT license, which is included as LICENSE in the source.

Something went wrong with that request. Please try again.