1.0 Introduction to Web Tools

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. The Web Tool 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 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:

In this instance, you will replace “12345” with the destination zip code for your request.

1.1 Before you get started:

For information on registering and getting started with Web Tools, please refer to the Step-By-Step guide found on the Web Tools Technical Documentation Page.

2.0 SDCGetLocations API

2.1 Overview

The SDCGetLocations Web Tools API allows customers to get estimates on delivery standards between 3 or 5 digit Zip Codes for Priority Mail Express, Priority Mail, First Class Mail, Marketing Mail, Periodicals, and Package Services. The data returned by the API is intended for display only. The content or sequence of the string data returned in the API response may change.

2.1.1 API Signature Table

Scheme	Host	Path	API	XML
https://	secure.shippingapis.com	/shippingapi.dll?	API=SDCGetLocations	&XML=(see below)

2.2 Request Descriptions

Tag Name

Occurs

Description

Type

Validation

SDCGetLocationsRequest

Required

API=SDCGetLocations

(Alias)

SDCGetLocationsRequest / USERID

Required

This attribute specifies your WebTools ID. See the Developers Guide for information on obtaining your USERID.

For example:

<USERID>=”XXXXXXXXXXX”

String

SDCGetLocationsRequest / MailClass

Required

Defines mail class for commitment data. For example: <MailClass>0<MailClass>

Mail Class Value	Description
0	All Mail Classes (1-digit)
000	All Mail Classes (3-digit)
1	Priority Mail Express
2	Priority Mail
201	Priority Mail 1-Day
202	Priority Mail 2-Day
203	Priority Mail 3-Day
204	Priority Mail Military
205	Priority Mail DPO
206	Priority Mail Offshore
3	First-Class
301	First-Class Mail Letters
302	First-Class Mail Flats
303	First-Class Mail Cards
304	First-Class Mail Parcel/Package
4	Standard Mail
401	Standard Mail Letters
402	Standard Mail Flats
403	Standard Mail Marketing Parcels
404	Standard Mail Simple Samples
405	Parcel Select Lightweight
5	Periodicals
501	Periodicals
502	Parcel Shaped Periodicals
6	Package Services
601	Parcel Select
602	Standard Post
603	Media Mail
604	Library Mail
605	Bound Printed Matter

String

minOccurs="1" maxOccurs="1"

Enumerations=

· 0

· 000

· 1

· 2

· 201

· 202

· 203

· 204

· 205

· 206

· 3

· 301

· 302

· 303

· 304

· 4

· 401

· 402

· 403

· 404

· 405

· 5

· 501

· 502

· 6

· 601

· 602

· 603

· 604

· 605

SDCGetLocationsRequest / OriginZIP

Required

ZIP code must be valid. May be 3, 5, or 9 characters.

For example:

String

minOccurs="1" maxOccurs="1"

SDCGetLocationsRequest / DestinationZIP

Required

ZIP code must be a valid 5-character zip code.

For example: <DestinationZIP>54324</DestinationZIP>

String

minOccurs="1" maxOccurs="1"

SDCGetLocationsRequest / AcceptDate

Optional

Date Package will be mailed. Acceptance date may be up to 30 days in advance. Defaults to system date.

Enter the date in format: dd-mmm-yyyy.

For example:

String

minOccurs="0" maxOccurs="1"

SDCGetLocationsRequest / AcceptTime

Optional

Time package will be accepted at a postal facility. Defaults to system time. Default value returned when no value is included in the request will be current time CT.

Enter the time in format: HHMM

For example:

String

minOccurs="0" maxOccurs="1"

SDCGetLocationsRequest / NonEMDetail

Optional

Returns additional detail for Non-Expedited mail classes when ‘True.’ Default=’False’

For example:

String

minOccurs="0" maxOccurs="1"

SDCGetLocationsRequest / NonEMOriginType

Optional

Origin type indicator for non-Expedited shipments:

Valid Values:

“1” = Local Mail

“2” = Destination Entered Mail

For example:

String

minOccurs="0" maxOccurs="1"

Enumeration

· 1

· 2

