How to Calculate USPS Shipping Rates With PHP

The U.S. Postal Service provides an online Application Program Interface (API), which you can access with a script on your website to calculate shipping rates. Make your website interactive with scripts written in the PHP (Hypertext Preprocessor) programming language. In this manner you can dynamically calculate the weight of a shipment based on customer inputs, such as item and quantity, query the USPS API to calculate shipping and figure the order total based on the response from the USPS server.

Difficulty:

Moderate

Instructions

Things You'll Need

• Text editor
• Web server running PHP

1. Calculate postage. stamp image by CraterValley Photo from Fotolia.com

   Sign up for an account to use the USPS Rate Calculator API (See Resources). Once you are registered, the USPS will provide you with a username and password. The confirmation email also contains the URL for the testing API server. Once you have tested your script and are ready to go live with it, you must contact the USPS Internet Customer Care Center to be granted access to the production server.

2. Calculate the size and weight of your shipment based on customer input and your own records. For example, if you sell six types of widgets, you will need to figure the shipping weight and dimensions for different quantities of each of the items in your inventory. You may want to store this information in a database and retrieve the information based on the parameters of your customer's query.

3. Use the shipment information from your database to generate an XML tree describing the shipment. Your XML tree must contain required elements and attributes, and may contain additional optional elements and attributes. The root node of the XML tree must be named RateV3Request, and must include the required attribute USERID. Within the root node, your XML string may include multiple Package nodes. Each Package node must have an ID attribute, although the format of the ID attribute is up to you.

4. Include the required and optional child nodes of each Package node in your XML tree. The required nodes are Service, ZipOrigination, ZipDestination, Pounds, Ounces and Size. There are 13 different acceptable values for Service, as specified in the documentation (Ssee References). First class mail may weigh up to 13 ounces; other packages may weigh up to 70 pounds each. If you select First Class as the Service, you must specify the FirstClassMailType (either Letter, Flat or Parcel). ZIP codes must be valid five-digit zip codes. Values for pounds and ounces must be numeric; do not include a unit abbreviation in addition to the numeric value. There are several acceptable values for size: if you are sending a letter, you may leave this node value empty; if the length of the package plus its girth equals 84 inches or less, the value of the size node is Regular; otherwise it is Large or oversize.

5. Type your computer code. clavier,internet image by yam from Fotolia.com

   Create an XML string from the XML tree you constructed in the previous steps. There are several methods for string conversion of an XML datatype; but perhaps the simplest method is to construct your tree in string format as demonstrated in the following example. First set the appropriate variables with your script, based on user selections and the response from your database, as described. Then use the variables to construct a URL. Note that the URL for the API Request in the example is specific to the production server, which you will need additional permission to access.

   <?php
   $packageID = 1;
   $service = 'ALL';
   $origin = '12345';
   $destination = '12345';
   $pounds = 0;
   $ounces = 13;
   $size = 'REGULAR';

   $XMLString = '<RateV3Request USERID="XXXXXXXXX"><Package ID="'.$packageID.'"><Service>'.$service.'</Service><ZipOrigination>'.$origin.'</ZipOrigination><ZipDestination>'.$destination.'</ZipDestination><Pounds>'.$pounds.'</Pounds><Ounces>'.$ounces.'</Ounces><Size>'.$size.'</Size></Package></RateV3Request>';

   $APIRequest = urlencode("http://production.shippingapis.com/ShippingAPI.dll?API=RateV3&XML=$XMLString");
   ?>

6. Send the query and capture the response. The method may differ depending on your server environment and permissions; but one method is to treat the URL as a path to an XML document, and to read this XML document as a SimpleXMLElement object.

   $responseXML = new SimpleXMLElement($APIRequest, NULL, TRUE);

   This provides an easily parsed XML object including the postage rate for the service. For example:

   $postageNodes = $responseXML->xpath('Package/Postage');
   foreach($postageNodes as $node){
   echo 'The rate for '.$node->MailService.' is '.$node->Rate.'<br />';
   }

References

• USPS: Web Tool Kit Development Guide
• USPS: Rates Calculators
• PHP Manual: SimpleXMLElement object

Resources

• USPS: Registration for USPS Web Tools