地址
信息

USPS Web Tools™

Application Programming Interface

User’s Guide

Document Version 5.3 (02/19/2019)

 

 

 

 

 

 

 

 

 

 

 

 


 

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 4

1.3.1 Error Responses 4

2.0 Address Web Tool 4

2.1 Overview_ 4

2.2 API Signature_ 4

2.3 Tag Descriptions 5

2.3.1 Request Parameters 5

3.0 ZIP Code Lookup Web Tool 9

3.1 Overview_ 9

3.1.1 API Signature  9

3.1.2 Request Parameters 9

3.1.3 Make the Internet Connection & Send the XML Request 11

3.2 Response Parameters 12

4.2.1 XML Output Example  12

4.0 City/State Lookup Web Tool 13

4.1 Build the XML Request 13

4.1.1 API Signature  13

4.1.2 Request Parameters 13

4.3 Response Parameters 15

5.3.1 XML Output from Unpacked Response 15


 

 

1.0 Introduction

This document contains a Reference Guide to the Address Information Web Tools listed below. See the Developer’s Guide step-by-step instructions  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 trouble-shooting.

·                  Address /Standardization Web Tool, which 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.  By eliminating address errors, you will improve overall package delivery service.

·                  ZIP Code Lookup Web Tool, which 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.

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

请注意: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 Technical Documentation section of the Web Tools page on usps.com/webtools.

 

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

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.

1.3.1     Error Responses

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.

§  HelpFile = [reserved for future use].

§  HelpContext = [reserved for future use].

For Web Tools that can handle multiple transactions, the error conditions for requests for multiple responses to be returned together are handled at the response level.  例如:a Web Tool developer sends a request for rates for two packages.  If the addresses are non-existent, an “Error document” is returned to the user.  On the other hand, if the address for the first package is acceptable but not the second, the response document contains the information for the first address, but under the XML tag for the second address there is an error tag.

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

 

2.0  Address Web Tool

2.1    Overview

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.  By eliminating address errors, you will improve overall package delivery service.

 

2.2    API Signature

Scheme

Host

小道

API

XML

https://

secure.shippingapis.com

/ShippingAPI.dll?

API=Verify

&XML=(see below)

http://

production.shippingapis.com

/ShippingAPI.dll?

API=Verify

&XML=(see below)

 

 

2.3 Tag Descriptions

The table below presents the XML input tags for generating live 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

2.3.1   Request Parameters

Tag Name

Occurs

描述

类型

Validation

AddressValidateRequest

Required Once

API = AddressValidateRequest

(group)

 

AddressValidateRequest / USERID

Required Once

 

NMTOKEN

 

AddressValidateRequest / PASSWORD

Required Once

 

String

 

AddressValidateRequest / APPID

Optional

 

String

 

AddressValidateRequest / Revision

需要

Integer value used to flag return of all response fields. When the tag is included in the request, the value must be set to a valid value. Set this value to 1 to return all currently documented response fields. 

String

minLength=0

pattern=\d{1}

pattern=  

AddressValidateRequest / Address /

需要

Up to 5 address verifications can be included per transaction.

(group)

 

AddressValidateRequest / Address / FirmName

Optional

 Firm Name

String

<FirmName>XYZ Corp.</FirmName>

AddressValidateRequest / Address / <Address1>

Optional

Delivery Address in the destination address.

String

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 / Address / <Address2>

Optional

Delivery Address in the destination address.

String

May contain secondary unit designator, such as APT or SUITE, for Accountable mail.)

AddressValidateRequest / Address / City

Optional

City name of the destination address.

String

Maximum characters allowed: 15

AddressValidateRequest / Address / State

Optional

Two-character state code of the destination address.

String

Maximum characters allowed: 2

AddressValidateRequest / Address / Urbanization

Optional

城市化

String

Maximum characters allowed: 28. For Puerto Rico addresses only.

AddressValidateRequest / Address / Zip5

Optional

Destination 5-digit ZIP Code.

String

Must be 5-digits. Numeric values (0-9) only. If International, all zeroes.

AddressValidateRequest / Address / Zip4

Optional

Destination ZIP+4

String

Numeric values (0-9) only. If International, all zeroes. Default to spaces if not available.

 

2.3.1.1 URL

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

2.3.1.2   XML Request Example

The  XML request should be in the following form and sequence:

https://production.shippingapis.com/ShippingApi.dll?API=Verify&XML=

<AddressValidateRequest USERID="XXXXX">

