1.0 Introduction to Web Tools

This document contains a Reference Guide to the Get Locker Info 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 “2” with the weight in pounds for the package.

1.1 Before you get started:

The Web Tools Get Locker Info API requires additional API permissions. Integrators should contact the Smart Locker Customer Onboarding Support team via email at USPSSmartLockerAPI@usps.gov to request access. Reference https://www.uspssmartpackagelockers.com/faq for details.

For additional USPS Web Tools information, please refer to the Step-By-Step guide found on the Technical Documentation section of the Web Tools page on usps.com/webtools.

2.0 Get Locker Info API

2.1 Overview

The Web Tools Get Locker Info API (API=GetLockerInfo) allows integrators to search for operational USPS Smart Locker locations (identified by unique Facility ID <FacilityID>). The Facility ID output returned in the GetLockerInfo API is a required input for label creation to a Smart Locker via the eVS Domestic Label API.

This API enables integrators to search by City/State and/or ZIP or search all operational Smart Locker locations within the USPS network. If a Smart Locker location is available, the Facility ID and supporting information (such as maximum locker dimensions) is returned to enable integrators to select a locker that fits their package. When no City, State, or ZIP parameters are provided (i.e., “All” locker locations requested), the API will return the first 100 Smart Lockers and a location context value for integrators to use to call for additional locations.

2.1.1 API Signature

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

Scheme

Host

Path

API

XML

https://

secure.shippingapis.com

/ShippingAPI.dll

API=GetLockerInfo

&XML=

(see Tag Descriptions below)

2.2 Request Descriptions

Tag Name	Occurs	Description	Type	Validation
GetLockerInfoRequest	Required	API=GetLockerInfo	Alias
GetLockerInfoRequest / USERID	Required	This attribute specifies your Web Tools user ID. See the Developer's Guide for information on obtaining your USERID. For example: USERID="XXXXXXX"	NMTOKEN
GetLockerInfoRequest / PASSWORD	Optional	This attribute specifies your Web Tools password. See the Developer's Guide for information on your Password. For Example: PASSWORD="XXXXXXX"	NMTOKEN
GetLockerInfoRequest /City	Required	City of the Post Office where the Smart Locker is located. To search by City, State must also be included. To return all lockers, do not populate. For example: <City>Miami</City> Note: <City> tag must always be included in the request; a value is not required.	String
GetLockerInfoRequest /State	Required	State of the Post Office where the Smart Locker is located. Value should be passed as two-letter state abbreviation. To search by State, City must also be included. To return all lockers, do not populate. For example: <State>FL</State> Note: <State> tag must always be included in the request; a value is not required.	String	minLength=2 maxLength=2
GetLockerInfoRequest /Zip5	Required	5-digit ZIP code of the Post Office where the Smart Locker is located. To return all lockers, do not populate. For example: <Zip5>33125</Zip5> Note: <Zip5> tag must always be included in the request; a value is not required.	String	pattern=\d{5}
GetLockerInfoRequest / AdditionalLocationsContextValue	Optional	Pagination feature used to return remaining lockers when more than 100 lockers satisfy search criteria. Note: When results exceed 100 lockers, the <AdditionalLocationsContextValue> tag is returned. A subsequent request with this value will return the next 100 lockers until all data is returned indicated when this tag no longer returns in the XML response.	String
GetLockerInfoRequest	Required		Alias

2.2.1 Sample Request

Simple Request

<City>Miami</City>

</GetLockerInfoRequest>

All Call – Returns All Operational Lockers (limited to 100 lockers per XML response)

</GetLockerInfoRequest>

Subsequent All Call – Returns remaining locations using context value returned in original XML response

GetLockerInfoRequest USERID="XXXXXXXXX" PASSWORD="">

</GetLockerInfoRequest>

2.3 Response Descriptions

