1.0 Introduction

This document contains a Reference Guide to the Address Information Web Tools listed below. See the Developers Guide to learn the administrative process for gaining access to the Web Tools APIs as well as the basic mechanism for calling the APIs and processing the results. The Developer’s Guide also contains information on testing and troubleshooting.

Note: The Request Parameter sections present the XML input tags for generating live requests along with 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.

When building the XML request, pay particular attention to the order and case for tags. An error message will be returned if an incorrect value is entered. Remember that all data and attribute values in this document are for illustration purposes and are to be replaced by your actual values. For instance, a line of sample code may be:

In this instance, you will replace “MD” with the state abbreviation for the address location.

1.1 Before you get started:

For information on registering and getting started with Web Tools, please refer to the Step-By-Step guide found on the Web Tools Technical Documentation Page

1.2 Important Notice: User ID

The Web Tools User ID provided is for you and your company to use when requesting data via the Internet from the U.S. Postal Service API servers. As per the Terms and Conditions of Use Agreement you agreed to during the Web Tools registration process, you are responsible to maintain the confidentiality of your User ID as specified. You may not package any APIs with your User ID for resale or distribution to others. The U.S. Postal Service does not prohibit the reuse and/or distribution of the API documentation (User's Guide) with sample code in order to generate awareness, encourage use or provide ease-of-use to customers or affiliates.

Warning - If the U.S. Postal Service discovers use of the same User ID from more than one web site, all users will be subject to loss of access to the USPS production server and/or termination of the licenses granted under the Terms and Conditions of Use.

1.3 Important Notice: Address Information API

The Address Validation APIs can be used in conjunction with USPS SHIPPING OR MAILING SERVICES ONLY. The address API cannot be utilized for sourcing or deriving addresses to add to your database or system. The primary function of this API lies in validating, completing, and correcting addresses that were captured through your own processes.

2.0 Address Validation API

2.1 Overview

The Address/Standardization “Verify” API, which corrects errors in street addresses, including abbreviations and missing information, and supplies ZIP Codes and ZIP Codes + 4. The Verify API supports up to five lookups per transaction. By eliminating address errors, you will improve overall package delivery service.

2.1.1 API Signature

Scheme	Host	Path	API	XML
https://	secure.shippingapis.com	/ShippingAPI.dll?	API=Verify	&XML=(see below)

2.2 Request Descriptions

Tag Name	Occurs	Description	Type	Validation
AddressValidateRequest	Required	API = AddressValidateRequest	(Alias)
AddressValidateRequest / UserID	Required	This attribute specifies your Web Tools ID. See the Developers Guide for information on obtaining your USERID. For Example: <USERID=”XXXXXXXXXXXX”>	NMTOKEN
AddressValidateRequest / Revision	Required	Integer value used to return of all available response fields. Set this value to 1 to return all currently documented response fields. Example: Revision>1</Revision>	String	minLength=0 pattern=\d{1} pattern=
AddressValidateRequest / Address /	Required	Up to 5 address verifications can be included per transaction.	(group)
AddressValidateRequest / Address / FirmName	Optional	Firm Name Example:<FirmName>XYZ Corp.</FirmName>	String
AddressValidateRequest / Address / Address1	Optional	Delivery Address in the destination address. May contain secondary unit designator, such as APT or SUITE, for Accountable mail.)	String
AddressValidateRequest / Address / Address2	Required	Delivery Address in the destination address. Required for all mail and packages, however 11-digit Destination Delivery Point ZIP+4 Code can be provided as an alternative in the Detail 1 Record.	String
AddressValidateRequest / Address / City	Optional	City name of the destination address.	String	maxLength=15
AddressValidateRequest / Address / State	Optional	Two-character state code of the destination address.	String	maxLength=2
AddressValidateRequest / Address / Urbanization	Optional	Urbanization. For Puerto Rico addresses only.	String	maxLength=28.
AddressValidateRequest / Address / Zip5	Optional	Destination 5-digit ZIP Code. Numeric values (0-9) only. If International, all zeroes.	String	Must be 5-digits.
AddressValidateRequest / Address / Zip4	Optional	Destination ZIP+4 Numeric values (0-9) only. If International, all zeroes. Default to spaces if not available.	String
AddressValidateRequest	Required		(Alias)

2.2.1 Sample Request

Request: Verify

<Address1>SUITE K</Address1>

<Address2>29851 Aventura</Address2>

<City/>

<Zip4/>

</Address>

</AddressValidateRequest>

2.3 Response Descriptions

Tag Name

Occurs

Description

Type

Validation

AddressValidateResponse / Address

Required

(Alias)

AddressValidateResponse / Address / FirmName

Optional

String

AddressValidateResponse / Address / Address1

Optional

String

AddressValidateResponse / Address / Address2

Required

String

