Domestic Mail
Service
Standards

 

 

USPS Web Tools™

Application Programming Interface

User’s Guide

Document Version 2.0 (01/26/2014)

 

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.

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 2014 United States Postal Service


Table of Contents

1.0       Domestic Mail Service Standards Overview.. 3

1.1           Aviation Mail Security & Hazardous Materials. 4

2.0       Priority Mail Service Standards Web Tool 5

2.1           Priority Mail Service Standards Web Tool Transaction Procedures. 5

2.2           Priority Mail Service Standards Request 5

Step 1: Build the XML Request 5

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

Step 3: Unpack the XML Response. 7

3.0       Package Services Service Standards Web Tool 8

3.1           Package Services Service Standards Web Tool Transaction Procedures. 8

3.2           Run Live Data. 8

Step 1: Build the XML Request 8

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

Step 3: Unpack the XML Response. 10

4.0       First Class Mail Service Standards Web Tool 11

4.1           The First Class Mail Service Standards Web Tool Transaction Procedures. 11

4.2           Run Live Data. 11

Step 1: Build the XML Request 11

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

Step 3: Unpack the XML Response. 13

5.0       Express Mail Service Commitments Web Tool 14

5.1           Run Live Data. 14

Step 1: Build the XML Request 14

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

Step 3: Unpack the XML Response. 16

 


1.0    Domestic Mail Service Standards Overview

The Domestic Mail Service Standards Web Tools provide information as to the delivery times for three separate services:  Priority Mail, Package Services (including the four types: Standard Post, Bound Printed Matter, Library Mail, and Media Mail), First Class Mail and Express Mail Service.  For Priority Mail, Package Services, and First Class Mail the applicable Web Tool calculates the average number of days it will take for a package to arrive at a destination ZIP code from its origination ZIP code.  The Express Mail Service Web Tool provides an exact delivery date for that service.  The functions and standards of each are as follows:

§  The Priority Mail Service Standards Web Tool receives requests and returns the number of days (on average) it will take a Priority Mail package to arrive at its destination.  This Web Tool processes a single request.  Note these are service standards and not guaranteed commitments.

Priority Mail Service Standard

Commitment?

