Dirección

Información

 

USPS Web Tools™

Application Programming Interface

Guía del usuario

Version 6.0 (07/31/2020)

 

 

 

 

 

Logotipo del United States Postal Service (Servicio Postal de los Estados Unidos)
 

 

 

 


Índice

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

 


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.

Nota: 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: API de información de direcciones

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.

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

Descripción

Tipo

Validation

AddressValidateRequest

Obligatorio

API = AddressValidateRequest

(Alias)

 

AddressValidateRequest / UserID

Obligatorio

This attribute specifies your Web Tools ID. See the Developers Guide for information on obtaining your USERID.

Por Ejemplo: <USERID=”XXXXXXXXXXXX”>

NMTOKEN

 

AddressValidateRequest / Revision

Obligatorio

Integer value used to return of all available response fields. Set this value to 1 to return all currently documented response fields.

Ejemplo: Revision>1</Revision>

String

minLength=0

pattern=\d{1}

pattern=  

AddressValidateRequest / Address /

Obligatorio

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

Obligatorio

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

Obligatorio

 

(Alias)

 

2.2.1   Sample Request

Request: Verificar

<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

Descripción

Tipo

Validation

AddressValidateResponse / Address

Obligatorio

 

(Alias)

 

AddressValidateResponse / Address / FirmName

Optional

 

String

 

AddressValidateResponse / Address / Address1

Optional

 

String

 

AddressValidateResponse / Address / Address2

Obligatorio

 

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 / CarrierRoute

Optional

Carrier Route code.

String

Default is spaces.

Alphanumeric(5)

 

AddressValidateResponse / Address / Footnotes

Optional

Enumeration

Definition

A

Zip Code Corrected

B

City / State Spelling Corrected

C

Invalid City / State / Zip

D

NO ZIP+4 Assigned

E

Zip Code Assigned for Multiple Response

F

Address could not be found in the National Directory File Database

G

Information in Firm Line used for matching

H

Missing Secondary Number

I

Insufficient / Incorrect Address Data

J

Dual Address

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

Z

Match made using the ZIPMOVE product data

 

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.

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

Obligatorio

 

(Alias)

 

2.3.1   Sample Response

Response: Verificar

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

3.2    Request Descriptions

Tag Name

Occurs

Descripción

Tipo

Validation

ZipCodeLookupRequest

Obligatorio

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

Obligatorio

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

Obligatorio

 

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

3.2    Response Descriptions

Tag Name

Occurs

Descripción

Tipo

Validation

ZipCodeLookupResponse

Obligatorio

 

(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

Obligatorio

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

<ZipCodeLookupResponse>

<Address ID="1">

<FirmName>XXXY COMP</FirmName>

<Address2>8 WILDWOOD DR</Address2>

<City>OLD LYME</City>

<State>CT</State>

<Urbanization>SÍ</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

Descripción

Tipo

Validation

CityStateLookupRequest

Obligatorio

API= CityStateLookupRequest

(Alias)

 

CityStateLookupRequest

/ UserID

Obligatorio

 

String

 

CityStateLookupRequest

/ ZipCode

Obligatorio

 

(Group)

 

CityStateLookupRequest / ZipCode / Zip5

Obligatorio

 

Integer

 

CityStateLookupRequest / ZipCode

Obligatorio

Max 5 Zips

(Group)

 

CityStateLookupRequest

Obligatorio

 

(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

Descripción

Tipo

Validation

CityStateLookupResponse

Obligatorio

API = CityStateLookupResponse

(Alias)

 

CityStateLookupResponse / ZipCode

Obligatorio

 

(Group)

 

CityStateLookupResponse / Zip5

Obligatorio

Zip code provided in the request.

Integer

 

CityStateLookupResponse / City

Obligatorio

City returned for the given zip code.

String

 

CityStateLookupResponse / State

Obligatorio

State returned for the given zip code. A two letter enumeration will return for the given state.

Ejemplo:

<State>MD</State>

String

 

CityStateLookupResponse / ZipCode

Obligatorio

 

(Group)

 

CityStateLookupResponse

Obligatorio

 

(Alias)

 

4.3.1   Sample Response

Response: CityStateLookup

 <CityStateLookupResponse>

<ZipCode ID="0">

<Zip5>20024</Zip5>

<City>WASHINGTON</City>

<State>DC</State>

</ZipCode>

</CityStateLookupResponse>

 

Powered By OneLink