Post Office Locator V2

 

USPS Web Tools™

Application Programming Interface

User Guide

Version 6.10 (11/18/2024)

 

 

 

 

 

 

 

 

Table of Contents

1.0  Introduction. 3

1.1        Before you get started: 3

2.0  Post Office Locator API - External 3

2.1        Overview.. 3

2.1.1        API Signature. 3

2.2        Request Descriptions. 3

2.2.1        Sample Request 6

2.3        Response Descriptions. 6

2.3.1        Sample Response. 8

3.0  Error Responses. 10

3.1        Overview.. 10

3.1.1        Error Response Parameters. 10

3.1.2        Sample Error Response. 11

4.0  Appendix A. 12

 

1.0        Introduction

This document provides the definition of the USPS Web Tools Post Office (PO) Locator Version 2 API. This service is considered a hybrid since both the WebTools system and the PO Locator system, including an external location service provider, are involved in processing the requests. The location, service, and hour information maintained by the PO Locator system is a subset of information maintained in the USPS Facilities Database (FDB) sources. The information is updated on a regular basis, so that the information returned to the caller reflects that which is maintained by the data providers.

1.1     Before you get started:

The Web Tools Post Office Locator API requires additional API permissions. Integrators should contact USPS Internet Customer Care Center and follow the below instructions to submit a request for Web Tools POLocatorV2Ext API access.

1.      Select “USPS.com” then “Web Tools (APIs)” – reference Email Us | Web Tools Inquiry (usps.com).

2.      In the “Account Information”, specify your Web Tools USERID.

3.      In the “Issue Information”, specify “API Authorization and Testing” and “Authorization error messages”.

4.      In the “Additional Information” section include the following:

Ø  API Access being requested: Specify “POLocatorV2Ext API” or “Post Office Locator API”

Ø  Indicate expected API volume

Ø  Indicate use-case (i.e., how API will be used)

Ø  Provide Mailer ID (MID) if you have one

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   Post Office Locator API - External

2.1     Overview

Post Office Locator External requests require address componets to be supplied for the Facility information to be returned

2.1.1       API Signature

Scheme

Host

Path

API

XML

https://

secure.shippingapis.com

/ShippingAPI.dll?

API=POLocatorV2Ext

&XML=(see below)

 

2.2     Request Descriptions

Tag Name

Occurs

Description

Type

Validation

POLocatorV2ExtRequest

Required

API=POLocator


The PO Locator web service returns USPS facilities within a given radius of a given point. Optionally, filters can be requested to limit the results. There are several request formats such as five-digit ZIP, address, and Latitude/Longitude. 

(Group)

 

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

 

POLocatorV2ExtRequest / PASSWORD

Optional

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

For Example: PASSWORD="XXXXXXX"

NMTOKEN

 

POLocatorV2ExtRequest / Revision

Optional

 

Integer

Enumerations=

·        0

·        1

POLocatorV2ExtRequest / (choice)

Required

This choice represents the calling sequence.

  1.  (Address Components)
    • Firm Name
    • Address 1

®                Address 2 (Required)

®                City (Required)

®                State (Required)

®                Zip 5 (Required)

    • Zip 4
    • Urbanization 

(Choice)

 

POLocatorV2ExtRequest / FirmName

Optional

Company name.  

String

whiteSpace=collapse minLength=1
maxLength=32 

POLocatorV2ExtRequest / Address1

Optional

Secondary address unit designator and number (such as an apartment or suite number (APT 202, STE 100)).  

String

whiteSpace=collapse  

minLength=1
maxLength=32

POLocatorV2ExtRequest / Address2

Optional

Street number and name. Includes predirectional, suffix, and postdirectional for the address or rural route and box number (RR 5 BOX 10), highway contract route and box number (HC 4 BOX 45), or post office box number (PO BOX 458).  

Required if requesting “Address Components”

String

whiteSpace=collapse  

minLength=1
maxLength=32

POLocatorV2ExtRequest / City

Required

The city is any acceptable mailing name for the 5-digit ZIP code.  

Required if requesting “Address Components”

String

whiteSpace=collapse

minLength=1
maxLength=21

POLocatorV2ExtRequest  / State

Required

Use only official USPS state name abbreviations.  

Required if requesting “Address Components”

String

whiteSpace=collapse
pattern=\w{2}  

POLocatorV2ExtRequest / ZIP5

Required

ZIP5 is Required unless City/State is specified.  

Required if requesting “Address Components”

String

pattern=\d{5}  

POLocatorV2ExtRequest / ZIP4

Optional

Last four digits of a complete ZIP+4 code.  

String

minLength=0
pattern=\d{4}  

