TABLE OF CONTENTS

• What Is USPS Address Validation And Why Do We Use It?
  • How To Work With USPS Address Recommendation
  • Address Standardization Web Tool Transaction Procedures
    • ZIP Code Lookup Web Tool
    • ZIP Code Lookup Web Tool Transaction Procedures
    • Step 1: Build the XML Request
      • API Signature
      • XML Tags
      • URL
      • XML Request Example
    • Step 2: Make the Internet Connection & Send the XML Request
    • Step 3: Unpack the XML Response
      • XML Output from Unpacked Response
      •  XML Output Example
  • Code Changes
  • Reference

What Is USPS Address Validation And Why Do We Use It?

The US Postal Service defines a complete address as one that has all the address elements necessary to allow an exact match with the current Postal Service ZIP+4 and City State files to obtain the finest level of ZIP+4 and delivery point codes for the delivery address. Address validation is the process of verifying and correcting addresses to ensure accuracy and deliverability. The USPS API provides methods and endpoints that can be used to validate and standardize addresses based on USPS standards.

By leveraging the USPS API's address validation capabilities, developers can improve the quality of address data entered into Znode by users or merchants. The API can validate and correct address elements such as street names, house numbers, city names, ZIP codes, and more. This helps to ensure that the address information provided by users is accurate and complete. Improving address data helps reduce shipping errors, improves the efficiency of mail delivery, and enhances customer satisfaction by ensuring that packages and mail reach the intended recipients without issues.

How To Work With USPS Address Recommendation

The Address Standardization Web Tool corrects errors in street addresses, including abbreviations and missing information, and supplies ZIP Codes and ZIP Codes + 4.  It supports up to five lookups per transaction.

Address Standardization Web Tool Transaction Procedures

The illustration below shows the transactional flow of information to and from the USPS Address Standardization Web Tool server:

ZIP Code Lookup Web Tool

The ZIP Code Lookup Web Tool returns the ZIP Code and ZIP Code + 4 corresponding to the given address, city, and state (use USPS state abbreviations).  The ZIP Code Lookup Web Tool processes up to five lookups per request.

ZIP Code Lookup Web Tool Transaction Procedures

The illustration below shows the transactional flow of information to and from the USPS ZIP Code Lookup Web Tool server:

Step 1: Build the XML Request

API Signature

XML Tags

The table below presents the XML input tags for generating requests and the restrictions on the values allowed.  An error message will be returned if an incorrect value is entered.  Also, be aware of the maximum character amounts allowed for some tags.  If the user enters more than those amounts, an error will not be generated.  The Web Tool will simply pass in the characters up to the maximum amount allowed and disregard the rest.  This is important since the resulting value could prevent a correct response.

e.g., <ZipCodeLookupRequest USERID="yourID">

Tags within the above-defined call are as follows:

URL

XML Tag	Required/ Optional	Description & Values Allowed
<Address ID='#'>	Required Tag/ Required Value	Up to 5 address verifications can be included per transaction. For example: <Address ID="0"></Address>
<FirmName>	Required Tag/ Optional Value	Maximum characters allowed: 38 For example:  <FirmName>XYZ Corp.</FirmName>
<Address1>	Required Tag/ Optional Value	Address Line 1 is used to provide an apartment or suite number, if applicable.  Maximum characters allowed: 38 For example: <Address1></Address1>
<Address2>	Required Tag/ Required Value	Street address. Maximum characters allowed: 38 For example: <Address2>6406 Ivy </Address2>
<City>	Required Tag/ Required Value	Maximum characters allowed: 15 For example: <City>Greenbelt</City>
<State>	Required Tag/ Required Value	Maximum characters allowed: 2 For example: <State>MD</State>

All users will receive access to Address Information APIs upon registration and agreement to the terms and conditions of use. Users will need to enter their own User ID in the examples shown below.

XML Request Example

The  XML request should be in the following form:

http://production.shippingapis.com/ShippingAPI.dll?API=ZipCodeLookup&XML=<ZipCodeLookupRequest USERID="XXXXXX"><Address ID="1"><Address1></Address1><Address2>8 Wildwood Drive</Address2><City>Old Lyme</City><State>CT</State><Zip5>06371</Zip5><Zip4></Zip4></Address></ZipCodeLookupRequest>

 

Step 2: Make the Internet Connection & Send the XML Request

This step involves four separate functions:

1. Making the connection to the USPS Shipping Web Tools server.
2. Sending the request (whether Perl, ASP or any other language).
3. Receiving the response from the Web Tools server.
4. Closing the Internet connection.

If you have recently registered, the registration e-mail will have the name of the server.  If you are an existing user and need the name of the server, please contact the ICCC.  When sending the XML request, the Web Tool name must be specified.  The server name can be found in your Web Tools registration e-mail.  The Web Tool's name is ZipCodeLookup.  The format of the XML transaction is as follows:

http://production/ShippingAPI.dll?API=ZipCodeLookup&XML=<ZipCodeLookupRequest USERID="username">…….</ZipCodeLookupRequest>

Step 3: Unpack the XML Response

When the USPS Shipping Web Tools returns a response, it will either return a successful response document or an error document. 

XML Output from Unpacked Response

** Optional response elements are only returned when there is applicable data for the field.

 XML Output Example

The ZIP Code Lookup Web Tool returns the following information to the user.

<?xml version="1.0" ?>

<ZipCodeLookupResponse>

<Address ID="0">

<FirmName>XYZ CORP.</FirmName>

<Address2>6406 IVY LN</Address2>

<City>GREENBELT</City>

<State>MD</State>

<Zip5>20770</Zip5>

<Zip4>1441</Zip4>

</Address>

<Address ID="1">

<FirmName>ABC COMPANY</FirmName>

<Address1>Apt/Suite 2</Address1>

<Address2>435 S MAIN ST</Address2>

<City>LOS ANGELES</City>

<State>CA</State>

<Zip5>90013</Zip5>

<Zip4>1310</Zip4>

</Address>

</ZipCodeLookupResponse>

Code Changes

We have added a new method in UspsAgent to get recommended address, the input parameter for this method is AddressModel, and portalId returns the recommended address if available.

Reference

https://www.usps.com/business/web-tools-apis/address-information-api.htm#_Toc487629494