Address
Information

 

 

USPS Web Tools™

Application Programming Interface

User’s Guide

Document Version 3.2 (07/28/2013)

 

United States Postal Service Logo
 

 

 

 

 

 

 

 



To Our Customers

In registering for use of the USPS Web Tools™ (Web Tools), you received a user ID that will allow you to begin sending calls to the server when you are ready.  Any additional information or contact with you will occur as indicated on the registration form, please return to the eCommerce API Technical Guides site for the most recent documentation from any of the Web Tools.

If you require technical support, contact the USPS Internet Customer Care Center (ICCC).  This office is staffed as follows:

  • Monday through Friday from 8:00 a.m. to 8:30 p.m. Eastern Time 
  • Saturdays from 8:00 a.m. to 6:00 p.m. Eastern Time 
  • Sunday and Postal Holidays - Closed except for the following Holidays: Martin Luther King; President's Day; Columbus Day; & Veteran’s Day with hours from 9:00 a.m. to 6:00 p.m. ET.

 

E-mail address:  uspstechnicalsupport@mailps.custhelp.com

Telephone: 1-800-344-7779

 

USPS Customer Commitment

The United States Postal Service fully understands the importance of providing information and service anytime day or night to your Internet and e-commerce customers.  For that reason, the USPS is committed to providing 24 x 7 service from our Web Tools servers, 365 days a year.

 

 

Registered Trademarks

Priority Mail, Priority Mail Flat Rate, Priority Mail International, Priority Mail Regional Rate, Global Express Mail, Global Express Guaranteed, Global Priority Mail, Parcel Post, Parcel Select, First-Class Mail, USPS, USPS Web Tools, and ZIP + 4 are registered trademarks of the U.S. Postal Service.

Priority Mail Express, Priority Mail Express 1-Day, Priority Mail Express 2-Day, Priority Mail Express 3-Day, Priority Mail Express DPO, Priority Mail Express International, Priority Mail Express Intl, Priority Mail Express Military, Priority Mail Express Offshore, Priority Mail 1-Day, Priority Mail 2-Day, Priority Mail 3-Day, Priority Mail DPO, Priority Mail Intl, Priority Mail Military, Priority Mail Offshore, Signature Confirmation, Standard Post, USPS Tracking, ZIP, and ZIP Code are trademarks of the U.S. Postal Service.

Microsoft and Visual Basic are registered trademarks of Microsoft Corporation.

Adobe Acrobat and Adobe Reader are trademarks of Adobe Systems Incorporated.

DUNS is a registered trademark of Dun & Bradstreet.

ãCopyright 2013 United States Postal Service


 

 

Table of Contents

1.0       Introduction To Web Tools. 1

1.1           Implementation Overview.. 1

Step 1: Register. 2

Step 2: Test Your XML. 2

Step 3: Go Live with Your Web Tool 2

1.2           User ID Restrictions. 2

1.3           USPS Corporate Branding Guidelines. 3

1.3.1     Preferred Reference. 3

1.3.2     Alternative Reference. 4

1.3.3     Trademark Ownership and Use. 4

1.4           XML Overview.. 4

1.5           Error Responses. 4

1.6           Aviation Mail Security & Hazardous Materials. 5

1.7           Structure of this Guide. 6

2.0       Address Standardization Web Tool 7

2.1           Address Standardization Web Tool Transaction Procedures. 7

2.2           Run Scripted Test 7

Step 1: Build the XML Request 7

Step 2: Make the Internet Connection & Send the XML Request 8

Step 3: Unpack the XML Response. 8

2.3           Run Live Data. 9

Step 1: Build the XML Request 9

Step 2: Make the Internet Connection & Send the XML Request 11

Step 3: Unpack the XML Response. 11

3.0       ZIP Code Lookup Web Tool 13

3.1           ZIP Code Lookup Web Tool Transaction Procedures. 13

3.2           Run Scripted Test 13

Step 1: Build the XML Request 13

Step 2: Make the Internet Connection & Send the XML Request 14

Step 3: Unpack the XML Response. 14

3.3           Run Live Data. 15

Step 1: Build the XML Request 15

Step 2: Make the Internet Connection & Send the XML Request 16

