1.0 Introduction to Web Tools

This document contains a Reference Guide to the USPS Sunday Holiday API. See the Developers Guide to learn the administrative process for gaining access to the Web Tools APIs as well as the basic mechanism for calling the APIs and processing the results. The Developer’s Guide also contains information on testing and troubleshooting.

Note: The Request Parameter sections present the XML input tags for generating live requests along with the restrictions on the values allowed. An error message will be returned if an incorrect value is entered. Also, be aware of the maximum character amounts allowed for some tags. If the user enters more than those amounts, an error will not be generated. Web Tools will simply pass in the characters up to the maximum amount allowed and disregard the rest. This is important since the resulting value could prevent a correct response.

When building the XML request, pay particular attention to the order and case for tags. An error message will be returned if an incorrect value is entered. Remember that all data and attribute values in this document are for illustration purposes and are to be replaced by your actual values. For instance, a line of sample code may be:

In this instance, you will replace “EJ123456780US” with the tracking ID for the package.

1.1 Before you get started:

For information on registering and getting started with Web Tools, please refer to the Step-By-Step guide found on the Web Tools Technical Documentation Page.

2.0 Sunday Holiday API

2.1 Overview

The Sunday Holiday API allows customers to request information on package availability for Sunday’s and/or Holidays for a given zip code pairing. For information on USPS Holidays, please visit https://about.usps.com/newsroom/events/.

2.1.1 API Signature

Scheme	Host	Path	API	XML
https://	secure.shippingapis.com	/shippingapi.dll?	API=SundayHolidayAvailability	&XML=(see Tag Descriptions below)

2.2 Request Descriptions

Tag Name	Occurs	Description	Type	Validation
SundayHolidayRequest	Required	API = SundayHolidayRequest	(Alias)
SundayHolidayRequest / SundayHoliday / USERID	Required	This attribute specifies your WebTools ID. See the Developers Guide for information on obtaining your USERID For example: <USERID=”XXXXXXXXXX”>	NMTOKEN
SundayHolidayRequest / SundayHoliday	Required	Select Sunday or Holiday	String	Sunday or Holiday
SundayHolidayRequest / FromZipCode	Required	5 digit ship from Zip	String
SundayHolidayRequest / ToZipCode	Required	5 digiit ship to zip	String
SundayHolidayRequest	Required	API = SundayHolidayRequest	(Alias)

2.2.1 Sample Request

Request: SundayHoliday

<SundayHoliday>Sunday</SundayHoliday>

</SundayHolidayRequest>

2.3 Response Descriptions

Tag Name	Occurs	Description	Type	Validation
SundayHolidayResponse	Required	API = SundayHolidayResponse	(Alias)
SundayHolidayResponse / Delivery	Required	Returns whether the lane Is eligible for delivery on day type selected.	String	Enumeration= · Yes · No
SundayHolidayResponse / Error	Optional	Returns when error occurs	String
SundayHolidayResponse	Required	API = SundayHolidayResponse	(Alias)

2.3.1 Sample Response

Response: SundayHoliday – Delivery Available

</SundayHolidayAvailabilityResponse>

Response: SundayHoliday – Delivery Unavailable

</SundayHolidayAvailabilityResponse>

Response: SundayHoliday – Invalid Origin Zip Code

<Error>

<Source>clsSundayHoliday:ValidateParameters</Source>

<Description>Please enter a numeric From Zip Code.</Description>

</Error>

Response: SundayHoliday – Invalid Destination Zip Code

<Error>

<Source>clsSundayHoliday:ValidateParameters</Source>

<Description>Please enter a numeric To Zip Code.</Description>

</Error>