USPS Web Tools guide

March 7, 2011 PHP Recipes

Besides its primary role – delivering mail, USPS allows several other functions by means of https://www.usps.com/webtools/. In order to use them you’ll need to make xml in conformance with USPS Web Tools documentation and send it as for example cURL request. Below given is a class that will handle all these cURL requests. It’s the class serving all the requests in this article. We’ll need to pass it only URL, API method name and the XML.


Here are the methods and samples that we can use:
1.US address verification (AddressValidateRequest)
First, form the XML with the test address and USERID that we get get by registering at https://www.usps.com/webtools/.

USPS address verification API method is called Verify and the URL for it is https://production.shippingapis.com/ShippingAPI.dll.
Let’s pass our XML, URL and method name into USPS::connectToUSPS() :

Let’s have a look at the resulting XML:

We see handful XML where we can obtain validated and normalized address from as well as see it’s valid. We can tweak connectToUSPS() method and parse resulting XML with SimpleXML:

Then we can read from returned value as follows:

Let’s make the address invalid and see how it looks:

As you dump the result you’ll see

As we see, the address is not validated. The error is in element. In practice it happens that there is warning in response asking for more detailed info. Often it needs to have suite, apartment etc if Address2 is building. You should populate apt, room, suite in the Address element then.

2. Generating return labels (MerchandiseReturnV4)
USPS Tracking Number – is a unique identifier of a parcel and return label is the label you can send to your customer for return shipment. Here is a sample of Merchandise Return label:

To get it create XML as below:

We recommend to refer to official USPS doc to understand each of the parameters here.
API USPS Web Tools that allows us to get return label is MerchandiseReturnV4, and the method call for this task will look like:

To get the image from the response we need to look into

Note that it is base64 encoded.

You can get a copy of label via email (RecipientEMail request parameter):

You can access the tracking number itself at

3. Getting shipment tracking status by its tracking number (TrackRequest)
You have to know only parcel’s tracking num in order to get actual status of its location. You should use https://trkcnfrm1.smi.usps.com/PTSInternetWeb/ service for that, but you can also do the same with Web Tools
Let’s form the XML:

And send it via TrackV2 API method which is available at https://production.shippingapis.com/ShippingAPI.dll, provided 30-digit tracking number of your shipment in TrackID parameter.

Look at the result:

We see that in TrackSummary there is the shipment current status, its date and also location. In TrackDetail elements there are some more details.

That’s it. This article is only a brief introduction into USPS Web Tools. You can find very detailed documentation and samples here

Author: Alexandr Cvirovsky

Derek

July 29, 2011 at 5:50 am

Bless you for providing this info. The usps docs are wrong and after 10 days of back and forth (mostly forth because it took them 5 days to respond) I finally found this website with working examples. Thanks!
Reply

Sebastian

January 13, 2012 at 8:31 pm

Hi, your guide has been really helpful as there's not a lot of documentation about it online, ¬°thanks!However i'm having an issue with the created image, it does not work, the image is created but when I try to open it says that it might be damaged.Could you give me some insight on why that can happen?Thanks again.Sebastian
Reply

Russ

January 16, 2012 at 5:01 pm

Sebastian, most web browsers don't natively support TIF images. Try using the PDF option instead. Or you can use Image Magick and convert it into a JPG, however, you may lose resolution when doing so as the item being returned by USPS is a TIF encoded bitmap.
Reply

admin Post Author

January 16, 2012 at 5:13 pm

Russ, we figured out the issue with Sebastian offline, so it wasn't a problem with TIFF browser support. Thanks anyway :)
Reply

Russ

January 16, 2012 at 5:16 pm

No problem. But the PDF option is better. Can't beat a vector file when it comes to print resolution. And thanks for putting this tut out there. Really helped me out when I tried to decode the USPS webtools user guides. They are seriously lacking in examples.
Reply

Neil

February 29, 2012 at 7:32 am

Has anyone had any luck getting multiple address results back with the ZipCodeLookup or Verify APIs?I keep getting this undocumented gem of a message:"Default address: The address you entered was found but more information is needed (such as an apartment, suite, or box number) to match to a specific address."Of course, I can specify an Apt# and get back a good one to one, but I would like to offer my user suggestions like the USPS.com GUI displays.
Reply

Hadiman

March 29, 2012 at 2:42 am

thanks man, i've looking at USPS site and there is no working sample code.Thank you, you save my live :)
Reply

Kim in Michigan

October 12, 2012 at 5:16 am

I LOVE YOU! Like others I have been DAYS on this and my clients were starting to doubt I knew what I was doing. The kindness and generousity of developers is like nothing you see in any other profession.
Reply

shana

October 17, 2012 at 4:13 am

I seem to be having a problem with the line:$usps = new USPS();Is there a class I'm missing? I'd appreciate your helpThank you.
Reply

Michael Martin

July 27, 2013 at 12:18 am

This is what I came up with in both CURL and just plain PHPI'm pretty much an amateur "hack" coder, but I don't quit<?php /// send request id CURL must use CSS to format $request1 = <<< XMLREQUEST 6406 Ivy Lane Greenbelt MDXMLREQUEST;$request = "http://production.shippingapis.com/ShippingAPITest.dll?API=Verify&XML=" . rawurlencode($request1);$ch = curl_init();curl_setopt($ch, CURLOPT_URL, $request); curl_setopt($ch, CURLOPT_HEADER, false); curl_setopt($ch, CURLOPT_HTTPGET, true); curl_setopt($ch, CURLOPT_RETURNTRANSFER, true); curl_setopt($ch, CURLOPT_SLL_VERIFYHOST, false); curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false);$response = curl_exec($ch); curl_close($ch);print_r($response);?><?php//send using PHP$html = ""; $url = "http://production.shippingapis.com/ShippingAPITest.dll?API=Verify&XML=" . rawurlencode($request1);$xml = simplexml_load_file($url); for($i = 0; $i Address[$i]->Address2; $City = $xml->Address[$i]->City; $State = $xml->Address[$i]->State; $Zip5 = $xml->Address[$i]->Zip5; $Zip4 = $xml->Address[$i]->Zip4; $html .= "Address2"; $html .= "$City,  "; $html .= "$State"; $html .= "$Zip5  "; $html .= "$Zip4 "; } echo $html; echo ''; echo ''; echo $Address2; echo ''; echo $City; echo ', '; echo $State; echo ''; echo $Zip5; echo'&nbsp'; echo $Zip4; ?>Untitled DocumentAddress2{ display: block; } City{ display: inline; } State{ display: inline; } Zip4{ display: block; } Zip5{ display:inline; } #midBox{ width: 98%; }<?php echo ''; echo ''; echo $response; ?>
Reply

Michael Martin

July 27, 2013 at 12:24 am

forget it, the system keeps deleting the most important part of the code what a friggin joke!!!!!!!!!
Reply


Leave a Reply

Your email address will not be published