https://

secure.shippingapis.com

/ShippingAPI.dll?

API=POLocatorV2Ext

&XML=(see below)

POLocatorV2ExtRequest

Obligatorio

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

Obligatorio

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

Por Ejemplo: USERID="XXXXXXX"

NMTOKEN

POLocatorV2ExtRequest / PASSWORD

Optional

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

Por Ejemplo: PASSWORD="XXXXXXX"

NMTOKEN

POLocatorV2ExtRequest / Revision

Optional

Integer

Enumerations=

·        0

·        1

POLocatorV2ExtRequest / (choice)

Obligatorio

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
• Urbanización 

(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

Obligatorio

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

Obligatorio

Use only official USPS state name abbreviations.  

Required if requesting “Address Components”

String

whiteSpace=collapse
pattern=\w{2}  

POLocatorV2ExtRequest / ZIP5

Obligatorio

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

Código de urbanización  

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

Obligatorio

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

• FacilityType
• Servicio
• Horarios

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

Obligatorio

(Group)

POLocatorV2ExtRequest

Obligatorio

(Alias)

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

POLocatorV2ExtResponse

Obligatorio

Response document from PO Locator web service  

(Group)

POLocatorV2ExtResponse / Locations

Obligatorio

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

Obligatorio

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

Obligatorio

Primary address line.  

String

POLocatorV2ExtResponse / Locations / Location / City

Obligatorio

Name of city.  

String

POLocatorV2ExtResponse / Locations / Location / State

Obligatorio

Official USPS abbreviation.  

String

POLocatorV2ExtResponse / Locations / Location / ZIP5

Obligatorio

Five-digit ZIP.  

String

POLocatorV2ExtResponse / Locations / Location / Services / Services

Obligatorio

One Service tag for each service available.  

(Group)

POLocatorV2ExtResponse / Locations / Location / Services / Service / name

Obligatorio

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

Obligatorio

Keyword indicating what the set of hours represent.

String

whiteSpace=collapse

Enumerations=

·     BUSINESS

·     WINDOWSSERVICE

POLocatorV2ExtResponse / Locations / Location / Hours / Set / MO

Obligatorio

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

Obligatorio

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

Obligatorio

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

Obligatorio

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

Obligatorio

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

Obligatorio

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

Obligatorio

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

Obligatorio

Effective date for these hours.  

Fecha

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

Obligatorio

Date of last day the hours are in effect.  

Fecha

POLocatorV2ExtResponse / TemporarilyClosed

Optional

Location Temporarily Closed

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

Obligatorio

(Alias)

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

        </Location>

        <Location>

            <LocationName>BROOKLYN SOUTH</LocationName>

            <Address2>1500 CHERRY HILL RD</Address2>

            <City>BROOKLYN</City>

            <State>MD</State>

            <ZIP5>21225</ZIP5>

            <Services/>

            <Parking>NINGUNA</Parking>

        </Location>

    </Locations>

</POLocatorV2ExtResponse>

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:

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