AddressValidateResponse / Address / Address2Abbreviation

Optional

Address line 2 abbreviation.

To return abbreviations you must set <Revision>=1

String

AddressValidateResponse / Address / City

Optional

City name of the destination address.

String

AddressValidateResponse / Address / CityAbbreviation

Optional

Abbreviated city name of the destination address. To return abbreviations you must set <Revision>=1

String

AddressValidateResponse / Address / State

Optional

Two-character state code of the destination address.

String

AddressValidateResponse / Address / Urbanization

Optional

String

AddressValidateResponse / Address / Zip5

Optional

Destination 5-digit ZIP Code.

String

AddressValidateResponse / Address / Zip4

Optional

Destination ZIP+4

String

AddressValidateResponse / Address / DeliveryPoint

Optional

String

AddressValidateResponse / Address / ReturnText

Optional

See below for the only response message applicable to return.

“Default address: The address you entered was found but more information is needed (such as an apartment, suite, or box number) to match to a specific address.”

String

AddressValidateResponse / Address / CarrierRoute

Optional

Carrier Route code.

String

Default is spaces.

Alphanumeric(5)

AddressValidateResponse / Address / Footnotes

Optional

See Appendix A for full definitions of each enumeration.

Enumerations=

· A

· B

· C

· D

· E

· F

· G

· H

· I

· J

· K

· L

· LI

· M

· N

· O

· P

· Q

· R

· S

· T

· U

· V

· W

· X

· Y

· Z

AddressValidateResponse / Address / DPVConfirmation

Optional

The DPV Confirmation Indicator is the primary method used by the USPS to determine whether an address was considered deliverable or undeliverable.

Enumeration	Definition
Y	Address was DPV confirmed for both primary and (if present) secondary numbers.
D	Address was DPV confirmed for the primary number only, and the secondary number information was missing.
S	Address was DPV confirmed for the primary number only, and the secondary number information was present by not confirmed.
N	Both primary and (if present) secondary number information failed to DPV confirm.

Blank Address not presented to the hash table.

String

Enumerations=

· Y

· D

· S

· N

AddressValidateResponse / Address / DPVCMRA

Optional

CMRA Indicates a private business that acts as a mail-receiving agent for specific clients. “Y” Address was found in the CMRA table.

“N” Address was not found in the CMRA table.

Blank Address not presented to the hash table.

String

Enumerations=

· Y

· N

AddressValidateResponse / Address / DPVFootnotes

Optional

DPV® Standardized Footnotes - EZ24x7Plus and Mail*STAR are required to express DPV results using USPS standard two character footnotes.

Example: AABB

Footnotes Reporting CASS™ ZIP+4™ Certification

AA – Input address matched to the ZIP+4 file.

A1 – Input address not matched to the ZIP+4 file.

Footnotes Reporting DPV Validation Observations

BB - Matched to DPV (all components).

CC - Secondary number not matched (present but invalid).

N1 - High-rise address missing secondary number.

M1 - Primary number missing.

M3 - Primary number invalid.

P1 - Input Address RR or HC Box number Missing.

P3 - Input Address PO, RR, or HC Box number Invalid.

F1 - Input Address Matched to a Military Address.

G1 - Input Address Matched to a General Delivery Address.

U1- Input Address Matched to a Unique ZIP Code™.

String

Enumerations=

· AA

· A1

· BB

· CC

· N1

· M1

· P1

· P3

· F1

· G1

· U1

AddressValidateResponse / Address / Business

Optional

Indicates whether address is a business or not

String

Enumerations=

· Y

· N

AddressValidateResponse / Address / CentralDeliveryPoint

Optional

Central Delivery is for all business office buildings, office complexes, and/or industrial/professional parks. This may include call windows, horizontal locked mail receptacles, cluster box units.

String

Enumerations=

· Y

· N

AddressValidateResponse / Address / Vacant

Optional

Is the location not occupied.

string

Enumerations=

· Y

· N

AddressValidateResponse

Required

(Alias)

2.3.1 Sample Response

Response: Verify

<Address2>29851 AVENTURA</Address2>

<City>RANCHO SANTA MARGARITA</City>

</Address>

</AddressValidateResponse>

3.0 ZIP Code Lookup API

3.1 Overview

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

3.1.1 API Signature

Scheme	Host	Path	API	XML
https://	secure.shippingapis.com	/ShippingAPI.dll?	API= ZipCodeLookup	&XML=(see below)

3.2 Request Descriptions