POLocatorV2ExtRequest / Urbanization

Optional

Urbanization Code  

String

minLength=1
maxLength=28  

POLocatorV2ExtRequest / Radius

Optional

Specify in integral miles.  

Required if request is exclusive to Latitude / Longitude or if requesting “Address Components”

Positive Integer

 

POLocatorV2ExtRequest / MaxLocations

Optional

Specifies the maximum number of locations desired in the response.  

Required if request is exclusive to Latitude / Longitude or if requesting “Address Components”

Positive Integer

default=10

maxInclusive=200  

POLocatorV2ExtRequest / MaxSpecialWeeks

Optional

Number of future weeks of holiday/special hours for a facility. Returns Special business “SPCBUSINESS” hours if available for a facility. When multiple weeks of special hours are requested (i.e. <MaxSpecialWeeks>=“2”), each week of hours will be grouped by the applicable <Starting> and <Ending> dates and returned as a separate set.

String

Default=1

POLocatorV2ExtRequest / Filters

Required

Group that identifies the facility type(s), service(s), and hours criteria.  Valid filters are:

  • FacilityType
  • Service
  • Hours

One filter or all filters may be requested

(Group)

 

POLocatorV2ExtRequest / Filters /FacilityType

Optional, repeating up to 7 times

Specifies the value(s) for the facility filter to be applied.

String

whiteSpace=collapse
Enumeration=

·        PO

POLocatorV2ExtRequest / Filters /Service

Optional

Specifies the values for the service filter to apply. Only facilities supporting the service(s) indicated in this tag will return in response. When not indicated, all services returned; i.e no service filter applied to facilities returned.

String

Default=no service filter applied

Enumerations=

·        CONNECTLOCAL

·        CONNECTREGIONAL

·        GIFTCARDS

·        LBRORETAIL

·        LBROSSK

POLocatorV2ExtRequest / Filters /Hours

Optional

Specifies the type of hours filter to apply.

 

String

whiteSpace=collapse

Enumerations=

·        ALL

·        24HR

·        SATURDAY

·        SUNDAY

·        AFTER5PM

POLocatorV2ExtRequest / Filters

Required

 

(Group)

 

POLocatorV2ExtRequest

Required

 

(Alias)

 

2.2.1   Sample Request

<POLocatorV2ExtRequest USERID="XXXXXXXXX" PASSWORD="">

    <Revision>1</Revision>

    <Address2>212 Charles St</Address2>

    <City>Baltimore</City>

    <State> MD </State>

    <Radius>2</Radius>

    <MaxLocations>2</MaxLocations>

    <Filters>

        <FacilityType>PO</FacilityType>

    </Filters>

</POLocatorV2ExtRequest>

2.3     Response Descriptions

Tag Name

Occurs

Description

Type

Validation

POLocatorV2ExtResponse

Required

Response document from PO Locator web service  

(Group)

 

POLocatorV2ExtResponse / Locations

Required

The zero or more locations that match the request criteria.  

(Group)

 

POLocatorV2ExtResponse / Locations / Location

Optional repeating up to 200 times

In ascending order by Distance.  

(Group)

 

POLocatorV2ExtResponse / Locations / Location / LocationName

Required

Company, Station, Firm name, as appropriate.  

String

 

POLocatorV2ExtResponse / Locations / Location / Address1

Optional

Secondary address line.  

String

 

POLocatorV2ExtResponse / Locations / Location / Address2

Required

Primary address line.  

String

 

POLocatorV2ExtResponse / Locations / Location / City

Required

Name of city.  

String

 

POLocatorV2ExtResponse / Locations / Location / State

Required

Official USPS abbreviation.  

String

 

POLocatorV2ExtResponse / Locations / Location / ZIP5

Required

Five-digit ZIP.  

String

 

POLocatorV2ExtResponse / Locations / Location / Services / Services

Required

One Service tag for each service available.  

(Group)

 

POLocatorV2ExtResponse / Locations / Location / Services / Service / name

Required

Keyword specifying the available services for a facility.

String

Enumerations=

·        CONNECTLOCAL

·        CONNECTREGIONAL

·        GIFTCARDS

·        LBRORETAIL

·        LBROSSK

POLocatorV2ExtResponse / Locations / Location / Hours

Optional

Contains sets of hours of operations.  

(Group)

 

POLocatorV2ExtResponse / Locations / Location / Hours / Set

Required once repeating up to unbounded times

A set of hours representing the availability of services.  

(Group)

 

POLocatorV2ExtResponse / Locations / Location / Hours / Set / name

Required

Keyword indicating what the set of hours represent.

String

whiteSpace=collapse

Enumerations=

