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.
//connect to USPS class USPS { public function connectToUSPS($url, $api, $xml) { $ch = curl_init($url); curl_setopt($ch, CURLOPT_POST, 1); curl_setopt($ch, CURLOPT_POSTFIELDS, $api . $xml); curl_setopt($ch, CURLOPT_TIMEOUT, 60); curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1); curl_setopt($ch, CURLOPT_SSL_VERIFYHOST, false); curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false); $result = curl_exec($ch); $error = curl_error($ch); if (empty($error)) { return $result; } else { return false; } } }
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/.
$xml = ' <Address ID="1"> 6406 Ivy Lane Greenbelt MD </Address> ';
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() :
$usps = new USPS(); $result = $usps->connectToUSPS( 'https://production.shippingapis.com/ShippingAPI.dll', 'API=Verify&XML=', $xml);
Let’s have a look at the resulting XML:
6406 IVY LN GREENBELT MD 20770 1441
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:
// (...) if (empty($error)) { return new SimpleXMLElement($result); } else { return false; } // (...)
Then we can read from returned value as follows:
$usps = new USPS(); $result = $usps->connectToUSPS( 'https://production.shippingapis.com/ShippingAPI.dll', 'API=Verify&XML=', $xml); $address = array( 'address' => $result->Address[0]->Address2, 'address2' => $result->Address[0]->Address1, 'city' => $result->Address[0]->City, 'state' => $result->Address[0]->State, 'zip' => $result->Address[0]->Zip5 . (!empty($result->Address[0]->Zip4) ? '-' . $result->Address[0]->Zip4 : '') );
Let’s make the address invalid and see how it looks:
// formation XML $xml = ' <Address ID="1"> Ivy Lane Greenbelt MD </Address> '; $result = $usps->connectToUSPS( 'https://production.shippingapis.com/ShippingAPI.dll', 'API=Verify&XML=', $xml);
As you dump the result you’ll see
-2147219401 API_AddressCleancAddressClean.CleanAddress2;SOLServer.CallAddressDll Address Not Found. 1000440
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:
$xml = ' RIGHTWINDOW Garrison Johns TEST 40 6406 Ivy Lane Greenbelt MD 20770 Reza Dianat 6406 Ivy Lane 293829 Greenbelt MD 20770 6406 Ivy Lane Greenbelt MD 20770 1234 Bound Printed Matter False ID00001 0 10 RMA 123456 False TIF False False ';
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:
$usps = new USPS(); $result = $usps->connectToUSPS( 'https://secure.shippingapis.com/ShippingAPI.dll', 'API=MerchandiseReturnV4&XML=', $xml);
To get the image from the response we need to look into
$result->MerchandiseReturnLabel
Note that it is base64 encoded.
file_put_contents('test_tracking.tif',base64_decode($result->MerchandiseReturnLabel));
You can get a copy of label via email (RecipientEMail request parameter):
$xml = ' RIGHTWINDOW Garrison Johns TEST 40 6406 Ivy Lane Greenbelt MD 20770 Reza Dianat 6406 Ivy Lane 293829 Greenbelt MD 20770 6406 Ivy Lane Greenbelt MD 20770 1234 Bound Printed Matter False ID00001 0 10 RMA 123456 False TIF Test test@gmail.com False False ';
You can access the tracking number itself at
$result->MerchandiseReturnNumber
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:
$xml = ' <TrackID ID="XXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"&gt </TrackRequest&gt';
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.
$usps = new USPS(); $result = $usps->connectToUSPS( 'https://production.shippingapis.com/ShippingAPI.dll', 'API=TrackV2&XML=', $xml);
Look at the result:
Your item was delivered at 9:45 am on February 14, 2011 in Greenbelt, MD 20770. Out for Delivery, February 14, 2011, 8:29 am, Greenbelt, MD 2077. Sorting Complete, February 14, 2011, 8:19 am, Greenbelt, MD 20770 Arrival at Post Office, February 14, 2011, 8:02 am, Greenbelt, MD 20770. Processed through Sort Facility, February 13, 2011, 12:05 am, Greenbelt, MD 20770.
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