Address

Information

USPS Web Tools™

Application Programming Interface
User Guide
Version 6.0 (07/31/2020)
USPS Web Tools User Guide

Table of Contents
1.0 Introduction ............................................................................................................................... 3
1.1 Before you get started: .......................................................................................................... 3
1.2 Important Notice: User ID...................................................................................................... 3
1.3 Important Notice: Address Information API ............................................................................ 3
2.0 Address Validation API ............................................................................................................. 3
2.1 Overview .............................................................................................................................. 3
2.1.1 API Signature ..................................................................................................................... 4
2.2 Request Descriptions ........................................................................................................... 4
2.2.1 Sample Request ................................................................................................................. 5
2.3 Response Descriptions ......................................................................................................... 5
2.3.1 Sample Response ............................................................................................................ 10
3.0 ZIP Code Lookup API .............................................................................................................. 10
3.1 Overview ............................................................................................................................ 10
3.1.1 API Signature ................................................................................................................... 10
3.2 Request Descriptions .......................................................................................................... 11
3.2.1 Sample Request ............................................................................................................... 11
3.2 Response Descriptions ....................................................................................................... 12
3.3.1 Sample Response ............................................................................................................ 12
4.0 CityStateLookup API ............................................................................................................... 13
4.1 Overview ............................................................................................................................ 13
4.1.1 API Signature ................................................................................................................... 13
4.2 Request Descriptions .......................................................................................................... 13
4.2.1 Sample Request ............................................................................................................... 13
4.3 Response Descriptions ....................................................................................................... 13
4.3.1 Sample Response ............................................................................................................ 14

2
USPS Web Tools User Guide

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:
<State>MD</State>
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 must only be used on an individual transactional basis, i.e. not batch processing
or cleansing of a database, but as a customer enters the information into a form on a website. Failure to
comply with these terms and conditions can result in termination of USPS API access without prior notice.

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.

3
USPS Web Tools User Guide

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 = (Alias)

AddressValidateRequest
AddressValidateRequest Required This attribute specifies NMTO
/ UserID your Web Tools ID. See KEN
the Developers Guide for
information on obtaining
your USERID.
For Example:
<USERID=”XXXXXXXXXX
XX”>
AddressValidateRequest Required Integer value used to String minLength=0
/ Revision return of all available pattern=\d{1}
response fields. Set this pattern=
value to 1 to return all
currently documented
response fields.
Example:
Revision>1</Revision>
AddressValidateRequest Required Up to 5 address (group)
/ Address / verifications can be
included per transaction.
AddressValidateRequest Optional Firm Name String
/ Address / FirmName Example:<FirmName>XYZ
Corp.</FirmName>
AddressValidateRequest Optional Delivery Address in the String
/ Address / Address1 destination address. May
contain secondary unit
designator, such as APT or
SUITE, for Accountable
mail.)
AddressValidateRequest Required Delivery Address in the String
/ Address / Address2 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.
AddressValidateRequest Optional City name of the String maxLength=15
/ Address / City destination address.
AddressValidateRequest Optional Two-character state code String maxLength=2
/ Address / State of the destination address.
AddressValidateRequest Optional Urbanization. String maxLength=28.
/ Address / Urbanization

4
USPS Web Tools User Guide

Tag Name Occurs Description Type Validation

For Puerto Rico addresses

only.
AddressValidateRequest Optional Destination 5-digit ZIP String Must be 5-digits.
/ Address / Zip5 Code. Numeric values (0-
9) only. If International, all
zeroes.
AddressValidateRequest Optional Destination ZIP+4 Numeric String
/ Address / Zip4 values (0-9) only. If
International, all zeroes.
Default to spaces if not
available.
AddressValidateRequest Required (Alias)

2.2.1 Sample Request

Request: Verify
<AddressValidateRequest USERID="XXXXXXXXXXXX">
<Revision>1</Revision>
<Address ID="0">
<Address1>SUITE K</Address1>
<Address2>29851 Aventura</Address2>
<City/>
<State>CA</State>
<Zip5>92688</Zip5>
<Zip4/>
</Address>
</AddressValidateRequest>

2.3 Response Descriptions

Tag Name Occurs Description Type Validation

AddressValidateResponse Required (Alias)

/ Address
AddressValidateResponse Optional String
/ Address / FirmName
AddressValidateResponse Optional String
/ Address / Address1
AddressValidateResponse Required String
/ Address / Address2
AddressValidateResponse Optional Address line 2 abbreviation. String
/ Address / To return abbreviations you must
Address2Abbreviation set <Revision>=1
AddressValidateResponse Optional City name of the destination String
/ Address / City address.
AddressValidateResponse Optional Abbreviated city name of the String
/ Address / destination address. To return
CityAbbreviation abbreviations you must set
<Revision>=1

