USPS Address Recommendation


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:

Address Standardization Web Tool Server Laptop computer icon. Inputs via XML request are address I D # (up to 5), recipient name, recipient address and recipient zip code(s). Server icon.  Server tasks are looks up in address management system, gets correct address and builds XML response. Laptop computer icon.  Outputs via XML response is corrected address(es).

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








API= ZipCodeLookup

&XML=(see below)

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.



Description & Values Allowed



Input tag exactly as presented.



Use the user ID provided with registration.

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

Tags within the above-defined call are as follows:







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>


Required Tag/

Optional Value

Maximum characters allowed: 38

For example:  <FirmName>XYZ Corp.</FirmName>


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>


Required Tag/

Required Value

Street address.

Maximum characters allowed: 38

For example: <Address2>6406 Ivy </Address2>


Required Tag/

Required Value

Maximum characters allowed: 15

For example: <City>Greenbelt</City>


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:<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



Type of Response


Address ID Number

<Address ID='#'>

Name of Firm

<FirmName> **

Address Line 1

<Address1> **

Address Line 2


City (abbreviated form if available)




Urbanization Code

<Urbanization> **

ZIP Code


ZIP Code + 4


** 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" ?>


<Address ID="0">

<FirmName>XYZ CORP.</FirmName>

<Address2>6406 IVY LN</Address2>






<Address ID="1">

<FirmName>ABC COMPANY</FirmName>

<Address1>Apt/Suite 2</Address1>

<Address2>435 S MAIN ST</Address2>

<City>LOS ANGELES</City>






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.

Note: The default USPS AVS API request quota is 60 calls/hour, if exceeded, the Znode webstore will show this error: "The number of requests has exceeded the quota established for the time period." 

The default quota can be increased by requesting USPS via applying the same over a request form. The details are as below:

  • Form: Microsoft Forms
  • Support Email for additional assistance:


Did you find it helpful? Yes No

Send feedback
Sorry we couldn't be helpful. Help us improve this article with your feedback.