Step 3: Unpack the XML Response. 17

4.0       City/State Lookup Web Tool 18

4.1           City/State Lookup Web Tool Transaction Procedures. 18

4.2           Run Scripted Test 18

Step 1: Build the XML Request 18

Step 2: Make the Internet Connection & Send the XML Request 19

Step 3: Unpack the XML Response. 19

4.3           Run Live Data. 20

Step 1: Build the XML Request 20

Step 2: Make the Internet Connection & Send the XML Request 21

Step 3: Unpack the XML Response. 21

 


1.0    Introduction To Web Tools

The USPS Web Tools allow developers of web-based and shrink-wrapped applications access to the on-line services of the United States Postal Service (USPS).  They provide easy access to shipping information and services for your customers.  Your customers can utilize the functions provided by the USPS without ever leaving your web site.  Once the Web Tools are integrated, your server communicates through the USPS Web Tools server over HTTP using XML (eXtensible Markup Language). 

Important:  Implementing these Web Tools requires experienced programmers who are familiar with Internet and web site development tools and techniques.

There is a Web Tools User’s Guide for each Web Tool listed on the USPS web site.  These user guides provide examples of the XML transactions to the USPS Web Tools server and guidance for installation.

1.1    Implementation Overview

As shown below, before you go live with any of the Address Information Web Tools, you must perform testing.  Following the diagram is a brief description of the steps illustrated.

Register online.
Users only have to register once at www.usps.com to download and install web tools.
Test your XML.
All web tools must be tested using the scripts provided in this guide.
Call the I C C C.
After successful testing, call the I C C C.
The I C C C sets you to production.
After the I C C C verifies your test results, it grants access to use live data.
Go live with your web tool.

To use the USPS Web Tools you must be a registered user.  Completing the registration process resulted in the receipt of your user ID and test server URL.

Stop Sign IconIf you have not registered, go to the Web Tools web site and follow the instructions to register for the Web Tools.

Step 2: Test Your XML

The next step is to test your Web Tools.  As a registered user you have been granted access to the test server.  An important note: The test server is set up to only accept the pre-defined XML transactions and return the pre-defined XML responses provided in this document.  For the testing phase, follow the instructions in the Run Scripted Test sections for each Web Tool.  After you have called the ICCC and they verified your successful test results you are ready to go live with your Web Tool.

Stop Sign IconAt this point, you have completed all testing and are now ready to send Live data and begin full service.  Follow the instructions provided in the Run Live Data sections for each Web Tool.

Note:  The United States Postal Service expressly prohibits the use of Web Tools "scripting" without prior approval.  Web Tools scripting can be defined as a technique to generate large volumes of Web Tools XML request transactions that are database- or batch-driven under program control, instead of being driven by individual user requests from a web site or a client software package.  The USPS reserves the right to suspend server access without notification by any offending party that does not have prior approval for Web Tools scripting.  Registered Web Tools customers that believe they have a legitimate requirement for Web Tools scripting should contact the ICCC to request approval.

1.2    User ID Restrictions

The user ID that you have received is for you or your company to use in accordance with the Terms and Conditions of Use to which you agreed during the registration process.  This user ID is not to be shared with others outside your organization, nor is it to be packaged, distributed, or sold to any other person or entity.  Please refer to the Terms and Conditions of Use Agreement for additional restrictions on the use of your user ID.

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 immediate loss of access to the USPS server and termination of the licenses granted under the Terms and Conditions of Use.

The documentation and sample code contained in the Web Tools User Guide series may be reused and/or distributed to your customers or affiliates to generate awareness, encourage Web Tool use, or provide ease-of-use.  It is your responsibility to ensure that your customers do not use your user ID for any purpose.  Direct your customers to the Web Tools web site to register, agree to the Terms and Conditions of Use agreement, and receive their own unique user ID.

Note to Software Distributors: The user ID restrictions discussed above are intended for online retailers that use the USPS Web Tools exclusively within their own web sites.  If you plan to distribute software with the USPS Web Tools embedded, contact the ICCC for guidelines.

For more information regarding the USPS Web Tools user ID policy, or for questions regarding the distribution of documentation, send e-mail to uspstechsupport@esecurecare.net.