SDCGetLocationsRequest / NonEMDestType

Optional

Destination type indicator for non-Expedited shipments:

Valid Values:

“1” = PO-Addressee - Street

“2” = PO-Addressee – PO Box

“3” = Hold for pickup

For example:

String

minOccurs="0" maxOccurs="1"

Enumeration

· 1

· 2

· 3

SDCGetLocationsRequest / Weight

Optional

Item weight. For future use.

String

minOccurs="0" maxOccurs="1"

SDCGetLocationsRequest

Required once

(Alias)

2.2.1 Sample Request

Request: SDCGetLocations:

</SDCGetLocationsRequest>

2.3 Response Descriptions

Tag Name

Occurs

Description

Type

Validation

SDCGetLocationsResponse

Required

(Alias)

SDCGetLocationsResponse / Release

Required

Release version

String

minOccurs="1" maxOccurs="1"

SDCGetLocationsResponse / CallerID

Required

Caller ID

String

minOccurs="1" maxOccurs="1"

SDCGetLocationsResponse / MailClass

Required

MailClass from request

String

minOccurs="1" maxOccurs="1"

SDCGetLocationsResponse / OriginZIP

Required

OriginZIP from request

String

minOccurs="1" maxOccurs="1"

SDCGetLocationsResponse / OriginCity

Required

Origin City

String

minOccurs="0" maxOccurs="1"

SDCGetLocationsResponse / OriginState

Required

Origin State

String

minOccurs="0" maxOccurs="1"

SDCGetLocationsResponse / DestZIP

Required

DestinationZIP from request

String

minOccurs="1" maxOccurs="1"

SDCGetLocationsResponse / DestCity

Required

Destination City

String

minOccurs="0" maxOccurs="1"

SDCGetLocationsResponse /

DestState

Required

Destination State

String

minOccurs="0" maxOccurs="1"

SDCGetLocationsResponse / AcceptDate

Required

Acceptance date at postal facility

String

minOccurs="1" maxOccurs="1"

SDCGetLocationsResponse / AcceptTime

Required

Acceptance time at postal facility

String

minOccurs="1" maxOccurs="1"

SDCGetLocationsResponse / Weight

Optional

Weight from request

String

minOccurs="0" maxOccurs="1"

SDCGetLocationsResponse / Expedited

Optional

Groups Priority Mail Express Mail and Priority Mail Commitments and Scheduled Delivery Dates.

Appears where applicable: SDCGetLocationsRequest [MailClass='0' or MailClass=’1’]

(Group)

minOccurs="0" maxOccurs="1"

SDCGetLocationsResponse / Expedited / EAD

Optional

Effective Acceptance Date

String

minOccurs="0" maxOccurs="1"

SDCGetLocationsResponse / Commitment

Optional

Groups Priority Mail Express information.

(Group)

minOccurs="0" maxOccurs="1"

SDCGetLocationsResponse / Expedited / MailClass

Optional

Mail Class indicator for Priority Mail Express.

Value = “1”

String

minOccurs="0" maxOccurs="1"

SDCGetLocationsResponse / Expedited / Commitment

Optional, repeating up to unbounded times

Groups Priority Mail Express commitment information

(Group)

minOccurs="0" maxOccurs="unbounded"

SDCGetLocationsResponse / Expedited / Commitment / CommitmentName

Optional

Commitment Name

Valid Values:

1-Day

2-Day

3-Day

DPO

Military

Note: If a scenario exceeds a 3-day commitment then no value will be returned in the response field

String

minOccurs="0" maxOccurs="1"

Enumeration

· 1-Day

· 2-Day

· 3-Day

· DPO

· Military

SDCGetLocationsResponse / Expedited / Commitment / CommitmentTime

Optional

Commitment Time. Value will only be returned for Priority Mail Express.

String

minOccurs="0" maxOccurs="1"

Enumeration=

· 1800

SDCGetLocationsResponse / Expedited / Commitment / CommitmentSeq

Optional

Commitment Sequence

Valid Values:

Seq #	Service Standard
A0118	1-Day at 6:00 PM
B0118	1-Day at 6:00 PM
A0218	2-Day at 6:00 PM
B0218	2-Day at 6:00 PM

String

minOccurs="0" maxOccurs="1"

SDCGetLocationsResponse / Expedited / Commitment / Location

Optional, repeating up to unbounded times

Groups drop off location information

(Group)

minOccurs="0" maxOccurs="1"

SDCGetLocationsResponse / Expedited / Commitment / Location / SDD

Optional

Scheduled Delivery Date

String

minOccurs="0" maxOccurs="1"

SDCGetLocationsResponse / Expedited / Commitment / Location / COT

Optional

Cut-off Time

String

minOccurs="0" maxOccurs="1"

SDCGetLocationsResponse / Expedited / Commitment / Location / FacType

Optional

Facility Type

String

minOccurs="0" maxOccurs="1"

Enumeration

· POST OFFICE

· PRIORITY MAIL EXPRESS COLLECTION BOX

· AIR MAIL FACILITY

SDCGetLocationsResponse / Expedited / Commitment / Location / Street

Optional

Facility Street

String

minOccurs="0" maxOccurs="1"

SDCGetLocationsResponse / Expedited / Commitment / Location / City

Optional

Facility City

String

minOccurs="0" maxOccurs="1"

SDCGetLocationsResponse / Expedited / Commitment / Location / State

Optional

Facility State

String

minOccurs="0" maxOccurs="1"

SDCGetLocationsResponse / Expedited / Commitment / Location / ZIP

Optional

Facility Zip Code

String

minOccurs="0" maxOccurs="1"

SDCGetLocationsResponse / Expedited / Commitment / Location / IsGuaranteed

Optional

Indicates if Guarantee is offered for Priority Mail Express.

Valid Values

“1” = Guaranteed

“2” = No Guarantee

“3” = Temporary No Guarantee

String

minOccurs="0" maxOccurs="1"

SDCGetLocationsResponse / Expedited /

Optional

Groups Priority Mail Guarantee information.

(Group)

minOccurs="0" maxOccurs="1"

SDCGetLocationsResponse / Expedited /MailClass

Optional

Mail Class indicator for Priority Mail.

Value = “2”

String

minOccurs="0" maxOccurs="1"

SDCGetLocationsResponse / Expedited / Commitment

Optional, repeating up to unbounded times

Groups Priority Mail commitment information

(Group)

minOccurs="0" maxOccurs="unbounded"

SDCGetLocationsResponse / Expedited / Commitment / CommitmentName

Optional

Commitment Name

String

minOccurs="0" maxOccurs="1"

SDCGetLocationsResponse / Expedited / Commitment / CommitmentTime

Optional

Commitment Time

String

minOccurs="0" maxOccurs="1"

SDCGetLocationsResponse / Expedited / Commitment / CommitmentSeq

Optional

Commitment Sequence

Valid Values:

Seq #	Service Standard
C0100	1-Day Street
C0200	2-Day Street
C0300	3-Day Street
D0100	1-Day PO Box
D0200	2-Day PO Box
D0300	3-Day PO Box
E0100	1-Day HFPU
E0200	2-Day HFPU
E0300	3-Day HFPU

String

minOccurs="0" maxOccurs="1"

SDCGetLocationsResponse / Expedited / Commitment / Location

Optional, repeating up to unbounded times

Groups drop off location information

(Group)

minOccurs="0" maxOccurs="unbounded"

SDCGetLocationsResponse / Expedited / Commitment / Location / SDD

Optional

Scheduled Delivery Date

String

minOccurs="0" maxOccurs="1"

SDCGetLocationsResponse / Expedited / Commitment / Location / COT

Optional

Cut-off Time

String

minOccurs="0" maxOccurs="1"

SDCGetLocationsResponse / Expedited / Commitment / Location / FacType

Optional

Facility Type.

Valid Values:

“POST OFFICE”

“PRIORITY MAIL EXPRESS COLLECTION BOX”

“AIR MAIL FACILITY”

String

minOccurs="0" maxOccurs="1"

