International snail mail addressing is a pain. This plugin begins to make it easier.

The basic idea is that mailing addresses need first and foremost to make it OUT of the originating country. It’s beyond the scope of my current work to consider any originating country besides the United States, so that’s where I am beginning. I will leave other countries of origination to the open source community.

Given the United States as a point of origin, my effort here is based on Frank’s Compulsive Guide to Postal Addresses, available from www.columbia.edu/kermit/postal.html as of July 2009, and the USPS International Mail Manual (IMM), available from pe.usps.gov/text/imm/immidx.htm.

The United States Postal Service (USPS) requires (strongly prefers?) a few things:

• That the address be 5 lines long or less.

• That the last address line be a country name recognized by the USPS, in all uppercase.

• That the city line (comprising the city, state, and postal code as appropriate) immediately precede the country line.

The rest of the address should be formatted according to the rules of the receiving country.

Nearly all of the variation in formatting rules applies to the city line. Depending on the receiving country, the three component pieces (e.g. city, state, postal code) have different names, are pieced together in different order with different punctuation, and may or may not be required.

And then there’s Great Britain, which Frank’s Compulsive Guide describes as “where to find the most confusing addresses on earth” (a description confirmed and further confused by a source from within Royal Mail).

I hope to tackle this plugin in stages, with help from the open source community:

# provide standardized USPS country names # provide basic formatting rules for the city line in major countries # provide basic country-specific validation logic # build a best-practice form field generator to collect appropriate address information # expand to other originating countries # continue fleshing out the formatting and validation

Taking regular data and formatting it into an internationally mailable address:

Snail.new(
  :name => "Jon Doe",
  :line_1 => "12345 Somewhere Ln",
  :line_2 => nil,
  :city => "Bentley",
  :region => "WA",
  :postal_code => "6102",
  :country => "Australia"
).to_s

=> "Jon Doe\n12345 Somewhere Ln\nBENTLEY WA  6102\nAUSTRALIA"

By default addresses with a country of USA are considered domestic and the country will be left off any output. To change the home country:

Snail.home_country = "Australia"
Snail.new(
  :name => "Jon Doe",
  :line_1 => "12345 Somewhere Ln",
  :line_2 => nil,
  :city => "Bentley",
  :region => "WA",
  :postal_code => "6102",
  :country => "Australia"
).to_s

=> "Jon Doe\n12345 Somewhere Ln\nBENTLEY WA  6102"

See the test cases for more.

Copyright © 2009 Lance Ivy, released under the MIT license