USPS

Get Locker Info API

 

 

USPS Web Tools™

Application Programming Interface

用户指南

Version 1.4 (02/26/2025)

 

 

 

 

 

 

目录

1.0 Introduction to Web Tools. 3

1.1       Before you get started: 3

2.0 Get Locker Info API 3

2.1 Overview. 3

2.1.1      API Signature. 3

2.2       Request Descriptions. 4

2.2.1      Sample Request 5

2.3       Response Descriptions. 6

2.3.1      Sample Response. 8

2.3.2      Error Responses. 11

 

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:

<Pounds>2</Pounds>

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 and 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 or PO Box 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 or PO Box Locker via the eVS Domestic Label API.

This API enables integrators to search by City/State and/or ZIP or search all operational Locker locations within the USPS network. If a 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 Lockers and a location context value for integrators to use to call for additional locations.

2.1.1  API Signature

Scheme

Host

小道

API

XML

https://

secure.shippingapis.com

/ShippingAPI.dll

API=GetLockerInfo

&XML=

(see Tag Descriptions below)

 

备注: GET HTTP requests have length restrictions, whereas POST HTTP requests do not. Please take this under consideration when determining the request-response method that you choose.

 

2.2     Request Descriptions

Tag Name

Occurs

描述

类型

Validation

GetLockerInfoRequest

需要

API=GetLockerInfo

Alias

GetLockerInfoRequest / USERID

需要

This attribute specifies your Web Tools user ID. See the Developer's Guide for information on obtaining your USERID.

例如：USERID="XXXXXXX"

NMTOKEN

 

GetLockerInfoRequest / PASSWORD

Optional

This attribute specifies your Web Tools password. See the Developer's Guide for information on your Password.

例如：PASSWORD="XXXXXXX"

NMTOKEN

 

GetLockerInfoRequest / Revision

Optional

Set this value to “1” to return the response tag “LockerType”

 

例如：<Revision>1</Revision>

String

 

GetLockerInfoRequest / City

需要

City of the Post Office where the Locker is located. To search by City, State must also be included. To return all lockers, do not populate.

 

例如：<City>《miami</City>

 

说明：<City> tag must always be included in the request; a value is not required.

String

 

GetLockerInfoRequest / State

需要

State of the Post Office where the 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.

 

例如：<State>FL</State>

 

说明：<State> tag must always be included in the request; a value is not required.

String

minLength=2

maxLength=2

GetLockerInfoRequest /Zip5

需要

5-digit ZIP code of the Post Office where the Locker is located. To return all lockers, do not populate.

 

例如：<Zip5>33125</Zip5>

 

说明：<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.

 

注意：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

需要

 

Alias

 

2.2.1  Sample Request

 

Simple Request

<GetLockerInfoRequest USERID="XXXXXXXXX" PASSWORD="">

        <Revision>1</Revision>

        <City>《miami</City>

        <State>FL</State>

        <Zip5>33142</Zip5>

</GetLockerInfoRequest>

 

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

<GetLockerInfoRequest USERID="XXXXXXXXX" PASSWORD="">

        <Revision>1</Revision>

        <City></City>

        <State></State>

        <Zip5></Zip5>

</GetLockerInfoRequest>

 

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

GetLockerInfoRequest USERID="XXXXXXXXX" PASSWORD="">

        <Revision>1</Revision>

       <City></City>

        <State></State>

        <Zip5></Zip5>

        <AdditionalLocationsContextValue>1434185</AdditionalLocationsContextValue>

</GetLockerInfoRequest>

 

2.3     Response Descriptions

Tag Name

Occurs

描述

类型

Validation

GetLockerInfoResponse

需要

 

Alias

GetLockerInfoResponse /Location

需要

 

String

minOccurs="1" maxOccurs="100"

GetLockerInfoResponse /Location/FacilityID

需要

Unique identifier of the Post Office where the Locker is located.

 

注意：This value is required when generating a Locker label in the Web Tools eVS Domestic Label API.

String

 

GetLockerInfoResponse /Location/LocationAddress

需要

Post Office (where the Locker is located) Address group.

Address Type

 

GetLockerInfoResponse /Location/LocationAddress/Address1

需要

Primary Street Address of the Post Office where the Locker is located.

String

 

GetLockerInfoResponse /Location/LocationAddress/Address2

Optional

Secondary Address (if available) of the Post Office where the Locker is located.

String

 

GetLockerInfoResponse /Location/LocationAddress/City

需要

City of the Post Office where the Locker is located.

City Type

maxLength ="28"

minLength ="0"

GetLockerInfoResponse /Location/LocationAddress/State

需要