1.3    USPS Corporate Branding Guidelines

The U.S. Postal Service requests to be referenced and acknowledged as the source of information for all U.S. Postal Service data that has been acquired through the Internet and/or from other sources.  However, this is not mandatory.  The following guidelines should be followed for those that want to authenticate and/or validate the data displayed from the U.S. Postal Service.

1.3.1        Preferred Reference

Use one of the following when the USPS is the only referenced source:

§  “Information provided by http://www.usps.com/.”

or

§  Use the official USPS corporate logo or USPS product-specific logos.

Digital copies of USPS corporate trademarks/logos are available through the U.S. Postal Service, Public Policy and Communications Department, Washington, D.C.  You can request the USPS corporate logo and/or product-specific logos by e-mailing ilogo@email.usps.gov.  Requests will be responded to by e-mail within 10 days.  We will review your web site, and if appropriate, provide the logo for usage in accordance with the guidelines and the license grant contained in the Terms and Conditions of Use for Internet Shipping Application Program Interfaces (Web Tools).  If your web page is not available over the Internet, please provide a screen shot of the page where the logo will reside.

When requesting logo(s) you must provide the following information:

§  Company name.

§  URL and page where logo will reside.

§  Type of business.

§  How and where the logo will be used.

§  Contact name.

§  Telephone number.

§  E-mail address.

§  Desired graphic format, e.g., GIF, TIF, JPEG, etc.

§  Logo desired:

____USPS Corporate Eagle logo

____Priority Mail

____Express Mail

____Other (describe)

1.3.2        Alternative Reference

Use one of the following when the USPS is listed with other shipping carriers or web sites:

§  United States Postal Service.

§  U.S. Postal Service.

§  U.S.P.S. (use period after each initial).

The above alternatives are listed in the order of United States Postal Service preference.

1.3.3        Trademark Ownership and Use

The USPS trademarks listed in the front of this guide and any logos requested from USPS Public Policy and Communications Department should not be altered or abbreviated.

USPS trademarks are trademarks owned solely and exclusively by USPS and may be used only in the form and manner, and with appropriate legends prescribed by USPS.  All advertising and other uses of USPS trademarks must include a legend indicating that USPS trademarks are the property of USPS and that they are being used under license from USPS, together with any other legends or marking that may be required by law.  Nothing contained in this document shall be deemed to convey any title or ownership interest to any user except for the nonexclusive rights granted under the Terms and Conditions of Use for Internet Shipping Application Program Interfaces and this document.

1.4    XML Overview

XML uses a hierarchical (tree) element structure.  Each element consists of a start tag of the form <Name>, and an end tag of the form </Name>, between which can be data and other elements.  <Name/> is shorthand for <Name></Name>, an element with no data.  Attributes such as user ID can be included in the start tag.  All data and attribute values in this document are for illustration purposes and are to be replaced by the actual values.  Developers must use the order and case for tag names of the sample code contained in this document.  The tabs and carriage returns in the XML structures are for readability only; there is no need for white space in the actual code.

For more information about XML, browse the W3C web site and the XML.com web site

1.5    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.  For example: 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.

1.6    Aviation Mail Security & Hazardous Materials

The Aviation Mail Security and Hazardous Materials Programs represent the U.S. Postal Service’s commitment to provide a safe environment for our customers, employees, and the traveling public.

The U.S. Postal Service has taken a proactive role in the areas of aviation mail security and hazardous materials acceptance, handling, and transport for many years.  Training has been provided to our employees, supervisors, and managers.  Each year these programs are modified to meet increased challenges through improved technology.  Our multi-phased programs are in effect 365 days a year, 24 hours a day.  The particulars of our programs are withheld for security reasons.  However, complying with the following restrictions will assist us in securing a safe mailing environment for all of us:

§         Priority Mail envelopes or packages weighing 13 ounces or over with adhesive postage stamps cannot be deposited at unattended receptacles such as collection boxes and lobby drops.  These mail pieces must be taken to your nearest USPS retail unit or may be given to your carrier if you are a known customer to him/her and have included your return address.  Refer to Domestic Mail Manual, Deposit for Priority Mail.