Tag Name	Occurs	Description	Type	Validation
GetLockerInfoResponse	Required		Alias
GetLockerInfoResponse /Location	Required		String	minOccurs="1" maxOccurs="100"
GetLockerInfoResponse /Location/FacilityID	Required	Unique identifier of the Post Office where the Smart Locker is located. Note: This value is required when generating a Smart Locker label in the Web Tools eVS Domestic Label API.	String
GetLockerInfoResponse /Location/LocationAddress	Required	Post Office (where the Smart Locker is located) Address group.	Address Type
GetLockerInfoResponse /Location/LocationAddress/Address1	Required	Primary Street Address of the Post Office where the Smart Locker is located.	String
GetLockerInfoResponse /Location/LocationAddress/Address2	Optional	Secondary Address (if available) of the Post Office where the Smart Locker is located.	String
GetLockerInfoResponse /Location/LocationAddress/City	Required	City of the Post Office where the Smart Locker is located.	City Type	maxLength ="28" minLength ="0"
GetLockerInfoResponse /Location/LocationAddress/State	Required	State of the Post Office where the Smart Locker is located. Returned as two-letter state abbreviation.	State Type	[a-z or A-Z]{2}
GetLockerInfoResponse /Location/LocationAddress/Zip5	Required	5-digit ZIP code of the Post Office where the Smart Locker is located.	Zip5 Type	[0-9]{5}
GetLockerInfoResponse /Location/LocationAddress/Zip4	Required	4-digit ZIP code of the Post Office where the Smart Locker is located.	Zip4 Type	[0-9]{4}
GetLockerInfoResponse /Location/LocationLatitude	Required	Latitude of the Post Office where the Smart Locker is located.	String
GetLockerInfoResponse /Location/LocationLongitude	Required	Longitude of the Post Office where the Smart Locker is located.	String
GetLockerInfoResponse /Location/DeliveryAddress	Required	Smart Locker Delivery Address group.	Group
GetLockerInfoResponse /Location/DeliveryAddress/Address1	Required	Primary Street Delivery Address of the Smart Locker. (i.e., “USPS SMART LOCKER”)	String
GetLockerInfoResponse /Location/DeliveryAddress/Address2	Required	Secondary Delivery Address of the Smart Locker (if available).	String
GetLockerInfoResponse /Location/DeliveryAddress/City	Required	Delivery City of the Smart Locker.	String	maxLength ="28" minLength ="0"
GetLockerInfoResponse /Location/DeliveryAddress/State	Required	Delivery State of the Smart Locker. Returned as two-letter state abbreviation.	String	[a-z or A-Z]{2}
GetLockerInfoResponse /Location/DeliveryAddress/Zip5	Required	5-digit Delivery ZIP code of the Smart Locker.	String	[0-9]{5}
GetLockerInfoResponse /Location/DeliveryAddress/Zip4	Required	4-digit Delivery ZIP code of the Smart Locker.	String	[0-9]{4}
GetLockerInfoResponse /Location/DeliveryAddress/DeliveryPoint	Required	2-digit Delivery Point Code (DPC) of the Smart Locker.	String	[0-9]{2}
GetLockerInfoResponse /Location/LockerStatus	Required	Defaults to Operational. Note: This API will only return lockers in “Operational” status.	String
GetLockerInfoResponse /Location/LockerOnline	Required	Status of an operational locker.	Boolean	True or False
GetLockerInfoResponse /Location/LockerSizeMaximumLength	Required	Length of the biggest locker compartment for the locker unit.	Decimal
GetLockerInfoResponse /Location/LockerSizeMaximumWidth	Required	Width of the biggest locker compartment for the locker.	Decimal
GetLockerInfoResponse /Location/LockerSizeMaximumHeight	Required	Height of the biggest locker compartment for the locker unit.	Decimal
GetLockerInfoResponse /Location/ServiceDirectShip	Required	Indicates whether the locker can accept direct-to-locker shipments.	Boolean	True or False
GetLockerInfoResponse /Location/ServiceRedelivery	Required	Indicates whether the locker can support redelivery.	Boolean	True or False
GetLockerInfoResponse /Location/ServicePOBoxOverflow	Required	Indicates whether the locker can accept packages that cannot fit into a PO Box.	Boolean	True or False
GetLockerInfoResponse /Location/PrepaidReturns	Required	Indicates whether the locker can accept prepaid returns.	Boolean	True or False
GetLockerInfoResponse /Location/ServiceLabelPrinting	Required	Indicates whether the locker has printing capability.	Boolean	True or False
GetLockerInfoResponse /AdditionalContextValue	Optional	Returns the 7-digit context value so integrators can obtain additional locations.	Context Type	[0-9]{7}
GetLockerInfoResponse	Required		Alias

2.3.1 Sample Response

GetLockerInfo Response (Single Response)

<LocationName>JOSE MARTI</LocationName>

<City>MIAMI</City>

</LocationAddress>

<Address1>USPS SMART LOCKER</Address1>

<City>MIAMI</City>

</DeliveryAddress>

<LockerStatus>Operational</LockerStatus>

<ServicePrepaidReturns>False</ServicePrepaidReturns>

<ServiceLabelPrinting>False</ServiceLabelPrinting>

</Location>

</GetLockerInfoResponse>

GetLockerInfo Response (Multiple Locations returned; exceeds 100)

<LocationName>JOSE MARTI</LocationName>

<City>MIAMI</City>

</LocationAddress>

<Address1>USPS SMART LOCKER</Address1>

<City>MIAMI</City>

</DeliveryAddress>

<LockerStatus>Operational</LockerStatus>

<ServicePrepaidReturns>False</ServicePrepaidReturns>

<ServiceLabelPrinting>False</ServiceLabelPrinting>

</Location>

<LocationName>ALLAPATTAH</LocationName>

<City>MIAMI</City>

</LocationAddress>

<Address1>USPS SMART LOCKER</Address1>

<City>MIAMI</City>

</DeliveryAddress>

<LockerStatus>Operational</LockerStatus>

<ServicePrepaidReturns>False</ServicePrepaidReturns>

<ServiceLabelPrinting>False</ServiceLabelPrinting>

</Location>

<LocationName>NORLAND</LocationName>

<City>MIAMI</City>

</LocationAddress>

<Address1>USPS SMART LOCKER</Address1>

<City>MIAMI</City>

</DeliveryAddress>

<LockerStatus>Operational</LockerStatus>

<ServicePrepaidReturns>False</ServicePrepaidReturns>

<ServiceLabelPrinting>False</ServiceLabelPrinting>

</Location>

<LocationName>MILAM DAIRY</LocationName>

<City>MIAMI</City>

</LocationAddress>

<Address1>USPS SMART LOCKER</Address1>

<City>MIAMI</City>

</DeliveryAddress>

<LockerStatus>Operational</LockerStatus>

<ServicePrepaidReturns>False</ServicePrepaidReturns>

<ServiceLabelPrinting>False</ServiceLabelPrinting>

</Location>

… [truncated for space]

</GetLockerInfoResponse>

2.3.2 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].

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

An <Error> element may be returned at the top (response) level if there is a problem with the syntax of the request, or if a system error occurs. If the search criteria does not return any data, an <Error> element will be returned within the <GetLockerInfoResponse> element, for example:

<Error>

<ErrorMessage>No Parcel Locker was found for the given search parameters.</ErrorMessage>

</Error>

</GetLockerInfoResponse>