Using (or Not) USPS Web Tools API with PHP

Monday, March 21 2005

The US Postal Service has some nice Web Tools (like address based zipcode lookups -- 9 digit zipcodes at that!) that would have worked really well with Pooln. So I set off to build a little web app that took a user's address and returned to them the USPS verified zipcode.

Because I'm using PHP with Pooln, I wanted to stay with PHP for the zipcode lookup. Unfortunately, there is little out there in web-world that describes how to do it. The USPS site doesn't really provide much in the way of examples for any language but curiously less for the common languages used by Web folk. So, for the benefit of others, I wanted to share my experience and results.

I wrote get_zip_parse to demonstrate (to myself and maybe you now) how the interface works. In short, you need to form the XML input required of the API. This is pretty well outlined in the technical guide. What we have to do is build a URL that contains all this XML, submit it to USPS then wait for their reply. To form the URL you can seperate out the URL portion from the XML portion and urlencode it. With the the URL in this form you can use PHP's file_get_contents to retrieve the XML reply from the USPS.

Now that you've got the answer you can use whatever method you'd like to extract it from the XML reply. I wrote a quick and dirty XML parser-like thingy (it's by no means complete) to extract the few fields I needed to grab. The code for this is included in the PHP I provided as the function get_tag_data_r defined at the beginning of the program. I'd use something else if I were you, but I just don't know what -- I couldn't find much.

Here's what you'll get when you run the program (note: you have to get a username and password from the USPS. Death is assured to those who share usernames and passwords.):

-We say to the USPS- http://testing.shippingapis.com/ShippingAPITest.dll?API=ZipCodeLookup&XML=%3CZipCodeLookupRequest%2520USERID%3D%22793POOLN8123%22%2520PASSWORD%3D%22777TW85EC320%22%3E%3CAddress+ID%3D%220%22%3E%3CAddress1%3E%3C%2FAddress1%3E%3CAddress2%3E6406+Ivy+Lane%3C%2FAddress2%3E%3CCity%3EGreenbelt%3C%2FCity%3E%3CState%3EMD%3C%2FState%3E%3C%2FAddress%3E%3C%2FZipCodeLookupRequest%3E

-The USPS says-
<Error>
<Number>80040b1a</Number>
<Description>API Authorization failure. User 793POOLN8123 is not authorized to use API ZipCodeLookup.</Description>
<Source>UspsCom::DoAuth</Source>
</Error>

-We parse the XML Error-
<Number>: 80040b1a
<Description>: API Authorization failure. User 793POOLN8123 is not authorized to use API ZipCodeLookup.
<Source>: UspsCom::DoAuth

This is running on the test server (testing.shippingapis.com) and I believe the error is expected there. The next step, once you validate that your software is working and you're getting valid responses (that is you are getting a nice looking error) from your queries, is to switch over to the "live" server.

Why did I not take this next step (this is the punchline)? The USPS only allows usage of their web API tools to people fascilitate shipping things with the USPS. I had figured that they, as a governmental organization, were providing the data free to anyone who needed it. I forget that the USPS has recently become more like a private company than part of the government. I don't know if that has anything to do with it, but I was planning on using it to let people easily lookup zipcodes to help them find a carpool, so I'm out of luck and thus I must leave things in this incomplete state.

USPS, if you're listening, maybe you'll reconsider? I'll go easy on the server and I'll buy commemorative stamps for gifts this Christmas -- I promise!