File: README — Documentation for address

# 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](www.melissadata.com/lookups/AddressVerify.asp) and [Canadian address lookup](www.melissadata.com/lookups/CanadianAddressVerify.asp). They both work the same way, however. First, here’s how to standardize a US address:

addr = AddressStandardization::MelissaData::USAddress.standardize(
  :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::MelissaData::USAddress`. 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"

And standardizing a Canadian address:

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

Note that we refer to the province as ‘province`, but `state` works too. The postal code may also be referred to as `zip`.

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

addr = AddressStandardization::GoogleMaps::Address.standardize(
  :street => "1600 Amphitheatre Parkway",
  :city => "Mountain View",
  :state => "CA"
)
addr.street     #=> "1600 AMPHITHEATRE PKWY"
addr.city       #=> "MOUNTAIN VIEW"
addr.state      #=> "CA"
addr.zip        #=> "94043"
addr.country    #=> "USA"

And, again, a Canadian address:

addr = AddressStandardization::GoogleMaps::Address.standardize(
  :street => "1770 Stenson Blvd.",
  :city => "Peterborough",
  :province => "ON"
)
addr.street      #=> "1770 STENSON BLVD"
addr.city        #=> "PETERBOROUGH"
addr.province    #=> "ON"
addr.postalcode  #=> "K9K"
addr.country     #=> "CANADA"

Sharp eyes will notice that the Google Maps API doesn’t return the full postal code for Canadian addresses. If you know why this is please let me know (my email address is below).

## Support

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

file a bug report in the [Issues area on Github](github.com/mcmire/address_standardization/issues)
fork the [project on Github](github.com/mcmire/address_standardization) and send me a pull request
email me (firstname dot lastname at gmail dot com)

## Author/License