SDCGetLocationsResponse / Expedited / Commitment / Location / Street

Optional

Facility Street

String

minOccurs="0" maxOccurs="1"

SDCGetLocationsResponse / Expedited / Commitment / Location / City

Optional

Facility City

String

minOccurs="0" maxOccurs="1"

SDCGetLocationsResponse / Expedited / Commitment / Location / State

Optional

Facility State

String

minOccurs="0" maxOccurs="1"

SDCGetLocationsResponse / Expedited / Commitment / Location / ZIP

Optional

Facility Zip Code

String

minOccurs="0" maxOccurs="1"

SDCGetLocationsResponse / Expedited / Commitment / Location / IsGuaranteed

Optional

Indicates if Guarantee is offered.

Valid Values

“1” = Guaranteed

“2” = No Guarantee

“3” = Temporary No Guarantee

String

minOccurs="0" maxOccurs="1"

Enumeration

· 3

SDCGetLocationsResponse / Expedited / ExpeditedMessage

Optional

Holds a message code value for the customer explaining their delivery date when certain conditions are met:

Valid Message Codes

“1” = Over 200 Results

“1001” = Destination Type not valid for APO/FPO/DPO Zip

String

minOccurs="0" maxOccurs="1"

Enumeration

1
1001

SDCGetLocationsResponse / Expedited / ExpeditedTransMsg

Optional, repeating up to unbounded times

Groups Priority Mail Express transportation messaging

(Group)

minOccurs="0" maxOccurs="unbounded"

SDCGetLocationsResponse / Expedited / ExpeditedTransMsg / MsgCode

Optional

Priority Mail Express transportation messaging code

Valid Message Codes

“TM100” = This is a Military/Embassy specific ZIP Code for an APO/FPO/DPO(Air/Army Post Office, Fleet Post Office or Diplomatic Post Office)

“TM103” = Your shipment may be delayed due to transportation issues.

String

minOccurs="0" maxOccurs="1"

Enumeration

· TM100

· TM103

SDCGetLocationsResponse / Expedited / ExpeditedTransMsg /Msg

Optional

Priority Mail Express transportation messaging text.

For example:<Msg>Your shipment may be delayed due to transportation issues.</Msg>

String

minOccurs="0" maxOccurs="1"

SDCGetLocationsResponse / NonExpedited

Optional

Groups Non-Expedited Mail Class elements

(appears where applicable: SDCGetLocationsRequest[MailClass=0])

*Note: If this is a Hold for Pickup section then all elements from SDCGetLocationsResponse/NonExpedited/EAD through SDCGetLocationsResponse/NonExpedited/NonExpeditedExceptions/ NonExpeditedWTMsg will not be returned.

(Group)

minOccurs="0" maxOccurs="unbounded"

SDCGetLocationsResponse / NonExpedited / MailClass

Optional

Mail Class.

String

minOccurs="0" maxOccurs="1"

SDCGetLocationsResponse / NonExpedited / NonExpeditedDestType

Optional

Destination Type.

Valid Values

“1”	PO-Addressee - Street
“2”	PO-Addressee - PO Box
“3”	HFPU

String

minOccurs="0" maxOccurs="1"

Enumeration

· 1

· 2

· 3

SDCGetLocationsResponse / NonExpedited / EAD

Optional

Effective Acceptance Date.

String

minOccurs="0" maxOccurs="1"

SDCGetLocationsResponse / NonExpedited / SvcStdDays

Optional

Service Standard Days.

String

minOccurs="0" maxOccurs="1"

SDCGetLocationsResponse / NonExpedited / SchedDlvryDate

Optional

Scheduled Delivery Date.

String

minOccurs="0" maxOccurs="1"

SDCGetLocationsResponse / NonExpedited / HFPU

Optional, repeating up to one time

Groups Hold for Pickup information. If not present, then a HFPU Service Standard is not available.

(Group)

minOccurs="0" maxOccurs="1"

SDCGetLocationsResponse / NonExpedited / HFPU / EAD

Optional

Effective Acceptance Date.

String

minOccurs="0" maxOccurs="1"

