Using USPS APIs in PHP

Do you want to know how to use the USPS API in PHP? We'll show you how and share step-by-step examples. (You may also want to check out our video tutorial on how to use the USPS APIs in PHP).

In this article, we'll discuss:

• Creating a USPS account
• Types of USPS APIs
• Code example
• Alternative address validation APIs

Creating a USPS account

Before you can use the USPS APIs, you will need to register with the USPS to receive a USERID. This ID is used in the sample code below, which USERID is mentioned.

Types of USPS APIs

• There are three USPS APIs available:
  • Address Standardization: validates an address and returns the standardized version, along with other helpful metadata.
  • ZIP Code Lookup: a simplified version of the standardization API that returns the ZIP Code and ZIP+4.
  • City/State Lookup: returns the city and state associated with a specified ZIP Code.
• You can only make up to 5 requests per API call.
• XML is used for the Request and Response docs. (Bummer)

Code example

Note that this sample requires a (see Register above).

Address standardization sample code

<?php
$request_doc_template = <<<EOT
<?xml version="1.0"?>
<AddressValidateRequest USERID="">
	<Revision>1</Revision>
	<Address ID="0">
		<Address1>2335 S State</Address1>
		<Address2>Suite 300</Address2>
		<City>Provo</City>
		<State>UT</State>
		<Zip5>84604</Zip5>
		<Zip4/>
	</Address>
</AddressValidateRequest>
EOT;

// prepare xml doc for query string
$doc_string = preg_replace('/[\t\n]/', '', $request_doc_template);
$doc_string = urlencode($doc_string);

$url = "http://production.shippingapis.com/ShippingAPI.dll?API=Verify&XML=" . $doc_string;
echo $url . "\n\n";

// perform the get
$response = file_get_contents($url);

$xml=simplexml_load_string($response) or die("Error: Cannot create object");
print_r($xml);

echo "Address1: " . $xml->Address->Address1 . "\n";
echo "Address2: " . $xml->Address->Address2 . "\n";
echo "City: " . $xml->Address->City . "\n";
echo "State: " . $xml->Address->State . "\n";
echo "Zip5: " . $xml->Address->Zip5 . "\n";

?>

Code discussion

The first section is the XML request document. In this sample, we cheated a bit and just did a multi-line string.
In the XML document string, specify the USERID you received when you registered with USPS.

$request_doc_template = <<<EOT
<?xml version="1.0"?>
<AddressValidateRequest USERID="">
	<Revision>1</Revision>
	<Address ID="0">
		<Address1>2335 S State</Address1>
		<Address2>Suite 300</Address2>
		<City>Provo</City>
		<State>UT</State>
		<Zip5>84604</Zip5>
		<Zip4/>
	</Address>
</AddressValidateRequest>
EOT;

Next, we prepared the XML document string for use in the URL query string. We did this by removing all tabs and newlines, then URL-encoding the document.

We then build the complete URL and echo it to the screen for debugging purposes.

Finally, we make the HTTP GET call using file_get_contents().

// prepare xml doc for query string
$doc_string = preg_replace('/[\t\n]/', '', $request_doc_template);
$doc_string = urlencode($doc_string);

$url = "http://production.shippingapis.com/ShippingAPI.dll?API=Verify&XML=" . $doc_string;
echo $url . "\n\n";

// perform the get
$response = file_get_contents($url);

The last section parses the response into a valid XML document and prints the entire document so you can see all available fields.

Then we output a few of the returned fields to demonstrate how to access XML elements.

$xml=simplexml_load_string($response) or die("Error: Cannot create object");
print_r($xml);

echo "Address1: " . $xml->Address->Address1 . "\n";
echo "Address2: " . $xml->Address->Address2 . "\n";
echo "City: " . $xml->Address->City . "\n";
echo "State: " . $xml->Address->State . "\n";
echo "Zip5: " . $xml->Address->Zip5 . "\n";

Alternative address validation APIs

Smarty also provides an API for validating addresses. So why would Smarty assist in using an API that isn't theirs?

The answer is simple - we care. We want you to get your job done, and if you really want to use the USPS API, hopefully this article will help.

However, we think that once you see how much easier the Smarty PHP SDK is to use, you will want to use it instead of the USPS APIs. And, if you do, you'll get excellent customer service in the process. And of course, we won't even mention that Smarty APIs are blazingly fast!

Take a moment and compare the sample code above with the Smarty PHP SDK sample code.

When you compare the USPS API experience with the experience of using the various Smarty APIs, you'll see that Smarty wins every time. From the easy-to-use JSON response to the stellar support, the faster response times, and the fact that you can make up to 100 requests per API call to Smarty APIs, Smarty wins every time.

Try Smarty for yourself with a free account. You'll be glad that you did.