1-3 days per package (refer to A Customer's Guide to Mailing for specifications).  Also refer to the USPS Priority Mail web page.

Not a guaranteed commitment

§  The Package Services Service Standards Web Tool receives requests and returns the average number of days it will take a package (Standard Post, Bound Printed Matter, Library Mail, or Media Mail) to arrive at its destination.  This Web Tool processes a single request.  Note these are service standards and not guaranteed commitments.

Standard Post Service Standard

Commitment?

2-9 days per package (refer to A Customer's Guide to Mailing for specifications).  Also refer to the USPS Standard Post web page.

Not a guaranteed commitment

Bound Printed Matter Service Standard

Commitment?

2-9 days per package (refer to A Customer's Guide to Mailing for specifications).  Also refer to the USPS Bound Printed Matter web page.

Not a guaranteed commitment

Library Mail Service Standard

Commitment?

2-9 days per package (refer to A Customer's Guide to Mailing for specifications). 

Not a guaranteed commitment

Media Mail Service Standard

Commitment?

2-9 days per package (refer to A Customer's Guide to Mailing for specifications).  Also refer to the USPS Media Mail web page.

Not a guaranteed commitment

§  The First Class Mail Service Standards Web Tool receives requests and returns the number of days (on average) it will take a First Class Mail package to arrive at its destination.  This Web Tool processes a single request.  Note these are service standards and not guaranteed commitments.

First Class Mail Service Standard

Commitment?

1-3 days per package (refer to A Customer's Guide to Mailing for specifications).  Also refer to the USPS First Class Mail web page.

Not a guaranteed commitment

§  The Express Mail Service Commitments Web Tool provides delivery commitments for Express Mail packages.  A user provides an origination and a destination ZIP Code and an optional current or future date that the package will be shipped.  The Web Tool returns all the Express Mail Service Commitments for the given locations to include package drop-off information.

Express Mail Service Standard

Commitment?

1-2 days per package (refer to A Customer's Guide to Mailing for specifications).  Also refer to the USPS Express Mail Service web page.

Guaranteed

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

 


2.0    Priority Mail Service Standards Web Tool

The Priority Mail Service Standards Web Tool receives requests and returns the number of days (on average) it will take a Priority Mail package to arrive at its destination.  Ensure that end-users understand that these are service standards and not guaranteed commitments.  The Priority Mail Service Standards Web Tool processes a single request.

2.1    Priority Mail Service Standards Web Tool Transaction Procedures

The illustration below shows the transactional flow of information to and from the USPS Priority Mail Service Standards Web Tool server:

Priority Mail Service Standards Web Tool Server
Laptop computer icon. Inputs via XML request are Origin zip code and destination zip code.
Server icon.  Server tasks are gets standards and builds XML response.
Laptop computer icon.  Outputs via XML response are origin zip code, destination zip code and days.

2.2    Priority Mail Service Standards Request

Step 1: Build the XML Request

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

<PriorityMailRequest

Required

Input tag exactly as presented.

…USERID=”userid”>

Required

Use user ID provided with registration.

e.g., <PriorityMailRequest UserID=”yourID”>

Tags within the above defined call are as follows:

XML Tag

Required/

Optional

Description & Values Allowed

<OriginZip>

Required Tag/

Required Value

Origination and destination ZIP Codes must be valid.  Only the first 3 digits of the Zip Code are entered between the open tag and close tag.  If a 4- or 5-digit ZIP Code is entered, the last 1 or 2 digits will be ignored.

For example: <OriginZip>902</OriginZip>

<DestinationZip>

Required Tag/

Required Value

Origination and destination ZIP Codes must be valid.  Only the first 3 digits of the Zip Code are entered between the open tag and close tag.  If a 4- or 5-digit ZIP Code is entered, the last 1 or 2 digits will be ignored.

For example:

<DestinationZip>211</DestinationZip>

<DestinationType>

Optional Tag/

Optional Value

Destination Type for package.  Valid values are:

 

“1” = PO-Addressee – Street (Default Value)

“2” = PO-Addressee – PO Box

“3” = Hold For Pick-up

 

For example:

<DestinationType>1</DestinationType>

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:

<OriginZip>902</OriginZip>

In this instance, you will replace “902” with the first 3 digits of the origin ZIP Code.

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:

<PriorityMailRequest USERID=”xxxxxxxx>

     <OriginZip>902</OriginZip>

     <DestinationZip>211</DestinationZip>

</PriorityMailRequest>

Step 2: 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 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 PriorityMail.  The format of the XML transaction is:

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

Step 3: Unpack the XML Response

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

Response Type

<PriorityMailResponse>

Origination ZIP Code

<OriginZip>

Destination ZIP Code

<DestinationZip>

Average time for delivery

<Days>

Service Standards Messaging (optional – appears only when applicable)

<Message>

Effective Acceptance Date - returned only when <DestinationType> specified

<EffectiveAcceptanceDate>

Scheduled Delivery Date - returned only when <DestinationType> specified

<ScheduledDeliveryDate>

Live XML Response

The Priority Mail Service Standards Web Tool returns the following information if pickup is available to the supplied ZIP Code:

<PriorityMailResponse>

<OriginZip>902</OriginZip>

<DestinationZip>211</DestinationZip>

<Days>2</Days>

</PriorityMailResponse>

 

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


3.0    Package Services Service Standards Web Tool

The Package Services Service Standards Web Tool receives requests and returns the average number of days it will take a package to arrive at its destination.  There are four types of Package Services: Standard Post, Bound Printed Matter, Library Mail, and Media Mail.  The Package Services Service Standards Web Tool processes a single request.  Ensure that end-users understand that these are service standards and not guaranteed commitments.

3.1    Package Services Service Standards Web Tool Transaction Procedures

The illustration below shows the transactional flow of information to and from the USPS Package Services Service Standards Web Tool server:

Package Services Service Standards Web Tool Server
Laptop computer icon. Inputs via XML request are origin zip code and destination zip code.
Server icon.  Server tasks are gets standards and builds XML response.
Laptop computer icon.  Outputs via XML response are sorigin zip code, destination zip code and days.

3.2    Run Live Data

Step 1: Build the XML Request

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

<StandardBRequest

Required

Input tag exactly as presented.

…USERID=”userid”>

Required

Use user ID provided with registration.

 

e.g., <StandardBRequest USERID=”xxxxxxxx” >

 

Tags within the above defined call are as follows:

XML Tag

Required/

Optional

Description & Values Allowed

<OriginZip>

Required Tag/

Required Value

Origination and destination ZIP Codes must be valid.  Only the first 3 digits of the Zip Code are entered between the open tag and close tag.  If a 4- or 5-digit ZIP Code is entered, the last 1 or 2 digits will be ignored.

For example: <OriginZip>902</OriginZip>

<DestinationZip>

Required Tag/

Required Value

Origination and destination ZIP Codes must be valid.  Only the first 3 digits of the Zip Code are entered between the open tag and close tag.  If a 4- or 5-digit ZIP Code is entered, the last 1 or 2 digits will be ignored.

For example: <DestinationZip>211</DestinationZip>

<DestinationType>

Optional Tag/

Optional Value

Destination Type for package.  Valid values are:

 

“1” = PO-Addressee – Street (Default Value)

“2” = PO-Addressee - PO Box

“3” = Hold For Pick-up

 

For example: <DestinationType>1</DestinationType>

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:

<OriginZip>902</OriginZip>

In this instance, you will replace “902” with the first 3 digits of the origin ZIP Code.

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:

<StandardBRequest USERID=”xxxxxxxx>

     <OriginZip>902</OriginZip>

     <DestinationZip>211</DestinationZip>

</StandardBRequest>

Step 2: 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 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 StandardB.  The format of the XML transaction is:

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

Step 3: Unpack the XML Response

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

Response Type

<StandardBResponse>

Origination ZIP Code

<OriginZip>

Destination ZIP Code

<DestinationZip>

Average time for delivery

<Days>

Service Standards Messaging (optional – appears only when applicable)

<Message>

Effective Acceptance Date - returned only when <DestinationType> specified

<EffectiveAcceptanceDate>

Scheduled Delivery Date - returned only when <DestinationType> specified

<ScheduledDeliveryDate>

Live XML Output Example

The Package Services Service Standards Web Tool returns the following information to the user if the information is valid and pickup is available to the supplied address:

<StandardBResponse>

<OriginZip>902</OriginZip>

<DestinationZip>211</DestinationZip>

<Days>7</Days>

</StandardBResponse>

 

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

 


4.0    First Class Mail Service Standards Web Tool

The First Class Mail Service Standards Web Tool receives requests and returns the average number of days it will take a package to arrive at its destination.  The First Class Mail Service Standards Web Tool processes a single request.  Ensure that end-users understand that these are service standards and not guaranteed commitments.

4.1    The First Class Mail Service Standards Web Tool Transaction Procedures

The illustration below shows the transactional flow of information to and from the USPS The First Class Mail Service Standards Web Tool server:

 

First Class Mail Service Standards Web Tool Server
Laptop computer icon. Inputs via XML request are origin zip code and destination zip code.
Server icon.  Server tasks are gets standards and builds XML response.
Laptop computer icon.  Outputs via XML response are sorigin zip code, destination zip code and days.

4.2    Run Live Data

Step 1: Build the XML Request

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

<FirstClassMailRequest

Required

Input tag exactly as presented.

…USERID=”userid”>

Required

Use user ID provided with registration.

 

e.g., <FirstClassMailRequest USERID=”xxxxxxxx” >

 

Tags within the above defined call are as follows:

XML Tag

Required/

Optional

Description & Values Allowed

<OriginZip>

Required Tag/

Required Value

Origination and destination ZIP Codes must be valid.  Only the first 3 digits of the Zip Code are entered between the open tag and close tag.  If a 4- or 5-digit ZIP Code is entered, the last 1 or 2 digits will be ignored.

For example: <OriginZip>902</OriginZip>

<DestinationZip>

Required Tag/

Required Value

Origination and destination ZIP Codes must be valid.  Only the first 3 digits of the Zip Code are entered between the open tag and close tag.  If a 4- or 5-digit ZIP Code is entered, the last 1 or 2 digits will be ignored.

For example: <DestinationZip>211</DestinationZip>

<DestinationType>

Optional Tag/

Optional Value

Destination Type for package.  Valid values are:

 

“1” = PO-Addressee – Street (Default Value)

“2” = PO-Addressee – PO Box

“3” = Hold For Pick-up

 

For example: <DestinationType>1</DestinationType>

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:

<OriginZip>902</OriginZip>

In this instance, you will replace “902” with the first 3 digits of the origin ZIP Code.

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:

<FirstClassMailRequest USERID=”xxxxxxxx>

     <OriginZip>902</OriginZip>

     <DestinationZip>211</DestinationZip>

</FirstClassMailRequest>

Step 2: 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 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 FirstClassMail.  The format of the XML transaction is:

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

Step 3: Unpack the XML Response

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

Response Type

<FirstClassMailResponse>

Origination ZIP Code

<OriginZip>

Destination ZIP Code

<DestinationZip>

Average time for delivery

<Days>

Service Standards Messaging (optional – appears only when applicable)

<Message>

Effective Acceptance Date - returned only when <DestinationType> specified

<EffectiveAcceptanceDate>

Scheduled Delivery Date - returned only when <DestinationType> specified

<ScheduledDeliveryDate>

Live XML Output Example

The First Class Mail Service Standards Web Tool returns the following information to the user if the information is valid and pickup is available to the supplied address:

< FirstClassMailResponse>

<OriginZip>902</OriginZip>

<DestinationZip>211</DestinationZip>

<Days>3</Days>

</FirstClassMailResponse>

 

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


5.0    Express Mail Service Commitments Web Tool

The Express Mail Service Commitments Web Tool provides delivery commitments for Express Mail packages.  A user provides an origination and a destination ZIP Code and an optional current or future date that the package will be shipped.  The Web Tool returns all the Express Mail Service Commitments for the given locations to include package drop-off information.

Express Mail Service Commitments Web Tool Transaction Procedures

The illustration below shows the transactional flow of information to and from the USPS Express Mail Service Commitments Web Tool server.

Express Mail Service Commitments Web Tool Server
Laptop computer icon. Inputs via XML request are origin zip code, destination zip code and date.
Server icon.  Server tasks are gets standards and builds XML response.
Laptop computer icon.  Outputs via XML response are origin (zip, city, state), destination (zip, city, state), service commitment information and drop-off times and locations.

5.1    Run Live Data

Step 1: Build the XML Request

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

XML Tag

Required/

Optional

Description & Values Allowed

<ExpressMailCommitmentRequest

Required

Input tag exactly as presented.

…USERID=”userid”>

Required

Use user ID provided with registration.

e.g., <ExpressMailCommitmentRequest USERID=”yourID”>

Tags within the above defined call are as follows:

XML Tag

Required/

Optional

Description & Values Allowed

<OriginZIP>

Required Tag/

Required Value

ZIP code where the package originates.  Can be a 3 or 5 digit ZIP code.

For example: <OriginZIP>20770</OriginZIP>

<DestinationZIP>

Required Tag/

Required Value

 ZIP Code of the package destination.  Five digit ZIP Code.

For example: <DestinationZIP>11210</DestinationZIP>

<Date>

Required Tag/ Optional Value

Date package is shipped.  Can be left blank.  Can use formats MM/DD/YYYY or DD-MMM-YYYY.

For example:

<Date>05-Aug-2004</Date>

<DropOffTime>

Optional Tag/ Optional Value

Time package is shipped.  This tag can be omitted or left blank.  Use format HH:MM such as 13:30.

For example:

< DropOffTime >15:00</ DropOffTime >

<ReturnDates>

Optional Tag/ Optional Value

Indicates if Scheduled Delivery and Effective Acceptance dates should be returned.  Specify ‘true’ or ‘false’

For example:

<ReturnDates>true</ReturnDates>

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:

<OriginZIP>20008</OriginZIP>

In this instance, you will replace “20008” with your origin ZIP Code.

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:

<ExpressMailCommitmentRequest USERID="xxxxx">

     <OriginZIP>60605</OriginZIP>

     <DestinationZIP>11210</DestinationZIP>

     <Date></Date>

</ExpressMailCommitmentRequest>

 

Step 2: 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 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 ExpressMailCommitment.  The format of the XML transaction is:

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

Step 3: Unpack the XML Response

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

<ExpressMailCommitmentResponse>

Origin ZIP

<OriginZIP>

Origin City

<OriginCity>

Origin State

<OriginState>

Destination ZIP

<DestinationZIP>

Destination City

<DestinationCity>

Destination State

<DestinationState>

Date

<Date>

Time

<Time>

Express Mail Transportation Message - returned only when applicable and <ReturnDates>=’true’

<EMTransMsg>

Message Code - returned only when applicable and <ReturnDates>=’true’

<MsgCode>

Message Text - returned only when applicable and <ReturnDates>=’true’

<Msg>

Effective Acceptance Date - returned only when <ReturnDates>=’true’

<EffectiveAcceptanceDate>

Commitment – there can be multiple commitments

<Commitment>

Commitment Name

<CommitmentName>

Commitment Time

<CommitmentTime>

Commitment Sequence Number (see the Recommended Display of Commitments Information section, below)

<CommitmentSequence>

Location – there can be multiple locations

<Location>

Scheduled Delivery Date - returned only when <ReturnDates>=’true’

<ScheduledDeliveryDate>

Cutoff Time

<CutOff>

Facility Name

<Facility>

Facility Street Address

<Street>

Facility City

<City>

Facility State

<State>

Facility ZIP Code

<Zip>

Message indicating over 200 locations

<Message>

Recommended Display of Commitments Information

The returned Express Mail Service Commitments includes the following key items of information that will be used in how the information is displayed.

§  Commitment Name (e.g., 1-Day)

§  Commitment Time (e.g., 10:30 AM)

§  Commitment Sequence (e.g., A0110)

§  Locations related to the Commitment (e.g., Post Office, Air Mail Facility, etc.)

This is repeated for all of the Commitments pertinent to the XML request.  USPS recommends that the Web Tools developer display the returned Express Mail Service Commitments data using the <CommitmentSequence> field sorted in descending order.  The table below associates the Commitment Sequence Codes with the Commitment returned.

Commitment Sequence Codes

Commitment in XML Return

A0110

1-Day at 10:30 AM

B0110

1-Day at 10:30 AM PME HFPU

A0112

1-Day at 12:00 PM

A0115

1-Day at 3:00 PM

B0115

1-Day at 3:00 PM AM PME HFPU

A0210

2-Day at 10:30 AM

A0212

2-Day at 12:00 PM

A0215

2-Day at 3:00 PM

b0201

2-Day PME HFPU

 

 

 

 

 

An ascending sort sequence is recommended so that the earliest Commitment is displayed first with the latest Commitment displayed last.

As noted earlier, within each Commitment there will be a series of Locations.  USPS recommends that the Web Tools developer display the returned Locations data in the following sort order.

§  Primary Sort Key  = <CutOff>, which is the cutoff time that the package must be received at the facility.  On the primary sort key, a descending sort sequence is recommended so that the latest cutoff time is displayed first with the earliest cutoff time displayed last.

§  Secondary Sort Key  = <Facility>, which is the facility type in descending order (e.g., Post Office, Express Mail Collection Box, Air Mail Facility, etc.)

§  Tertiary Sort Key  = <Zip>, which is the ZIP Code for the facility in question and therefore will sort all the addresses by ZIP Code.

The following is an example using the USPS recommended sorts:

Commitment #1: Next Day 10:00 AM

            Location #1: Cutoff time 5:00 PM, Post Office, Address/ZIP

            Location #2: Cutoff time 5:00 PM, Express Mail Collection Box, Address/ZIP

            Location #3: Cutoff time 5:00 PM, Express Mail Collection Box, Address/ZIP

            Location #4: Cutoff time 5:00 PM, Air Mail Facility, Address/ZIP

            Location #5: Cutoff time 3:00 PM, Post Office, Address/ZIP

            Location #6: Cutoff time 3:00 PM, Express Mail Collection Box, Address/ZIP

            Location #7: Cutoff time 3:00 PM, Air Mail Facility, Address/ZIP

            Location #8: Cutoff time 2:00 PM, Post Office, Address/ZIP

            Location #9: Cutoff time 2:00 PM, Express Mail Collection Box, Address/ZIP

Live XML Output Example

The following is a response from the Express Mail Service Commitments Web Tool.

<?xml version="1.0"?>

<ExpressMailCommitmentResponse>

     <OriginZIP>60605</OriginZIP>

     <OriginCity>CHICAGO</OriginCity>

     <OriginState>IL</OriginState>

     <DestinationZIP>11210</DestinationZIP>

     <DestinationCity>BROOKLYN</DestinationCity>

     <DestinationState>NY</DestinationState>

     <Date>4-Feb-2014</Date>

     <Time>6:51AM</Time>

     <EffectiveAcceptanceDate>2014-02-04</EffectiveAcceptanceDate>

     <Commitment>

       <CommitmentName>1-Day</CommitmentName>

       <CommitmentTime>3:00 PM</CommitmentTime>

       <CommitmentSequence>A0115</CommitmentSequence>

       <Location>

         <ScheduledDeliveryDate>2014-02-05</ScheduledDeliveryDate>

         <CutOff>6:30 PM</CutOff>

         <Facility>POST OFFICE</Facility>

         <Street>433 W HARRISON ST FL LBBY</Street>

         <City>CHICAGO</City>

         <State>IL</State>

         <Zip>60699</Zip>

       </Location>

       <Location>

         <ScheduledDeliveryDate>2014-02-05</ScheduledDeliveryDate>

         <CutOff>6:00 PM</CutOff>

         <Facility>POST OFFICE</Facility>

         <Street>211 S CLARK ST</Street>

         <City>CHICAGO</City>

         <State>IL</State>

         <Zip>60604</Zip>

       </Location>

     </Commitment>

     <Commitment>

       <CommitmentName>1-Day</CommitmentName>

       <CommitmentTime>3:00 PM</CommitmentTime>

       <CommitmentSequence>B0115</CommitmentSequence>

       <Location>

         <ScheduledDeliveryDate>2014-02-05</ScheduledDeliveryDate>

         <CutOff>6:30 PM</CutOff>

         <Facility>POST OFFICE</Facility>

         <Street>433 W HARRISON ST FL LBBY</Street>

         <City>CHICAGO</City>

         <State>IL</State>

         <Zip>60699</Zip>

       </Location>

       <Location>

         <ScheduledDeliveryDate>2014-02-05</ScheduledDeliveryDate>

         <CutOff>6:00 PM</CutOff>

         <Facility>POST OFFICE</Facility>

         <Street>211 S CLARK ST</Street>

         <City>CHICAGO</City>

         <State>IL</State>

         <Zip>60604</Zip>

       </Location>

     </Commitment>

  </ExpressMailCommitmentResponse>

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