Tag Name	Occurs	Description	Type	Validation
ZipCodeLookupRequest	Required	API = ZipCodeLookupRequest	(Alias)
ZipCodeLookupRequest / UserID	Required Once		NMTOKEN
ZipCodeLookupRequest / Address	Optional		(Group)
ZipCodeLookupRequest / Address / FirmName	Optional	Up to 5 address verifications can be included per transaction.	String	Default is spaces.
ZipCodeLookupRequest / Address / Address1	Optional	Delivery Address in the destination address. May contain secondary unit designator, such as APT or SUITE, for Accountable mail.)	String
ZipCodeLookupRequest / Address / Address2	Required	Delivery Address in the destination address. Required for all mail and packages, however 11-digit Destination Delivery Point ZIP+4 Code can be provided as an alternative in the Detail 1 Record.	String
ZipCodeLookupRequest / Address / City	Optional	City name of the destination address. Field is required, unless a verified 11-digit DPV is provided for the mail piece.	String
ZipCodeLookupRequest / Address / State	Optional	Two-character state code of the destination address.	String	Default is spaces for International mail.
ZipCodeLookupRequest / Address / Zip5	Optional	Destination 5-digit ZIP Code. Must be 5-digits. Numeric values (0-9) only. If International, all zeroes.	String
ZipCodeLookupRequest / Address / Zip4	Optional	Destination ZIP+4. Numeric values (0-9) only. If International, all zeroes. Default to spaces if not available.	String
ZipCodeLookupRequest	Required		(Alias)

3.2.1 Sample Request

Request: ZipCodeLookup

<Address2>8 Wildwood Drive</Address2>

</Address>

</ZipCodeLookupRequest>

3.2 Response Descriptions

Tag Name	Occurs	Description	Type	Validation
ZipCodeLookupResponse	Required		(Alias)
ZipCodeLookupResponse / Address	Optional		(Group)
ZipCodeLookupResponse / Address / FirmName	Optional	Firm name provided in request	String	Default is spaces.
ZipCodeLookupResponse / Address / Address1	Optional	Delivery Address in the destination address. May contain secondary unit designator, such as APT or SUITE, for Accountable mail.)	String
ZipCodeLookupResponse / Address / Address2	Required	Delivery Address in the destination address. Required for all mail and packages, however 11-digit Destination Delivery Point ZIP+4 Code can be provided as an alternative in	String
ZipCodeLookupResponse / Address / City	Optional	City name of the destination address. Field is required, unless a verified 11 digit DPV is provided for the mailpiece.	String
ZipCodeLookupResponse / Address / State	Optional	Two-character state code of the destination address.	String	Default is spaces for International mail.
ZipCodeLookupResponse / Address / Urbanization	Optional		String
ZipCodeLookupResponse / Address / Zip5	Optional	Destination 5-digit ZIP Code. Must be 5-digits. Numeric values (0-9) only. If international, all zeroes.	Integer
ZipCodeLookupResponse / Address / Zip4	Optional	Destination ZIP+4. Numeric values (0-9) only. If International, all zeroes.	Integer	Default to spaces if not available.

3.3.1 Sample Response

Response: ZipCodeLookup

<Address2>8 WILDWOOD DR</Address2>

</Address>

</ZipCodeLookupResponse>

4.0 CityStateLookup API

4.1 Overview

City/State Lookup API returns the city and state corresponding to the given ZIP Code. The CityStateLookup API processes up to five lookups per request.

4.1.1 API Signature

Scheme	Host	Path	API	XML
https://	secure.shippingapis.com	/ShippingAPI.dll?	API= CityStateLookup	&XML=(see below)

4.2 Request Descriptions

Tag Name	Occurs	Description	Type	Validation
CityStateLookupRequest	Required	API= CityStateLookupRequest	(Alias)
CityStateLookupRequest / UserID	Required		String
CityStateLookupRequest / ZipCode	Required		(Group)
CityStateLookupRequest / ZipCode / Zip5	Required		Integer
CityStateLookupRequest / ZipCode	Required	Max 5 Zips	(Group)
CityStateLookupRequest	Required		(Alias)

4.2.1 Sample Request

Request: CityStateLookup

</ZipCode>

</CityStateLookupRequest>

4.3 Response Descriptions

Tag Name	Occurs	Description	Type	Validation
CityStateLookupResponse	Required	API = CityStateLookupResponse	(Alias)
CityStateLookupResponse / ZipCode	Required		(Group)
CityStateLookupResponse / Zip5	Required	Zip code provided in the request.	Integer
CityStateLookupResponse / City	Required	City returned for the given zip code.	String
CityStateLookupResponse / State	Required	State returned for the given zip code. A two letter enumeration will return for the given state. Example: <State>MD</State>	String
CityStateLookupResponse / ZipCode	Required		(Group)
CityStateLookupResponse	Required		(Alias)

4.3.1 Sample Response

Response: CityStateLookup

<City>WASHINGTON</City>

</ZipCode>

</CityStateLookupResponse>

5.0 Appendix A – Footnotes Descriptions