State of the Post Office where the Locker is located. Returned as two-letter state abbreviation.

State Type

[a-z or A-Z]{2}

GetLockerInfoResponse /Location/LocationAddress/Zip5

需要

5-digit ZIP code of the Post Office where the Locker is located.

Zip5 Type

[0-9]{5}

GetLockerInfoResponse /Location/LocationAddress/Zip4

需要

4-digit ZIP code of the Post Office where the Locker is located.

Zip4 Type

[0-9]{4}

GetLockerInfoResponse /Location/LocationLatitude

需要

Latitude of the Post Office where the Locker is located.

String

 

GetLockerInfoResponse /Location/LocationLongitude

需要

Longitude of the Post Office where the Locker is located.

String

 

GetLockerInfoResponse /Location/DeliveryAddress

需要

Locker Delivery Address group.

团体

 

GetLockerInfoResponse /Location/DeliveryAddress/Address1

需要

Primary Street Delivery Address of the Locker. Smart Lockers and PO Box Lockers function the exact same but have different delivery addresses (i.e., “USPS SMART LOCKER” or “PO BOX LOCKER”).

String

 

GetLockerInfoResponse /Location/DeliveryAddress/Address2

需要

Secondary Delivery Address of the Locker (if available).

String

 

GetLockerInfoResponse /Location/DeliveryAddress/City

需要

Delivery City of the Locker.

String

maxLength ="28"

minLength ="0"

GetLockerInfoResponse /Location/DeliveryAddress/State

需要

Delivery State of the Locker.

Returned as two-letter state abbreviation.

String

[a-z or A-Z]{2}

GetLockerInfoResponse /Location/DeliveryAddress/Zip5

需要

5-digit Delivery ZIP code of the Locker.

String

[0-9]{5}

GetLockerInfoResponse /Location/DeliveryAddress/Zip4

需要

4-digit Delivery ZIP code of the Locker.

String

[0-9]{4}

GetLockerInfoResponse /Location/DeliveryAddress/DeliveryPoint

需要

2-digit Delivery Point Code (DPC) of the Locker.

String

[0-9]{2}

GetLockerInfoResponse /Location/LockerType

Required Revision 1

Locker Type. Indicates if Locker is a USPS Smart Locker or a PO Box.

String

Enumeration=

·        POBoxLocker

·        SmartLocker

GetLockerInfoResponse /Location/LockerStatus

需要

Defaults to Operational.

说明：This API will only return lockers in “Operational” status.

String

 

GetLockerInfoResponse /Location/LockerOnline

需要

Status of an operational locker.

Boolean

True or False

GetLockerInfoResponse /Location/LockerSizeMaximumLength

需要

Length of the biggest locker compartment for the locker unit.

Decimal

 

GetLockerInfoResponse /Location/LockerSizeMaximumWidth

需要

Width of the biggest locker compartment for the locker.

Decimal

 

GetLockerInfoResponse /Location/LockerSizeMaximumHeight

需要

Height of the biggest locker compartment for the locker unit.

Decimal

 

GetLockerInfoResponse /Location/ServiceDirectShip

需要

Indicates whether the locker can accept direct-to-locker shipments.

Boolean

True or False

GetLockerInfoResponse /Location/ServiceRedelivery

需要

Indicates whether the locker can support redelivery.

Boolean

True or False

GetLockerInfoResponse /Location/ServicePOBoxOverflow

需要

Indicates whether the locker can accept packages that cannot fit into a PO Box.

Boolean

True or False

GetLockerInfoResponse /Location/PrepaidReturns

需要

Indicates whether the locker can accept prepaid returns.

Boolean

True or False

GetLockerInfoResponse /Location/ServiceLabelPrinting

需要

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

需要

 

Alias

 

 

2.3.1  Sample Response

GetLockerInfo Response (Single Response)

<GetLockerInfoResponse>

  <Location>

    <FacilityID>1368559</FacilityID>

    <LocationName>JOSE MARTI</LocationName>

    <LocationAddress>

      <Address1>425 NW 27TH AVE</Address1>

      <Address2></Address2>

      <City>《MIAMI</City>

      <State>FL</State>

      <Zip5>33125</Zip5>

      <Zip4>9998</Zip4>

    </LocationAddress>

    <LocationLatitude>25.7768520000</LocationLatitude>

    <LocationLongitude>-80.2391510000</LocationLongitude>

    <DeliveryAddress>

      <Address1>USPS SMART LOCKER</Address1>

      <Address2></Address2>

      <City>《MIAMI</City>

      <State>FL</State>

      <Zip5>33125</Zip5>

      <Zip4>0100</Zip4>

      <DeliveryPoint>99</DeliveryPoint>

    </DeliveryAddress>

    <LockerType>SmartLocker</LockerType>

    <LockerStatus>Operational</LockerStatus>

    <LockerOnline>True</LockerOnline>

    <LockerSizeMaximumLength>18.50</LockerSizeMaximumLength>

    <LockerSizeMaximumWidth>14.50</LockerSizeMaximumWidth>

    <LockerSizeMaximumHeight>13.00</LockerSizeMaximumHeight>

    <ServiceDirectShip>True</ServiceDirectShip>

    <ServiceRedelivery>True</ServiceRedelivery>

    <ServicePOBoxOverflow>True</ServicePOBoxOverflow>

    <ServicePrepaidReturns>False</ServicePrepaidReturns>

    <ServiceLabelPrinting>False</ServiceLabelPrinting>

  </Location>

