Address
Information
USPS Web Tools™
Application Programming Interface
User's Guide
Document Version 2.2-a (03/31/2006)
 |
Address
Information
USPS Web Tools™
Application Programming Interface
User's Guide
Document Version 2.2-a (03/31/2006)
|
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 Web Tools documentation website 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 manned from 7:00 AM to 11:00 PM EST daily.
E-mail address: icustomercare@usps.com
Telephone: 1-800-344-7779 (7:00 AM to 11:00 PM EST daily)
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.
Trademarks
Express Mail, First-Class Mail, Global Express Mail, GXG, Global Priority Mail, Parcel Post, Parcel Select, Priority Mail, USPS, and ZIP + 4 are registered trademarks of the U.S. Postal Service.
Delivery Confirmation, Global Express Guaranteed, International Parcel Post, Priority Mail Global Guaranteed, Signature Confirmation, USPS Web Tools, and ZIP Code are trademarks of the U.S. Postal Service.
Microsoft and Visual Basic are registered trademarks of Microsoft Corporation.
Adobe Acrobat is a trademark of Adobe Systems Incorporated.
ãCopyright 2005 United States Postal Service
Table of Contents
1.0 Introduction To Web Tools. 1
1.1 Implementation Overview.. 1
Step 3: Go Live with Your Web Tool 2
1.3 USPS Corporate Branding Guidelines. 3
1.3.2 Alternative Reference. 4
1.3.3 Trademark Ownership and Use. 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
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
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
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
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 19
4.1 City/State Lookup Web Tool Transaction Procedures. 19
Step 1: Build the XML Request 19
Step 2: Make the Internet Connection & Send the XML Request 20
Step 3: Unpack the XML Response. 20
Step 1: Build the XML Request 21
Step 2: Make the Internet Connection & Send the XML Request 22
Step 3: Unpack the XML Response. 22
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.
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.
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.
If 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.
Step 3: Go Live with Your Web Tool
At 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.
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 icustomercare@usps.com.
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.
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)
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.
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.
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
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.
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. Over 200,000 hours of training has been provided to our employees, supervisors, and managers in the last year alone. 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 us all:
§ Priority Mail envelopes or packages weighing 16 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 section 100.2, Restrictions.
§ International Mail envelopes or packages weighing 16 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 section 123.5.
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.
The illustration below shows the transactional flow of information to and from the USPS Address Standardization Web Tool server:
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.
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.
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.
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>
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>
There are several ways to make the Internet connection and send the XML request. Please contact the ICCC for code examples.
When the USPS Shipping Web Tools returns a response, it will either return a successful response document or an error document. If you need software to unpack the response, contact the ICCC for sample code you can use.
For your test to be successful, the following responses should be returned verbatim.
<?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>
<?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>
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.
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. |
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> |
|
<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> |
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.
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>
Contact the ICCC for a code example of building 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 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/ShippingAPI.dll?API=Verify&XML=<AddressValidateRequest USERID="username">…….</AddressValidateRequest>
There are several ways to make the Internet connection and send the XML request. Please contact the ICCC for code examples.
When the USPS Shipping Web Tools returns a response, it will either return a successful response document or an error document. If you need software to unpack the response, contact the ICCC for sample code you can use.
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> |
|
ZIP Code |
<Zip5> |
|
ZIP Code + 4 |
<Zip4> |
|
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."
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.
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.
The illustration below shows the transactional flow of information to and from the USPS ZIP Code Lookup Web Tool server:
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.
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.
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.
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>
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>
There are several ways to make the Internet connection and send the XML request. Please contact the ICCC for code examples.
When the USPS Shipping Web Tools returns a response, it will either return a successful response document or an error document. If you need software to unpack the response, contact the ICCC for sample code you can use.
For your test to be successful, the following responses should be returned verbatim.
<?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>
<?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>
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.
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> |
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.
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>
Contact the ICCC for a code example of building 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 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>
There are several ways to make the Internet connection and send the XML request. Please contact the ICCC for code examples.
When the USPS Shipping Web Tools returns a response, it will either return a successful response document or an error document. If you need software to unpack the response, contact the ICCC for sample code you can use.
|
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> |
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.
The illustration below shows the transactional flow of information to and from the USPS City/State Lookup Web Tools server:
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.
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.
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.
http://SERVERNAME/ShippingAPITest.dll?API=CityStateLookup&XML= <CityStateLookupRequest%20USERID="xxxxxxx"><ZipCode ID= "0">
<Zip5>90210</Zip5></ZipCode></CityStateLookupRequest>
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>
There are several ways to make the Internet connection and send the XML request. Please contact the ICCC for code examples.
When the USPS Shipping Web Tools returns a response, it will either return a successful response document or an error document. If you need software to unpack the response, contact the ICCC for sample code you can use.
For your test to be successful, the following responses to Test Requests should be returned verbatim.
<?xml version="1.0"?>
<CityStateLookupResponse>
<ZipCode ID="0">
<Zip5>90210</Zip5>
<City>BEVERLY HILLS</City>
<State>CA</State>
</ZipCode>
</CityStateLookupResponse>
<?xml version="1.0"?>
<CityStateLookupResponse>
<ZipCode ID="0">
<Zip5>20770</Zip5>
<City>GREENBELT</City>
<State>MD</State>
</ZipCode>
</CityStateLookupResponse>
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.
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> |
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.
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>
Contact the ICCC for a code example of building 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 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/ShippingAPI.dll?API=CityStateLookup&XML=<CityStateLookupRequest USERID="username">…….</CityStateLookupRequest>
There are several ways to make the Internet connection and send the XML request. Please contact the ICCC for code examples.
When the USPS Shipping Web Tools returns a response, it will either return a successful response document or an error document. If you need software to unpack the response, contact the ICCC for sample code you can use.
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> |
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>
