README.md

address_standardization

Summary

A tiny Ruby library to quickly standardize a postal address, either through MelissaData or Google Maps.

Installation

If you are using Rails, put this in your environment.rb:

config.gem 'address_standardization'

Then run rake gems:install to install the gem.

Otherwise, just run

gem install address_standardization

Usage

Right now this library supports two services: MelissaData and Google Maps.

MelissaData provides two services itself: US address lookup and Canadian address lookup. They both work the same way, however. First, here's how to standardize a US address:

addr = AddressStandardization::MelissaData.standardize_address(
  :street => "1 Infinite Loop",
  :city => "Cupertino",
  :state => "CA"
)

This submits the address to MelissaData. If the address can't be found, you'll get back nil. But if the address can be found (as in this case), you'll get an instance of AddressStandardization::Address. If you store the instance, you can refer to the individual fields like so:

addr.street  #=> "1 INFINITE LOOP"
addr.city    #=> "CUPERTINO"
addr.state   #=> "CA"
addr.zip     #=> "95014-2083"
addr.country #=> "USA"

And standardizing a Canadian address:

addr = AddressStandardization::MelissaData.standardize_address(
  :street => "103 Metig St",
  :city => "Sault Ste Marie",
  :province => "ON",
  :country => "Canada"
)
addr.street      #=> "103 METIG ST RR 4"
addr.city        #=> "SAULT STE MARIE"
addr.province    #=> "ON"
addr.postalcode  #=> "P6A 5K9"
addr.country     #=> "CANADA"

Note that when standardizing a Canadian address, the :country must be "Canada" (or "CANADA", or anything like that). Otherwise it will be treated as a US address.

Also note that I'm referring to the address's province as province, but you can also use state if you like. Same goes for the postal code -- you can also refer to it as zip.

Using Google Maps to validate an address is just as easy:

addr = AddressStandardization::GoogleMaps.standardize_address(
  :street => "1600 Amphitheatre Parkway",
  :city => "Mountain View",
  :state => "CA"
)
addr.street     #=> "1600 Amphitheatre Pkwy",
addr.city       #=> "Mountain View"
addr.county     #=> "Santa Clara"
addr.state      #=> "CA"
addr.zip        #=> "94043"
addr.country    #=> "United States"

And, again, a Canadian address:

addr = AddressStandardization::GoogleMaps.standardize_address(
  :street => "55 East Cordova St. Apt 415",
  :city => "Vancouver",
  :province => "BC"
)
addr.street      #=> "55 E Cordova St"
addr.city        #=> "Vancouver"
addr.county      #=> "Greater Vancouver Regional District"
addr.province    #=> "ON"
addr.postalcode  #=> "V6A 1K3"
addr.country     #=> "Canada"

Support

If you find any bugs with this plugin, feel free to:

• file a bug report in the Issues area on Github
• fork the project on Github and send me a pull request
• email me (firstname dot lastname at gmail dot com)

Author/License

(c) 2008-2010 Elliot Winkler. Released under the MIT license.