§         International Mail envelopes or packages weighing 13 ounces or over with adhesive postage stamps or customer applied postage meter strips cannot be deposited at unattended mail receptacles such as collection boxes and lobby drops.  These mail pieces must be taken to your nearest USPS retail unit or may be given to your carrier if you are a known customer and have included your return address along with a completed, signed, and dated PS Form 2976 or 2976-A.  Refer to International Mail Manual.

1.7    Structure of this Guide

This document provides guidance and step-by-step instructions for installing the Address Information Web Tools and fulfilling various administrative requirements.  There are three separate Web Tools that can be implemented, depending on your needs:

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

Each Web Tool is described in its own section.  The steps must be followed in the order presented for each Web Tool.

 


2.0    Address Standardization Web Tool

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

2.2    Run Scripted Test

For testing purposes, the only value in the test code in this section that you should change is the user ID.  Enter the user ID you received in the registration e-mail for testing.  All remaining code in the test scripts provided below must remain unchanged.

Testing URL

To make test calls to the Address Standardization server, access is required to a server.  Use the Testing URL provided in the registration e-mail.

Scripted Test Requests

There are two test requests included in this procedure.  All of the test script code contained in this document can be cut and pasted for your use in testing the software.  Be sure to note the request numbers so you can match up the responses you will receive as provided in the Successful Test Responses section.

Test Request #1

http://SERVERNAME/ShippingAPITest.dll?API=Verify&XML=<AddressValidateRequest%20USERID="xxxxxxx"><Address ID="0"><Address1></Address1>

<Address2>6406 Ivy Lane</Address2><City>Greenbelt</City><State>MD</State>

<Zip5></Zip5><Zip4></Zip4></Address></AddressValidateRequest>

Test Request #2

http://SERVERNAME/ShippingAPITest.dll?API=Verify&XML=<AddressValidateRequest%20USERID="xxxxxxx"><Address ID="1"><Address1></Address1>

<Address2>8 Wildwood Drive</Address2><City>Old Lyme</City><State>

CT</State><Zip5>06371</Zip5><Zip4></Zip4></Address></AddressValidateRequest>