SDCGetLocationsResponse / NonExpedited / HFPU / COT

Optional

Cut-off Time.

String

minOccurs="0" maxOccurs="1"

SDCGetLocationsResponse / NonExpedited / HFPU / ServiceStandard

Optional, repeating up to one time

Groups Hold for Pickup Service Standard Elements.

(Group)

minOccurs="0" maxOccurs="2"

SDCGetLocationsResponse / NonExpedited / HFPU / ServiceStandard / SvcStdMsg

Optional

Service Standard Message.

String

minOccurs="0" maxOccurs="1"

SDCGetLocationsResponse / NonExpedited / HFPU / ServiceStandard / SvcStdDays

Optional

Service Standard Days.

String

minOccurs="0" maxOccurs="1"

SDCGetLocationsResponse / NonExpedited / HFPU / ServiceStandard / Location

Optional, repeating up to 40 times

Groups Hold for Pickup Location information.

(Group)

minOccurs="0" maxOccurs="40"

SDCGetLocationsResponse / NonExpedited / HFPU / ServiceStandard / Location / SchedDlvryDate

Optional

Scheduled Delivery Date.

String

minOccurs="0" maxOccurs="1"

SDCGetLocationsResponse / NonExpedited / HFPU / ServiceStandard / Location / NonDeliveryDays

Optional

Non-Delivery Days.

String

minOccurs="0" maxOccurs="40"

SDCGetLocationsResponse / NonExpedited / HFPU / ServiceStandard / Location / RAUName

Optional

RAU Name.

String

minOccurs="0" maxOccurs="1"

SDCGetLocationsResponse / NonExpedited / HFPU / ServiceStandard / Location / Street

Optional

RAU Street Address.

String

minOccurs="0" maxOccurs="1"

SDCGetLocationsResponse / NonExpedited / HFPU / ServiceStandard / Location / ZIP

Optional

Facility Zip Code.

String

minOccurs="0" maxOccurs="1"

SDCGetLocationsResponse / NonExpedited / HFPU / ServiceStandard / Location / CloseTimes

Optional

Groups Close times by day of the week for Hold for Pickup location.

(Group)

minOccurs="0" maxOccurs="1"

SDCGetLocationsResponse / NonExpedited / HFPU / ServiceStandard / Location / CloseTimes / M

Optional

Close Time for Monday.

String

minOccurs="0" maxOccurs="1"

SDCGetLocationsResponse / NonExpedited / HFPU / ServiceStandard / Location / CloseTimes / Tu

Optional

Close Time for Tuesday.

String

minOccurs="0" maxOccurs="1"

SDCGetLocationsResponse / NonExpedited / HFPU / ServiceStandard / Location / CloseTimes / W

Optional

Close Time for Wednesday.

String

minOccurs="0" maxOccurs="1"

SDCGetLocationsResponse / NonExpedited / HFPU / ServiceStandard / Location / CloseTimes / Th

Optional

Close Time for Thursday.

String

minOccurs="0" maxOccurs="1"

SDCGetLocationsResponse / NonExpedited / HFPU / ServiceStandard / Location / CloseTimes / F

Optional

Close Time for Friday.

String

minOccurs="0" maxOccurs="1"

SDCGetLocationsResponse / NonExpedited / HFPU / ServiceStandard / Location / CloseTimes / Sa

Optional

Close Time for Saturday.

String

minOccurs="0" maxOccurs="1"

SDCGetLocationsResponse / NonExpedited / HFPU / ServiceStandard / Location / CloseTimes / Su

Optional

Close Time for Sunday.

String

minOccurs="0" maxOccurs="1"

SDCGetLocationsResponse / NonExpedited / HFPU / ServiceStandard / Location / CloseTimes / H

Optional

Close Time for Holiday.

String

minOccurs="0" maxOccurs="1"

SDCGetLocationsResponse / NonExpedited / HFPU / ServiceStandard / Location / NonExpeditedExceptions

Optional

Groups Hold for Pickup Location Exception Elements.

(Group)

minOccurs="0" maxOccurs="1"