5
USPS Web Tools User Guide

Tag Name Occurs Description Type Validation

AddressValidateResponse Optional Two-character state code of the String

/ Address / State destination address.
AddressValidateResponse Optional String
/ Address / Urbanization
AddressValidateResponse Optional Destination 5-digit ZIP Code. String
/ Address / Zip5
AddressValidateResponse Optional Destination ZIP+4 String
/ Address / Zip4
AddressValidateResponse Optional String
/ Address / DeliveryPoint
AddressValidateResponse Optional Carrier Route code. String Default is
/ Address / CarrierRoute spaces.
Alphanumeric(5)

AddressValidateResponse Optional Enumeration Definition Enumerations=

/ Address / Footnotes • A
A Zip Code
• B
Corrected
• C
B City / State • D
Spelling • E
Corrected • F
C Invalid City / • G
State / Zip • H
D NO ZIP+4 • I
Assigned • J
E Zip Code • K
Assigned for • L
Multiple • LI
Response • M
F Address • N
could not be • O
found in the • P
National • Q
Directory File • R
Database • S
G Information • T
in Firm Line • U
used for • V
matching • W
H Missing • X
Secondary • Y
Number • Z
I Insufficient /
Incorrect
Address
Data
J Dual
Address

6
USPS Web Tools User Guide

Tag Name Occurs Description Type Validation

K Multiple
Response
due to
Cardinal
Rule
L Address
component
changed
LI Match has
been
converted
via LACS
M Street Name
changed
N Address
Standardized
O Lowest +4
Tie-Breaker
P Better
address
exists
Q Unique Zip
Code match
R No match
due to EWS
S Incorrect
Secondary
Address
T Multiple
response
due to
Magnet
Street
Syndrome
U Unofficial
Post Office
name
V Unverifiable
City / State
W Invalid
Delivery
Address
X No match
due to out of
range alias
Y Military
match

7
USPS Web Tools User Guide

Tag Name Occurs Description Type Validation

Z Match made
using the
ZIPMOVE
product data
AddressValidateResponse Optional The DPV Confirmation Indicator is String Enumerations=
/ Address / the primary method used by the • Y
DPVConfirmation USPS to determine whether an • D
address was considered • S
deliverable or undeliverable. • N
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

8
USPS Web Tools User Guide

Tag Name Occurs Description Type Validation

failed to DPV
confirm.

Blank Address not presented to

the hash table.
AddressValidateResponse Optional CMRA Indicates a private String Enumerations=
/ Address / DPVCMRA business that acts as a mail- • Y
receiving agent for specific • N
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.
AddressValidateResponse Optional DPV® Standardized Footnotes - String Enumerations=
/ Address / DPVFootnotes EZ24x7Plus and Mail*STAR are • AA
required to express DPV results • A1
using USPS standard two • BB
character footnotes. • CC
Example: AABB • N1
• M1
Footnotes Reporting CASS™ • P1
ZIP+4™ Certification
• P3
• F1
AA – Input address matched to
the ZIP+4 file. • G1
A1 – Input address not matched • U1
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.

9
USPS Web Tools User Guide

Tag Name Occurs Description Type Validation

U1- Input Address Matched to a

Unique ZIP Code™.
AddressValidateResponse Optional Indicates whether address is a String Enumerations=
/ Address / Business business or not • Y
• N
AddressValidateResponse Optional Central Delivery is for all business String Enumerations=
/ Address / office buildings, office complexes, • Y
CentralDeliveryPoint and/or industrial/professional • N
parks. This may include call
windows, horizontal locked mail
receptacles, cluster box units.
AddressValidateResponse Optional Is the location not occupied. string Enumerations=
/ Address / Vacant • Y
• N
AddressValidateResponse Required (Alias)

2.3.1 Sample Response

Response: Verify
<AddressValidateResponse>
<Address ID="0">
<Address1> STE K</Address1>
<Address2>29851 AVENTURA</Address2>
<City>RANCHO SANTA MARGARITA</City>
<CityAbbreviation>RCHO STA MARG</CityAbbreviation>
<State>CA</State>
<Zip5>92688</Zip5>
<Zip4>2014</Zip4>
<DeliveryPoint>83</DeliveryPoint>
<CarrierRoute>C057</CarrierRoute>
<Footnotes>N</Footnotes>
<DPVConfirmation>Y</DPVConfirmation>
<DPVCMRA>N</DPVCMRA>
<DPVFootnotes>AABB</DPVFootnotes>
<Business>Y</Business>
<CentralDeliveryPoint>N</CentralDeliveryPoint>
<Vacant>N</Vacant>
</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)

10
USPS Web Tools User Guide

3.2 Request Descriptions

Tag Name Occurs Description Type Validation