</GetLockerInfoResponse>

 

 GetLockerInfo Sample Response (Multiple Locations returned; exceeds 100)

<GetLockerInfoResponse>

    <Location>

        <FacilityID>1434185</FacilityID>

        <LocationName>LENFANT PLAZA</LocationName>

        <LocationAddress>

            <Address1>470 LENFANT PLZ SW STE 604</Address1>

            <Address2/>

            <City>WASHINGTON</City>

            <State>DC</State>

            <Zip5>20024</Zip5>

            <Zip4>9995</Zip4>

        </LocationAddress>

        <LocationLatitude>38.8839010000</LocationLatitude>

        <LocationLongitude>-77.0264070000</LocationLongitude>

        <DeliveryAddress>

            <Address1>USPS SMART LOCKER</Address1>

            <Address2/>

            <City>WASHINGTON</City>

            <State>DC</State>

            <Zip5>20026</Zip5>

            <Zip4>9703</Zip4>

            <DeliveryPoint>99</DeliveryPoint>

        </DeliveryAddress>

        <LockerType>SmartLocker</LockerType>

        <LockerStatus>Operational</LockerStatus>

        <LockerOnline>True</LockerOnline>

        <LockerSizeMaximumLength>17.25</LockerSizeMaximumLength>

        <LockerSizeMaximumWidth>17.25</LockerSizeMaximumWidth>

        <LockerSizeMaximumHeight>15.00</LockerSizeMaximumHeight>

        <ServiceDirectShip>True</ServiceDirectShip>

        <ServiceRedelivery>True</ServiceRedelivery>

        <ServicePOBoxOverflow>True</ServicePOBoxOverflow>

        <ServicePrepaidReturns>False</ServicePrepaidReturns>

        <ServiceLabelPrinting>False</ServiceLabelPrinting>

    </Location>

    <Location>

        <FacilityID>1437347</FacilityID>

        <LocationName>MERRIFIELD</LocationName>

        <LocationAddress>

            <Address1>8409 LEE HWY</Address1>

            <Address2/>

            <City>MERRIFIELD</City>

            <State>VA</State>

            <Zip5>22116</Zip5>

            <Zip4>9998</Zip4>

        </LocationAddress>

        <LocationLatitude>38.8721130000</LocationLatitude>

        <LocationLongitude>-77.2353660000</LocationLongitude>

        <DeliveryAddress>

            <Address1>PO BOX LOCKER</Address1>

            <Address2/>

            <City>Merrifield</City>

            <State>VA</State>

            <Zip5>22116</Zip5>

            <Zip4>9998</Zip4>

            <DeliveryPoint>11</DeliveryPoint>

        </DeliveryAddress>

        <LockerType>POBoxLocker</LockerType>

        <LockerStatus>Operational</LockerStatus>

        <LockerOnline>True</LockerOnline>

        <LockerSizeMaximumLength>22.50</LockerSizeMaximumLength>

        <LockerSizeMaximumWidth>22.50</LockerSizeMaximumWidth>

        <LockerSizeMaximumHeight>12.00</LockerSizeMaximumHeight>

        <ServiceDirectShip>False</ServiceDirectShip>

        <ServiceRedelivery>False</ServiceRedelivery>

        <ServicePOBoxOverflow>True</ServicePOBoxOverflow>

        <ServicePrepaidReturns>False</ServicePrepaidReturns>

        <ServiceLabelPrinting>False</ServiceLabelPrinting>

    </Location>

… [truncated for space]

<AdditionalLocationsContextValue>1437366</AdditionalLocationsContextValue>

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

<GetLockerInfoResponse>

    <Error>

        <ErrorCode>-2147219102</ErrorCode>

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

    </Error>

</GetLockerInfoResponse>

 

 

Powered by Translations.com GlobalLink Web SoftwarePowered by GlobalLink Web