<Revision>1</Revision>

  <Address ID="0">

    <Address1></Address1>

    <Address2>29851 Aventura #k</Address2>

    <City></City>

    <State>CA</State>

    <Zip5>92688</Zip5>

    <Zip4></Zip4>

  </Address>

</AddressValidateRequest>

 

2.3.1.3   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 do not have 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 name is Verify.  The format of the XML transaction is:

https://servername/ShippingAPI.dll?API=Verify&XML=<AddressValidateRequest USERID="username">…….</AddressValidateRequest>

 

 

2.3.2     Response Parameters

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

After unpacking the XML response, you will have the output from your request—an XML response with the following tags:

 

Tag Name

Occurs

描述

类型

Validation

AddressValidateResponse / Address

需要

 

(group)

 

AddressValidateResponse / Address / FirmName

Optional

 

String

 

AddressValidateResponse / Address / Address1

Optional

 

String

 

AddressValidateResponse / Address / Address2

Optional

 

String

 

AddressValidateResponse / Address / City

Optional

City name of the destination address.

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

Must be 5-digits. Numeric values (0-9) only. If International, all zeroes.

AddressValidateResponse / Address / Zip4

Optional

Destination ZIP+4

String

Numeric values (0-9) only. If International, all zeroes. Default to spaces if not available.

AddressValidateResponse / Address / DeliveryPoint

Optional

 

String

 

AddressValidateResponse / Address / CarrierRoute

Optional

Carrier Route code.

String

Default is spaces.

Alphanumeric(5)

 

AddressValidateResponse / Address / Error

Optional

 

String

 

 

 

 

2.3.2.1 XML Response Example

The Address Standardization Web Tool returns the following information to the supplied address:

<AddressValidateResponse>

<Address ID="0">

<Address2>29851 AVENTURA STE K</Address2>

<City>RANCHO SANTA MARGARITA</City>

<CityAbbreviation>RCHO STA MARG</CityAbbreviation>

<State>CA</State>

<Zip5>92688</Zip5>

<Zip4>2014</Zip4>

<DeliveryPoint>83</DeliveryPoint>

<CarrierRoute>C###</CarrierRoute>

<Footnotes>N</Footnotes>

<DPVConfirmation>Y</DPVConfirmation>

<DPVCMRA>N</DPVCMRA>

<DPVFootnotes>AABB</DPVFootnotes>

<Business>Y</Business>

<CentralDeliveryPoint>N</CentralDeliveryPoint>

<Vacant>N</Vacant>

</Address>

</AddressValidateResponse>

 

If an error message is returned, refer to the Error Responses section for an explanation.

 

3.0 ZIP Code Lookup Web Tool

3.1    Overview

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.

3.1.1     API Signature

Scheme

Host

小道

API

XML

https://

secure.shippingapis.com

/ShippingAPI.dll?

API= ZipCodeLookup

&XML=(see below)

http://

production.shippingapis.com

/ShippingAPI.dll?

API= ZipCodeLookup

&XML=(see below)

3.1.2     Request Parameters

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.

Tag Name

Occurs

描述

类型

Validation

ZipCodeLookupRequest

需要

API = ZipCodeLookupRequest

(group)

 

ZipCodeLookupRequest / USERID

Required Once

 

NMTOKEN

 

ZipCodeLookupRequest / PASSWORD

Required Once

 

String

 

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.

String

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 / Address / Address2

Optional

Delivery Address in the destination address.

String

May contain secondary unit designator, such as APT or SUITE, for Accountable mail.)

ZipCodeLookupRequest / Address / City

Optional

City name of the destination address.

String

Field is required, unless a verified 11 digit DPV is provided for the mailpiece.

ZipCodeLookupRequest / Address / State

Optional

Two-character state code of the destination address.

String

Default is spaces for

International mail.

ZipCodeLookupRequest / Address / Urbanization

Optional

 

String

 

 

3.1.2.1   URL

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

3.1.2.2   Request Example

The XML request should be in the following form and sequence:

https://secure.shippingapis.com/shippingapi.dll?API=ZipCodeLookup&XML=<ZipCodeLookupRequest USERID="XXXX">

<Address ID="0">

<Address1></Address1>

<Address2>8 Wildwood Drive</Address2>

<City>Old Lyme</City>

<State>CT</State>

<Zip5>06371</Zip5>

<Zip4></Zip4>

</Address>

</ZipCodeLookupRequest>

 