ZipCodeLookupRequest Required API = ZipCodeLookupRequest (Alias)

ZipCodeLookupRequest Required NMTOKE
/ UserID Once N
ZipCodeLookupRequest Optional (Group)
/ Address
ZipCodeLookupRequest Optional Up to 5 address verifications can String Default is spaces.
/ Address / FirmName be included per transaction.
ZipCodeLookupRequest Optional Delivery Address in the String
/ Address / Address1 destination address. May contain
secondary unit designator, such
as APT or SUITE, for
Accountable mail.)
ZipCodeLookupRequest Required Delivery Address in the String
/ Address / Address2 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.
ZipCodeLookupRequest Optional City name of the destination String
/ Address / City address. Field is required, unless
a verified 11-digit DPV is
provided for the mail piece.
ZipCodeLookupRequest Optional Two-character state code of the String Default is spaces for
/ Address / State destination address. International mail.
ZipCodeLookupRequest Optional Destination 5-digit ZIP Code. String
/ Address / Zip5 Must be 5-digits. Numeric values
(0-9) only. If International, all
zeroes.
ZipCodeLookupRequest Optional Destination ZIP+4. Numeric String
/ Address / Zip4 values (0-9) only. If International,
all zeroes. Default to spaces if
not available.
ZipCodeLookupRequest Required (Alias)

3.2.1 Sample Request

Request: ZipCodeLookup
<ZipCodeLookupRequest USERID="XXXXXXXXXXXX">
<Address ID="1">
<Address1></Address1>
<Address2>8 Wildwood Drive</Address2>
<City>Old Lyme</City>
<State>CT</State>
<Zip5>06371</Zip5>
<Zip4></Zip4>
</Address>
</ZipCodeLookupRequest>

11
USPS Web Tools User Guide

3.2 Response Descriptions

Tag Name Occurs Description Type Validation

ZipCodeLookupResponse Required (Alias)

ZipCodeLookupResponse Optional (Group)

/ Address

ZipCodeLookupResponse Optional Firm name provided in String Default is spaces.

/ Address / FirmName request

ZipCodeLookupResponse Optional Delivery Address in the String

/ Address / Address1 destination address. May
contain secondary unit
designator, such as APT or
SUITE, for Accountable
mail.)

ZipCodeLookupResponse Required Delivery Address in the String

/ Address / Address2 destination address.
Required for all mail and
packages, however 11-digit
Destination Delivery Point
ZIP+4 Code can be provided
as an alternative in

ZipCodeLookupResponse Optional City name of the destination String

/ Address / City address. Field is required,
unless a verified 11 digit
DPV is provided for the
mailpiece.
Default is spaces for
ZipCodeLookupResponse Optional Two-character state code of String
International mail.
/ Address / State the destination address.

ZipCodeLookupResponse Optional String

/ Address / Urbanization

ZipCodeLookupResponse Optional Destination 5-digit ZIP Code. Integer

/ Address / Zip5 Must be 5-digits. Numeric
values (0-9) only. If
international, all zeroes.
Destination ZIP+4. Numeric
ZipCodeLookupResponse Optional Integer Default to spaces if not
values (0-9) only. If
/ Address / Zip4 International, all zeroes. available.

3.3.1 Sample Response

Response: ZipCodeLookup

12
USPS Web Tools User Guide

<ZipCodeLookupResponse>
<Address ID="1">
<FirmName>XXXY COMP</FirmName>
<Address2>8 WILDWOOD DR</Address2>
<City>OLD LYME</City>
<State>CT</State>
<Urbanization>YES</Urbanization>
<Zip5>06371</Zip5>
<Zip4>1844</Zip4>
</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= (Alias)

CityStateLookupRequest
CityStateLookupRequest Required String
/ UserID
CityStateLookupRequest Required (Group)
/ ZipCode
CityStateLookupRequest Required Integer
/ ZipCode / Zip5
CityStateLookupRequest Required Max 5 Zips (Group)
/ ZipCode
CityStateLookupRequest Required (Alias)

4.2.1 Sample Request

Request: CityStateLookup
<CityStateLookupRequest USERID="XXXXXXXXXXXX">
<ZipCode ID='0'>
<Zip5>20024</Zip5>
</ZipCode>
</CityStateLookupRequest>

4.3 Response Descriptions

Tag Name Occurs Description Type Validation

CityStateLookupResponse Required API = (Alias)

CityStateLookupResponse

13
USPS Web Tools User Guide

CityStateLookupResponse Required (Group)

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

4.3.1 Sample Response

Response: CityStateLookup
<CityStateLookupResponse>
<ZipCode ID="0">
<Zip5>20024</Zip5>
<City>WASHINGTON</City>
<State>DC</State>
</ZipCode>
</CityStateLookupResponse>

14