Enumeration	Description	Definition
A	Zip Code Corrected	The address was found to have a different 5-digit Zip Code than given in the submitted list. The correct Zip Code is shown in the output address.
B	City / State Spelling Corrected	The spelling of the city name and/or state abbreviation in the submitted address was found to be different than the standard spelling. The standard spelling of the city name and state abbreviation are shown in the output address.
C	Invalid City / State / Zip	The Zip Code in the submitted address could not be found because neither a valid city, state, nor valid 5-digit Zip Code was present. It is also recommended that the requestor check the submitted address for accuracy.
D	No Zip+4 Assigned	This is a record listed by the United State Postal Service on the national Zip+4 file as a non-deliverable location. It is recommended that the requestor verify the accuracy of the submitted address.
E	Zip Code Assigned for Multiple Response	Multiple records were returned, but each shares the same 5-digit Zip Code.
F	Address Could Not Be Found in The National Directory File Database	The address, exactly as submitted, could not be found in the city, state, or Zip Code provided.
G	Information In Firm Line Used for Matching	Information in the firm line was determined to be a part of the address. It was moved out of the firm line and incorporated into the address line.
H	Missing Secondary Number	Zip+4 information indicated this address is a building. The address as submitted does not contain an apartment/suite number.
I	Insufficient / Incorrect Address Data	More than one Zip+4 was found to satisfy the address as submitted. The submitted address did not contain sufficiently complete or correct data to determine a single Zip+4 Code.
J	Dual Address	The input contained two addresses.
K	Multiple Response Due to Cardinal Rule	CASS rule does not allow a match when the cardinal point of a directional changes more than 90%.
L	Address Component Changed	An address component was added, changed, or deleted in order to achieve a match.
M	Street Name Changed	The spelling of the street name was changed in order to achieve a match.
N	Address Standardized	The delivery address was standardized.
O	Lowest +4 Tie-Breaker	More than one Zip+4 Code was found to satisfy the address as submitted. The lowest Zip+4 addon may be used to break the tie between the records.
P	Better Address Exists	The delivery address is matchable, but is known by another (preferred) name.
Q	Unique Zip Code Match	Match to an address with a unique Zip Code.
R	No Match Due To EWS	The delivery address is matchable, but the EWS file indicates that an exact match will be available soon.
S	Incorrect Secondary Address	The secondary information does not match that on the national Zip+4 file. This secondary information, although present on the input address, was not valid in the range found on the national Zip+4 file.
T	Multiple Response Due to Magnet Street Syndrome	The search resulted on a single response; however, the record matched was flagged as having magnet street syndrome.
U	Unofficial Post Office Name	The city or post office name in the submitted address is not recognized by the United States Postal Service as an official last line name (preferred city name) and is not acceptable as an alternate name.
V	Unverifiable City / State	The city and state in the submitted address could not be verified as corresponding to the given 5-digit Zip Code.
W	Invalid Delivery Address	The input address record contains a delivery address other than a PO BOX, General Delivery, or Postmaster with a 5-digit Zip Code that is identified as a “small town default.” The United States Postal Service does not provide street delivery for this Zip Code. The United States Postal Service requires use of a PO BOX, General Delivery, or Postmaster for delivery within this Zip Code.
X	Unique Zip Code Generated	Default match inside a unique Zip Code.
Y	Military Match	Match made to a record with a military Zip Code.
Z	Match Mode Using the ZIPMOVE Product Data	The ZIPMOVE product shows which Zip+4 records have moved from one Zip Code to another.

6.0 Error Response

Error conditions are handled at the main XML document level. When parsing, it is best to check for an error document first before checking for good data. Error documents have the following format:

<Error>

<Number></Number>

<Source></Source>

<Description></Description>

<HelpFile></HelpFile>

<HelpContext></HelpContext>

</Error>

Where:

Number = the error number generated by the Web Tools server.
Source = the component and interface that generated the error on the Web Tools server.
Description = the error description. See table below for details.

<Description> Message	Definition
Invalid Address.	Address is not valid
Invalid Zip Code.	Zip code is not valid
Invalid State Code.	State code is not valid
Invalid City.	City is not valid
Address Not Found.	Address not found
Multiple addresses were found for the information you entered, and no default exists.	More than 1 address was found for the address information provided and there is not default designated for this address. The address as submitted does not contain an apartment/suite number. It is recommended that the requestor check the submitted address and add the missing apartment or suite number
Single Response - exact match	Exact match on address
Default address: The address you entered was found but more information is needed (such as an apartment, suite, or box number) to match to a specific address.	Default address was returned, need additional information to get an exact match. The address as submitted does not contain an apartment/suite number. It is recommended that the requestor check the submitted address and add the missing apartment or suite number

HelpFile = [reserved for future use].
HelpContext = [reserved for future use].

Errors that are further down in the hierarchy also follow the above format.

An <Error> element may be returned at the top (response) level if there is a problem with the syntax of the request, or if a system error occurs.