3.1.2.3   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 do not have 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 name is ZipCodeLookup.  The format of the XML transaction is:

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

3.1.3     Response Parameters

Tag Name

Occurs

描述

类型

Validation

ZipCodeLookupResponse

需要

API = ZipCodeLookupResponse

(group)

 

ZipCodeLookupResponse / Address

 

 

(group)

 

ZipCodeLookupResponse / Address / FirmName

 

Up to 5 address verifications can be included per transaction.

String

Default is spaces.

ZipCodeLookupResponse / Address / Address1

 

Delivery Address in the destination address.

String

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

ZipCodeLookupResponse / Address / Address2

 

Delivery Address in the destination address.

String

May contain secondary unit designator, such as APT or SUITE, for Accountable mail.)

ZipCodeLookupResponse / Address / City

 

City name of the destination address.

String

Field is required, unless a verified 11 digit DPV is provided for the mailpiece.

ZipCodeLookupResponse / Address / State

Optional

Two-character state code of the destination address.

String

Default is spaces for

International mail.

ZipCodeLookupResponse / Address / Zip5

Optional

Destination 5-digit ZIP Code.

String

Must be 5-digits. Numeric values (0-9) only. If International, all zeroes.

ZipCodeLookupResponse / Address / Zip4

Optional

Destination ZIP+4

String

Numeric values (0-9) only. If International, all zeroes.

Default to spaces if not available.

ZipCodeLookupResponse / Address / Error

Optional

Two-character state code of the destination address.

String

 

 

3.1.3.1 XML Output Example

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

 

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

 

4.0 City/State Lookup Web Tool

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

4.1 Build the XML Request

 

4.1.1 API Signature

Scheme

Host

小道

API

XML

https://

secure.shippingapis.com

/ShippingAPI.dll?

API= CityStateLookup

&XML=(see below)

http://

production.shippingapis.com

/ShippingAPI.dll?

API= CityStateLookup

&XML=(see below)

4.1.2 Request Parameters

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.

 

 

Tag Name

Occurs

描述

类型

Validation

CityStateLookupRequest /

需要

API = CityStateLookupRequest

(group)

 

CityStateLookupRequest / USERID

需要

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

NMTOKEN

 

CityStateLookupRequest / PASSWORD

Optional

 

string

 

CityStateLookupRequest / APPID

Optional

 

NMTOKEN

 

CityStateLookupRequest / Revision

Optional

 

string

pattern=\d+\.\d+

CityStateLookupRequest / ZipCode

 

.Max 5 Zips

(Group)

 

CityStateLookupRequest / ZipCode / Zip5

Optional

 

string

 

CityStateLookupRequest / ZipCode / ID

Optional

 

string

 

 

4.1.2.1 URL

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

4.1.2.2 Request Example

The XML request should be in the following form and sequence:

https://secure.shippingapis.com/shippingapi.dll?API=CityStateLookup&XML=<CityStateLookupRequest USERID="XXXXXXX">

<ZipCode ID='0'>

<Zip5>20024</Zip5>

</ZipCode>

</CityStateLookupRequest>

 

4.1.2.3 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.

 

4.3 Response Parameters

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

 

4.3.1 XML Output from Unpacked Response

Tag Name

Occurs

描述

类型

Validation

CityStateLookupResponse /

需要

API =  CityStateLookupResponse

(Group)

 

CityStateLookupResponse / ZipCode

Optional

Max 5

(Group)

 

CityStateLookupResponse / ZipCode / Zip5

Optional

Five-digit ZIP. 

String

 

CityStateLookupResponse / City

Optional

 

String

 

CityStateLookupResponse / State

Optional

2 characters

String

 

CityStateLookupResponse / Error

Optional

 

String

 

 

 

 

 

 

 

 

 

 

 

 

 

After unpacking the XML response, you will have the output from your request—an XML response with the following tags:

 

4.3.2 Response Example

The City/State Lookup Web Tool returns the following information for the supplied address:

 

<CityStateLookupResponse>

<ZipCode ID="0">

<Zip5>90210</Zip5>

<City>比佛利山</City>

<State>CA</State>

<FinanceNumber></FinanceNumber>

<ClassificationCode></ClassificationCode>

</ZipCode>

<ZipCode ID="1">

<Zip5>20770</Zip5>

<City>GREENBELT</City>

<State>MD</State>

<FinanceNumber></FinanceNumber>

<ClassificationCode></ClassificationCode>

</ZipCode>

</CityStateLookupResponse>

Powered By OneLink