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
You can view the (short) history of the UspsAddress project in the changelog.md file.