This step involves four separate functions:

  1. Making the connection to the USPS Shipping Web Tools server.
  2. Sending the request (whether Visual Basic, 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:

http://servername/ShippingAPITest.dll?API=Verify&XML=<AddressValidateRequest USERID="xxxxxxx">…….</AddressValidateRequest>

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

Successful Test Responses

For your test to be successful, the following responses should be returned verbatim.


Response to Test Request #1

<?xml version="1.0"?>

<AddressValidateResponse>

<Address ID="0">

<Address2>6406 IVY LN</Address2>

<City>GREENBELT</City>

<State>MD</State>

<Zip5>20770</Zip5>

<Zip4>1441</Zip4>

</Address>

</AddressValidateResponse>

Response to Test Request #2

<?xml version="1.0"?>

<AddressValidateResponse>

<Address ID="1">

<Address2>8 WILDWOOD DR</Address2>

<City>OLD LYME</City>

<State>CT</State>

<Zip5>06371</Zip5>

<Zip4>1844</Zip4>

</Address>

</AddressValidateResponse>

Scripted Test Error Responses

If any values were changed in your request, an error can occur.  Although the input may be valid, the response will still raise an error, because those particular values have not been included in this test server.  Refer to the Error Responses section for an explanation of returned errors.

Upon successful completion of the test phase, call the ICCC.  The ICCC will verify your test results and provide you with privileges necessary to proceed to the next step—running Live data.

2.3    Run Live Data

Live XML Tags

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.

XML Tag

Required/Optional

Description & Values Allowed

<AddressValidateRequest

Required

Input tag exactly as presented.

…USERID=”userid”>

Required

Use user ID provided with registration.

<ReturnCarrierRoute>

Optional Tag/

Optional Value

Flag to return Carrier Route – true/false

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

Tags within the above defined call are as follows:

XML Tag

Required/

Optional

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>

<FirmName>

Required Tag/

Optional Value

Maximum characters allowed: 38

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

<Address1>

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>

<Address2>

Required Tag/

Required Value

Street address.

Maximum characters allowed: 38

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

<City>

Required Tag/

Optional Value

(see box at right)

Maximum characters allowed: 15.  Either <City> and <State> or <Zip5> are required.

For example: <City>Greenbelt</City>

<State>

Required Tag/

Optional Value

(see box at right)

Maximum characters allowed: 2. Either <City> and <State> or <Zip5> are required.

For example: <State>MD</State>

<Urbanization>

Optional Tag/

Optional Value

(see box at right)

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

For example: <Urbanization></Urbanization>

<Zip5>

Required Tag/

Optional Value

(see box at right)

Input tag exactly as presented, not all caps.  Maximum characters allowed: 5. Either <City> and <State> or <Zip5> are required.

For example:  <Zip5></Zip5>

<Zip4>

Required Tag/

Optional Value

Input tag exactly as presented, not all caps.  Maximum characters allowed: 4

For example: <Zip4></Zip4>

Live URL

To gain access all users, including those registered for previous Web Tools use, must contact the ICCC for the URL to send Sample requests.  The ICCC will send the URL via e-mail.

Live XML Request Example

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

<AddressValidateRequest USERID="xxxxxxx">

<Address ID="0">

      <FirmName>XYZ Corp.</FirmName>

<Address1></Address1>

<Address2>6406 Ivy </Address2>

<City>Greenbelt</City>

<State>MD</State>

<Zip5></Zip5>

<Zip4></Zip4>

</Address>

</AddressValidateRequest>

This step involves four separate functions:

  1. Making the connection to the USPS Shipping Web Tools server.
  2. Sending the request (whether Visual Basic, 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>

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

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

Output

XML Tag

Type of Response

<AddressValidateResponse>

Address Verification Number

<Address ID='#'>

Name of Firm

<FirmName>

Address Line 1

<Address1>

Address Line 2

<Address2>

City

<City>

State

<State>

Urbanization

<Urbanization>

ZIP Code

<Zip5>

ZIP Code + 4

<Zip4>

Carrier Route

<CarrierRoute>

Message when multiple addresses found*

<ReturnText>

*This output is only returned when the address entered results in multiple locations being found by the Shipping API server, but a default address exists.  The text of the message will read: “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.”


Live XML Response

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

<AddressValidateResponse>

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

</AddressValidateResponse>

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

 


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

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

City/State Lookup Web Tool Server
Laptop computer icon. Inputs via XML request are zip code I D # (up to 5)  and zip code.
Server icon.  Server tasks are gets data from address management system, gets city and state and builds XML response.
Laptop computer icon.  Outputs via XML response are zip code, city and state.

3.2    Run Scripted Test

For testing purposes, the only values in the test code in this section that you should change are the user ID.  Enter the user ID you received in the registration e-mail for testing.  All remaining code in the test scripts provided below must remain unchanged.

Testing URL

To make test calls to the ZIP Code Lookup server, access is required to a server.  Use the Testing URL provided in the registration e-mail.

Scripted Test Requests

There are two test requests included in this procedure.  All of the test script code contained in this document can be cut and pasted for your use in testing the software.  Be sure to note the request numbers so you can match up the responses you will receive as provided in the Successful Test Responses section.

Test Request #1

http://SERVERNAME/ShippingAPITest.dll?API=ZipCodeLookup&XML=<ZipCodeLookupRequest%20USERID="xxxxxxx"><Address ID="0"><Address1></Address1>

<Address2>6406 Ivy Lane</Address2><City>Greenbelt</City><State>

MD</State></Address></ZipCodeLookupRequest>

Test Request #2

http://SERVERNAME/ShippingAPITest.dll?API= ZipCodeLookup&XML=<ZipCodeLookupRequest%20USERID="xxxxxxx">

<Address ID="1"><Address1></Address1>

<Address2>8 Wildwood Drive</Address2><City>Old Lyme</City><State>CT</State>

<Zip5>06371</Zip5><Zip4></Zip4></Address></ZipCodeLookupRequest>

This step involves four separate functions:

1.      Making the connection to the USPS Shipping Web Tools server.

2.      Sending the request (whether Visual Basic, 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:

http://servername/ShippingAPITest.dll?API= ZipCodeLookup&XML=<ZipCodeLookupRequest USERID="username">…….</ZipCodeLookupRequest>

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

Successful Test Response

For your test to be successful, the following responses should be returned verbatim.


Response to Test Request #1

<?xml version="1.0"?>

<ZipCodeLookupResponse>

<Address ID="0">

<Address2>6406 IVY LN</Address2>

<City>GREENBELT</City>

<State>MD</State>

<Zip5>20770</Zip5>

<Zip4>1441</Zip4>

</Address>

</ZipCodeLookupResponse>

Response to Test Request #2

<?xml version="1.0"?>

<ZipCodeLookupResponse>

<Address ID="1">

<Address2>8 WILDWOOD DR</Address2>

<City>OLD LYME</City>

<State>CT</State>

<Zip5>06371</Zip5>

<Zip4>1844</Zip4>

</Address>

</ZipCodeLookupResponse>

Scripted Test Error Responses

If any values were changed in your request, an error can occur.  Although the input may be valid, the response will still raise an error, because those particular values have not been included in this test server.  Refer to the Error Responses section for an explanation of returned errors.

Upon successful completion of the test phase, call the ICCC.  The ICCC will verify your test results and provide you with privileges necessary to proceed to the next step—running Live data.

3.3    Run Live Data

Live XML Tags

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.

XML Tag

Required/Optional

Description & Values Allowed

<ZipCodeLookupRequest

Required

Input tag exactly as presented.

…USERID=”userid”>

Required

Use user ID provided with registration.

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

Tags within the above defined call are as follows:

 

XML Tag

Required/

Optional

 

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>

<FirmName>

Required Tag/

Optional Value

Maximum characters allowed: 38

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

<Address1>

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>

<Address2>

Required Tag/

Required Value

Street address.

Maximum characters allowed: 38

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

<City>

Required Tag/

Required Value

Maximum characters allowed: 15

For example: <City>Greenbelt</City>

<State>

Required Tag/

Required Value

Maximum characters allowed: 2

For example: <State>MD</State>

Live URL

To gain access, all users, including those registered for previous Web Tools use, must contact the ICCC for the URL to make Live calls.  The ICCC will send the Live URL via e-mail.

Live XML Request Example

The Live XML request should be in the following form:

<ZipCodeLookupRequest USERID=”xxxxxxxx>

<Address ID='0'>

<FirmName>XYZ Corp.</FirmName>

<Address1></Address1>

<Address2>6406 Ivy</Address2>

<City>Greenbelt</City>

<State>MD</State>

</Address>

<Address ID='1'>

<FirmName>ABC Company</FirmName>

<Address1>Apt/Suite 2</Address1>

<Address2>435 S Main Street</Address2>

<City>Los Angeles</City>

<State>CA</State>

</Address>

</ZipCodeLookupRequest>

This step involves four separate functions:

  1. Making the connection to the USPS Shipping Web Tools server.
  2. Sending the request (whether Visual Basic, 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:

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

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

Output

XML Tag

Type of Response

<ZipCodeLookupResponse>

Address ID Number

<Address ID='#'>

Name of Firm

<FirmName>

Address Line 1

<Address1>

Address Line 2

<Address2>

City

<City>

State

<State>

ZIP Code

<Zip5>

ZIP Code + 4

<Zip4>

Live XML Output Example

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

<?xml version="1.0" ?>

<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    City/State Lookup Web Tool Transaction Procedures

The illustration below shows the transactional flow of information to and from the USPS City/State Lookup Web Tools server:

City/State Lookup Web Tool Server
Laptop computer icon. Inputs via XML request are zip code I D # (up to 5)  and zip code.
Server icon.  Server tasks are gets data from address management system, gets city and state and builds XML response.
Laptop computer icon.  Outputs via XML response are zip code, city and state.

4.2    Run Scripted Test

For testing purposes, the only value in the test code in this section that you should change is the user ID.  Enter the user ID you received in the registration e-mail for testing.  All remaining code in the test scripts provided below must remain unchanged.

Testing URL

To make test calls to the City/State Lookup server, access is required to a server.  Use the Testing URL provided in the registration e-mail.

Scripted Test Requests

There are two test requests included in this procedure.  All of the test script code contained in this document can be cut and pasted for your use in testing the software.  Be sure to note the request numbers so you can match up the responses you will receive as provided in the Successful Test Responses section.

Test Request #1

http://SERVERNAME/ShippingAPITest.dll?API=CityStateLookup&XML=<CityStateLookupRequest%20USERID="xxxxxxx"><ZipCode ID= "0">

<Zip5>90210</Zip5></ZipCode></CityStateLookupRequest>

Test Request #2

http://SERVERNAME/ShippingAPITest.dll?API=CityStateLookup&XML=<CityStateLookupRequest%20USERID="xxxxxxx"><ZipCode ID= "0">

<Zip5>20770</Zip5></ZipCode></CityStateLookupRequest>

This step involves four separate functions:

1.   Making the connection to the USPS Shipping Web Tools server.

2.   Sending the request (whether Visual Basic, 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 CityStateLookup.  The format of the XML transaction is:

http://servername/ShippingAPITest.dll?API=CityStateLookup&XML=<CityStateLookupRequest USERID="username">…….</CityStateLookupRequest>

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

Successful Test Responses

For your test to be successful, the following responses to Test Requests should be returned verbatim.

Response to Test Request #1

<?xml version="1.0"?>

<CityStateLookupResponse>

<ZipCode ID="0">

<Zip5>90210</Zip5>

<City>BEVERLY HILLS</City>

<State>CA</State>

</ZipCode>

</CityStateLookupResponse>


Response to Test Request #2

<?xml version="1.0"?>

<CityStateLookupResponse>

<ZipCode ID="0">

<Zip5>20770</Zip5>

<City>GREENBELT</City>

<State>MD</State>

</ZipCode>

</CityStateLookupResponse>

Scripted Test Error Responses

If any values were changed in your request, an error can occur.  Although the input may be valid, the response will still raise an error, because those particular values have not been included in this test server.  Refer to the Error Responses section for an explanation of returned errors.

Upon successful completion of the test phase, call the ICCC.  The ICCC will verify your test results and provide you with privileges necessary to proceed to the next step—running Live data.

4.3    Run Live Data

Live XML Tags

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.

XML Tag

Required/Optional

Description & Values Allowed

<CityStateLookupRequest

Required

Input tag exactly as presented.

…USERID=”userid”>

Required

Use user ID provided with registration.

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

Tags within the above defined call are as follows:

 

XML Tag

Required/

Optional

 

Description & Values Allowed

<ZipCode ID='#'>

Required Tag/

Required Value

Up to five ZIP Codes can be included per transaction.

For example: <ZipCode ID="0"></ZipCode ID>

<Zip5>

Required Tag/

Required Value

Input tag exactly as presented, not all caps.  Maximum characters allowed: 5

For example:  <Zip5>90210</Zip5>

Live URL

To gain access, all users, including those registered for previous Web Tools use, must contact the ICCC for the URL to make Live calls.  The ICCC will send the Live URL via e-mail.

Live XML Request Example

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

<CityStateLookupRequest USERID=”xxxxxxxx>

<ZipCode ID="0">

<Zip5>90210</Zip5>

</ZipCode>

<ZipCode ID="1">

<Zip5>20770</Zip5>

</ZipCode>

</CityStateLookupRequest>

This step involves four separate functions:

1.   Making the connection to the USPS Shipping Web Tools server.

2.   Sending the request (whether Visual Basic, 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 CityStateLookup.  The format of the XML transaction is:

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

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

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

 

Output

XML Tag

Type of Response

<CityStateLookupResponse

ZIP Code Lookup Number

<ZipCode ID='#'>

ZIP Code of City or State

<Zip5>

City for Requested ZIP Code

<City>

State for requested ZIP Code

<State>

Live XML Response

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

<CityStateLookupResponse>

<ZipCode ID="0">

<Zip5>90210</Zip5>

<City>BEVERLY HILLS</City>

<State>CA</State>

</ZipCode>

<ZipCode ID="1">

<Zip5>20770</Zip5>

<City>GREENBELT</City>

<State>MD</State>

</ZipCode>

</CityStateLookupResponse>