Post Office Locator V2

 

USPS Web Tools™

Application Programming Interface

用户指南

Version 6.8 (10/30/2023)

 

 

 

 

 

 

 


 

目录

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 5

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

小道

API

XML

https://

secure.shippingapis.com

/ShippingAPI.dll?

API=POLocatorV2Ext

&XML=(see below)

 

2.2     Request Descriptions

Tag Name

Occurs

描述

类型

Validation

POLocatorV2ExtRequest

需要

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

需要

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

例如:USERID="XXXXXXX"

NMTOKEN

 

POLocatorV2ExtRequest / PASSWORD

Optional

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

例如:PASSWORD="XXXXXXX"

NMTOKEN

 

POLocatorV2ExtRequest / Revision

Optional

 

Integer

Enumerations=

·        0

·        1

POLocatorV2ExtRequest / (choice)

需要

This choice represents the calling sequence.

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

®                Address 2 (Required)

®                City (Required)

®                State (Required)

®                Zip 5 (Required)

    • 邮区编码 4
    • 城市化 

(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

需要

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

需要

Use only official USPS state name abbreviations.  

Required if requesting “Address Components”

String

whiteSpace=collapse
pattern=\w{2}  

POLocatorV2ExtRequest / ZIP5

需要

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

城市化代码  

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

需要

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

  • FacilityType
  • Service (Note: effective 10/22/20)
  • 小时

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.

 

*Note: Effective 2020 年 10 月 22 日

String

Default=no service filter applied

Enumerations=

·        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

需要

 

(Group)

 

POLocatorV2ExtRequest

需要

 

(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

描述

类型

Validation

POLocatorV2ExtResponse

需要

Response document from PO Locator web service  

(Group)

 

POLocatorV2ExtResponse / Locations

需要

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

需要

Company, Station, Firm name, as appropriate.  

String

 

POLocatorV2Response / Locations / Location / LocationSubType

Optional

Facility Sub Type

String

minOccurs=0

 

POLocatorV2ExtResponse / Locations / Location / Address1

Optional

Secondary address line.  

String

 

POLocatorV2ExtResponse / Locations / Location / Address2

需要

Primary address line.  

String

 

POLocatorV2ExtResponse / Locations / Location / City

需要

Name of city.  

String

 

POLocatorV2ExtResponse / Locations / Location / State

需要

Official USPS abbreviation.  

String

 

POLocatorV2ExtResponse / Locations / Location / ZIP5

需要

Five-digit ZIP.  

String

 

POLocatorV2Response / Locations / Location / Services / Services

需要

One Service tag for each service available.  

(Group)

 

POLocatorV2Response / Locations / Location / Services / Service / name

需要

Keyword specifying the available services for a facility.

注意:Services supported by a facility will return effective 2020 年 10 月 22 日.

String

Enumerations=

·        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

需要

Keyword indicating what the set of hours represent.

String

whiteSpace=collapse

Enumerations=

·     BUSINESS

·     WINDOWSSERVICE

POLocatorV2ExtResponse / Locations / Location / Hours / Set / MO

需要

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

需要

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

需要

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

需要

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

需要

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

需要

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

需要

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

需要

Effective date for these hours.  

日期

 

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

需要

Date of last day the hours are in effect.  

日期

 

POLocatorV2Response / TemporarilyClosed

Optional

Location Temporarily Closed

 

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

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

需要

 

(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>地块</Parking>

        </Location>

        <Location>

            <LocationName>BROOKLYN SOUTH</LocationName>

            <Address2>1500 CHERRY HILL RD</Address2>

            <City>BROOKLYN</City>

            <State>MD</State>

            <ZIP5>21225</ZIP5>

            <Services/>

            <Parking>无</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

描述

类型

Validation

错误

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.

Powered by Translations.com GlobalLink OneLink SoftwarePowered By OneLink