USPS Address

A simple class for a (normalized) United States Postal Service (USPS) address.

On a project in Fall 2014, I needed to compare United States Postal Service (USPS) addresses.

Comparing addresses is tricky. There are many different ways to represent the same physical address. For example, "123 First St" is the same address as "123 1st St". However, to a computer, those are two different strings.

Of course, these days there are several API's that normalize, validate, and authenticate USPS addresses. However, I needed to compare thousands of USPS addresses at a time. I didn't want to rely on a web service (most of which require you to use their system to use their API). I probably couldn't afford it, and they probably wouldn't like me banging away at their servers all day.

So, I wrote my own elementary USPS address class (and USPS normalized address).

Feel free to check out the API documentation, report an issue, contribute, or ask a question.

// create two USPS addresses
$a = new UspsAddress();
$a->setStreet1('Thirty-one Spooner Street')  // note "Thirty-one" and "Street"
	->setCity('Quahog')
	->setState('Rhode Island')       // note "rhode island"
	->setZip('12345');

$b = new UspsAddress();
$b->setStreet1('31 Spooner St')  // note "31" and "St"
	->setCity('Quahog')
	->setState('RI')             // note "RI"
	->setZip('12345');

$a->equals($b);  // returns true

// the UspsAddress class compares addresses using their normalized versions
// that is, it translates abbreviations, lower-cases, trims whitespace, 
//     converts numeric words to their numeric value, etc

// you can access the normalized version of an address if you'd like
$A = $a->getNorm();
$B = $b->getNorm();

// you can also get the address' md5 hash if you'd like to compare it yourself
$a->getHash();  // returns "dc9a67eeb699f3d04ae4ee64b7cf014e"
$b->getHash();  // returns "d8b16c02b495d0b657e44d28e8810ce5"
$A->getHash();  // returns "a8262953aa90b4082d53081701034a56"
$B->getHash();  // returns "a8262953aa90b4082d53081701034a56"

// I've used setters in the examples here
// however, you can also set an address' properties at instantiation
//
$c = new UspsAddress('31 Spooner St', null, 'Quahog', 'RI', '12345');

Tests

I've written tests with about 90% coverage. I'm still getting used to writing unit tests, so let me know if I made a mistake somewhere.

Contributing

Feel free to contribute your own improvements:

Fork
Clone
PHPUnit
Branch
PHPUnit
Code
PHPUnit
Commit
Push
Pull request
Relax and eat a Paleo muffin

See contributing.md for details.

Author

Jack Clayton - clayjs0@gmail.com.

License

The UspsAddress library is released under the MIT License. See the LICENSE file for details.

History