SDCGetLocationsResponse / NonExpedited / HFPU / ServiceStandard / Location / NonExpeditedExceptions / NonExpeditedMsg

Optional

Additional exception messaging.

Valid Message Codes

“00133” = SDD Cannot be Calculated.

String

minOccurs="0" maxOccurs="unbounded"

Enumeration

· 00133

SDCGetLocationsResponse / NonExpedited / HFPU / ServiceStandard / Location / City

Optional

RAU City.

String

minOccurs="0" maxOccurs="1"

SDCGetLocationsResponse / NonExpedited / HFPU / ServiceStandard / Location / State

Optional

RAU State.

String

minOccurs="0" maxOccurs="1"

SDCGetLocationsResponse / NonExpedited / HFPU / HFPUGlobalExcept

Optional

Groups Hold for Pickup Exception Elements.

(Group)

minOccurs="0" maxOccurs="1"

SDCGetLocationsResponse / NonExpedited / HFPU / HFPUGlobalExcept / PostCOT

Optional

Indicates if the mailpiece arrived after the Cut-Off Time.

String

minOccurs="0" maxOccurs="1"

SDCGetLocationsResponse / NonExpedited / HFPU / HFPUGlobalExcept / OverMaxResults

Optional

Indicates if more than the number of returned Hold for Pickup locations was found.

String

minOccurs="0" maxOccurs="1"

SDCGetLocationsResponse / NonExpedited / HFPU / HFPUGlobalExcept / NoHFPULocInd

Optional

Indicates if there were no locations found in the RAU that support Hold for Pickup

String

minOccurs="0" maxOccurs="1"

SDCGetLocationsResponse / NonExpedited / HFPU / HFPUGlobalExcept / NonExpeditedWTMsg

Optional

Additional exception messaging.

Valid Message Codes

00133	SDD Cannot be Calculated
00135	SSD lists OD Pair but is missing the Service Standard

String

minOccurs="0" maxOccurs="unbounded"

Enumeration

· 00133

· 00135

SDCGetLocationsResponse / NonExpedited / HFPUGlobalExcept / NonExpeditedTransMsg

Optional, repeating up to unbounded times

Groups Non-Expedited Mail transportation messaging.

(Group)

minOccurs="0" maxOccurs="unbounded"

SDCGetLocationsResponse / NonExpedited / HFPUGlobalExcept / NonExpeditedTransMsg / MsgCode

Optional

Non-Expedited Mail transportation messaging code.

String

minOccurs="0" maxOccurs="1"

SDCGetLocationsResponse / NonExpedited / HFPUGlobalExcept / NonExpeditedTransMsg /

Optional, repeating up to unbounded times

Non-Expedited transportation messaging text.

String

minOccurs="0" maxOccurs="unbounded"

SDCGetLocationsResponse / NonExpedited / NonExpeditedExceptions / NonExpeditedTransMsg/

MsgCode

Optional

Groups Non-Expedited transportation messaging.

Valid Message Code

“TM103” = Your shipment may be delayed due to transportation issues.

(Group)

minOccurs="0" maxOccurs="1”

Enumeration

· TM103

SDCGetLocationsResponse / NonExpedited / NonExpeditedExceptions / NonExpeditedTransMsg / Msg

Optional

Non-Expedited transportation messaging code.

For example:<Msg>Your shipment may be delayed due to transportation issues.</Msg>

String

minOccurs="0" maxOccurs="1"

SDCGetLocationsResponse

Required

(Alias)

2.3.1 Sample Response

Response: SDCGetLocations:

<OriginCity>SAINT LOUIS</OriginCity>

<DestCity>GREENBELT</DestCity>

<FacType>POST OFFICE</FacType>

<Street>55 GRASSO PLZ</Street>

<City>SAINT LOUIS</City>

</Location>

</Commitment>

<FacType>POST OFFICE</FacType>

<Street>55 GRASSO PLZ</Street>

<City>SAINT LOUIS</City>

</Location>

</Commitment>

</Expedited>

</NonExpedited>

</NonExpedited>

</NonExpedited>

</NonExpedited>

</SDCGetLocationsResponse>