http://

secure.shippingapis.com

/ShippingAPI.dll?

API=POLocatorV2Ext

&XML=(see below)

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 and 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)

USERID="XXXXXXXXX" PASSWORD="">

    1

    212 Charles St

    Baltimore

    MD

    2

    <MaxLocations>2MaxLocations>

        <FacilityType>POFacilityType>

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

Optional

Facility Sub Type

String

minOccurs=0

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)

            <LocationName>BROOKLYN CURTIS BAYLocationName>

            10 16TH AVE

            BROOKLYN

            MD

            21225

                        10:00:00

                        14:00:00

                        15:15:00

                        17:00:00

                        10:00:00

                        14:00:00

                        15:15:00

                        17:00:00

                        10:00:00

                        14:00:00

                        15:15:00

                        17:00:00

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  

No locations found for the specified search criteria:

800412df

POLocator

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

Invalid XML specified (State tag omitted):

80040ee3

POLocator

Invalid XML Request</Description>

<HelpFile/>

<HelpContext/>

Unexpected Error

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