·     BUSINESS

·     WINDOWSSERVICE

POLocatorV2ExtResponse / Locations / Location / Hours / Set / MO

Required

Two open-close pairs are available per day of week.  This is service specific hour information 

See Appendix A

 

POLocatorV2ExtResponse / Locations / Location / Hours / Set / TU

Required

Two open-close pairs are available per day of week.  This is service specific hour information 

See Appendix A

 

POLocatorV2ExtResponse / Locations / Location / Hours / Set / WE

Required

Two open-close pairs are available per day of week.  This is service specific hour information 

See Appendix A

 

POLocatorV2ExtResponse / Locations / Location / Hours / Set / TH

Required

Two open-close pairs are available per day of week.  This is service specific hour information 

See Appendix A

 

POLocatorV2ExtResponse / Locations / Location / Hours / Set / FR

Required

Two open-close pairs are available per day of week.  This is service specific hour information 

See Appendix A

 

POLocatorV2ExtResponse / Locations / Location / Hours / Set / SA

Required

Two open-close pairs are available per day of week.  This is service specific hour information 

See Appendix A

 

POLocatorV2ExtResponse / Locations / Location / Hours / Set / SU

Required

Two open-close pairs are available per day of week.  This is service specific hour information 

See Appendix A

 

POLocatorV2ExtResponse / Locations / Location / Hours / Set / (sequence)

Optional

If this set of hours has a limited duration, it is indicated by the start and end dates.

(group)

 

POLocatorV2ExtResponse / Locations / Location / Hours / Set / (sequence) / Starting

Required

Effective date for these hours.  

Date

 

POLocatorV2ExtResponse / Locations / Location / Hours / Set / (sequence) / Ending

Required

Date of last day the hours are in effect.  

Date

 

POLocatorV2ExtResponse / TemporarilyClosed

Optional

Location Temporarily Closed

 

Note: Only returned when a facility is temporarily closed. If a facility is not temporarily closed, this tag will not be returned.

String

minOccurs=1

Enumeration=

·        Y

POLocatorV2ExtResponse / Filters / TemporarilyClosedDate

Optional

Effective date. A date of "YEAR-MONTH-DAY" will return when applicable.

String

minOccurs=0

POLocatorV2ExtResponse / Locations / Location / Parking

Optional

Type of parking accommodations, when available. 

String

Enumerations=

·        LOT

·        STREET

POLocatorV2ExtResponse / Locations / Location / LBRORetail

Deprecated

Label Broker Retail

 

Note:This tag is deprecated. Now returned in Service field

Deprecated

 

POLocatorV2ExtResponse

Required

 

(Alias)

 

2.3.1   Sample Response

<POLocatorV2ExtResponse>

    <Locations>

        <Location>

            <LocationName>BROOKLYN CURTIS BAY</LocationName>

            <Address2>10 16TH AVE</Address2>

            <City>BROOKLYN</City>

            <State>MD</State>

            <ZIP5>21225</ZIP5>

            <Services>

                <Service name="GIFTCARDS"/>

                <Service name="LBRORETAIL"/>

            </Services>

            <Hours>

                <Set name="BUSINESS">

                    <MO>

                        <Open>10:00:00</Open>

                        <Close>14:00:00</Close>

                        <Open>15:15:00</Open>

                        <Close>17:00:00</Close>

                    </MO>

                    <TU>

                        <Open>10:00:00</Open>

                        <Close>14:00:00</Close>

                        <Open>15:15:00</Open>

                        <Close>17:00:00</Close>

                    </TU>

                    <WE>

                        <Open>10:00:00</Open>

                        <Close>14:00:00</Close>

                        <Open>15:15:00</Open>

                        <Close>17:00:00</Close>

                    </WE>

                    <TH>

                        <Open>10:00:00</Open>

                        <Close>14:00:00</Close>

                        <Open>15:15:00</Open>

                        <Close>17:00:00</Close>

                    </TH>

                    <FR>

                        <Open>10:00:00</Open>

                        <Close>14:00:00</Close>

                        <Open>15:15:00</Open>

                        <Close>17:00:00</Close>

                    </FR>

                    <SA>

                        <Open>10:00:00</Open>

                        <Close>13:00:00</Close>

                    </SA>

                    <SU/>

                </Set>

                <Set name="WINDOWSSERVICE">

                    <MO>

                        <Open>10:00:00</Open>

                        <Close>14:00:00</Close>

                        <Open>15:15:00</Open>

                        <Close>17:00:00</Close>

                    </MO>

                    <TU>

                        <Open>10:00:00</Open>

                        <Close>14:00:00</Close>

                        <Open>15:15:00</Open>

                        <Close>17:00:00</Close>

                    </TU>

                    <WE>

                        <Open>10:00:00</Open>

                        <Close>14:00:00</Close>

                        <Open>15:15:00</Open>

                        <Close>17:00:00</Close>

                    </WE>

                    <TH>

                        <Open>10:00:00</Open>

                        <Close>14:00:00</Close>

                        <Open>15:15:00</Open>

                        <Close>17:00:00</Close>

                    </TH>

                    <FR>

                        <Open>10:00:00</Open>

                        <Close>14:00:00</Close>

                        <Open>15:15:00</Open>

                        <Close>17:00:00</Close>

                    </FR>

                    <SA>

                        <Open>10:00:00</Open>

                        <Close>13:00:00</Close>

                    </SA>

                    <SU/>

                </Set>

            </Hours>

            <Parking>LOT</Parking>

        </Location>

        <Location>

            <LocationName>BROOKLYN SOUTH</LocationName>

            <Address2>1500 CHERRY HILL RD</Address2>

            <City>BROOKLYN</City>

            <State>MD</State>

            <ZIP5>21225</ZIP5>

            <Services/>

            <Parking>NONE</Parking>

        </Location>

    </Locations>

</POLocatorV2ExtResponse>

 

3.0   Error Responses

3.1     Overview

If an error is encountered during the processing of the search request, an error message will be returned. The format of the error response and examples of the most probable error responses are provided below. 

3.1.1   Error Response Parameters

Tag Name

Occurs

Description

Type

Validation

Error

Required once

The Error document is returned in response to any Web Tools request that cannot be completed.  

(group)

 

Error / Number

Required once

Number = the error number generated by the Web Tools server or its dependent services.  

xs:hexBinary xs:integer

 

Error / (choice)

Required once

This choice is necessitated by two forms of Error documents.

(choice)

 

Error / (choice) / (sequence)

if used:
Required once

First form has Source followed by Description.

(group)

 

Error / (choice) / (sequence) / Source

Required once

Source = the component and interface that generated the error on the Web Tools server or a masked String when the error was generated by the PO Locator service.  

String

minLength=0  

Error / (choice) / (sequence) / Description

Required once

Description = the error description text.  

String

minLength=0  

Error / (choice) / (sequence)

if used:
Required once

Second form has Description followed by Source.

(group)

 

Error / (choice) / (sequence) / Description

Required once

Description = the error description text.  

String

minLength=0  

Error / (choice) / (sequence) / Source

Required once

Source = the component and interface that generated the error on the Web Tools server.  

String

minLength=0  

Error / HelpFile

Optional

HelpFile = generally not used, but reserved for future use.  

String

minLength=0  

Error / HelpContext

Optional

HelpContext = may contain additional information but generally reserved for future use.  

String

minLength=0  

3.1.2   Sample Error Response

No locations found for the specified search criteria:

<Error>

<Number>800412df</Number>

<Source>POLocator</Source>

<Description>no locations found in the search criteria.</Description>

</Error>

Invalid XML specified (State tag omitted):

<Error>

<Number>80040ee3</Number>

<Source>POLocator</Source>

<Description>Invalid XML Request</Description>

<HelpFile/>

<HelpContext/>

</Error>

Unexpected Error

<Error>

<Number>80040320</Number>
 <Description>An unexpected system error has occurred.  Please try again later or contact the System Administrator.</Description>
 <Source></Source>
</Error>

 

 

 

4.0   Appendix A

Hour Examples

Service hour information is returned as a set of nodes, one for each day of the week. The content within the daily nodes varies and may contain 0, 1, 2, or 4 elements.  Interpretation of this information depends on the service identified, resulting in unique combinations used to identify specific situations.

A typical response for a service is shown below. Monday will be used in all format examples.

<MO>
  <Open>08:30:00</Open>
  <Close>17:00:00</Close>
</MO>

This facility is open from 8:30  AM to 5 PM.

If the facility closes for lunch, two sets of Open and Close times will be returned.

<MO>
  <Open>08:00:00</Open>
  <Close>12:00:00</Close>
  <Open>13:00:00</Open>
  <Close>15:00:00</Close>
</MO>

This facility opens at 8 AM, closed for lunch at noon, re-opens at 1 PM and closes for the day at 3 PM.

Services that only have one time associated with them, such as PO Box Delivery time and Last Collection time, only the Close element will be returned.

<MO>
  <Close>10:00:00</Close>
</MO>

This service, likely to be PO Box Delivery time, has a completion time of 10 AM

If the service is not offered for a particular day, the response will indicate this with a null value day tag to indicate the service is not available on that day.