Locator package xml developers guide by Michael Parkin

Locator Package - XML

1/3/2011

Locator Package XML Developers Guide July 13, 2015

ÂŠ 2012 United Parcel Service of America, Inc. served. Confidential and Proprietary

All Rights Re-

Locator Package XML

07/13/2015

Notice In all communications with UPS concerning this document, please refer to the document date located on the cover. Copyright The use, disclosure, reproduction, modification, transfer, or transmittal of this work for any purpose in any form or by any means without the written permission of United Parcel Service is strictly prohibited. © Copyright 2015 United Parcel Service of America, Inc. All Rights Reserved. Trademarks UPS Online® is a registered trademark of United Parcel Service of America, Inc. All other trademarks are the property of their respective owners. Some of the UPS corporate applications use U.S. city, state, and postal code information obtained by United Parcel Service of America, Inc. under a non-exclusive license from the United States Postal Service.

Page 2

Locator Package XML

07/13/2015

Table of Contents Locator Package XML Developers Guide ........................................................................................................................... 1 January 05, 2015 ............................................................................................................................................................... 1 1.1 Important Information ................................................................................................................................................... 6 1.2 Welcome to the UPS API Developer's Guides.............................................................................................................. 7 1.2.1 What's New for Locator .......................................................................................................................................... 8 Jan 2015 ............................................................................................................................................................................. 8 July 2014 .......................................................................................................................................................................... 10 1.2.2 How to Use this Guide ........................................................................................................................................... 13 1.3 Required Steps for Integrating .................................................................................................................................... 14 1.4 Planning Your Applications for XML ........................................................................................................................ 14 1.4.1 UPS Developer API Applications ......................................................................................................................... 15 1.4.2 Licensing the UPS Developer APIs ...................................................................................................................... 18 1.4.2.1 Branding Requirements ................................................................................................................................... 18 1.4.3 Developing Client Applications for Developer APIs .......................................................................................... 18 1.4.3.1 Microsoft Visual Studio ................................................................................................................................... 19 1.4.3.2 Java Standard Edition and Enterprise Edition............................................................................................... 19 1.4.3.3 Open Source ..................................................................................................................................................... 19 1.4.4 Getting Technical Support .................................................................................................................................... 19 1.4.5 Testing and Deploying Applications .................................................................................................................... 23 1.4.6 Keeping Up-to-Date ............................................................................................................................................... 24 1.5 UPS Developer API Technologies for XML ............................................................................................................... 24 1.5.1 Hypertext Transfer Protocol and an Encrypted Channel ................................................................................. 24 1.5.2 Working with HTTP and an Encrypted Channel in Application Programs ................................................... 27 1.6.2.1 Microsoft Visual Studio ................................................................................................................................... 28 1.5.2.2 Java Standard Edition and Enterprise Edition............................................................................................... 29 1.5.2.3 Open Source ..................................................................................................................................................... 30 1.5.2.4 Certificate Changes and Renewals .................................................................................................................. 31 1.5.3 Extensible Markup Language (XML).................................................................................................................. 33

Page 3

Locator Package XML

07/13/2015

1.5.4 Working with XML in Application Programs .................................................................................................... 37 1.5.4.1 Microsoft Visual Studio ................................................................................................................................... 37 1.5.4.2 Java Standard Edition and Enterprise Edition............................................................................................... 40 1.5.4.3 Open Source ..................................................................................................................................................... 41 1.6 Understanding XML Locator Services ....................................................................................................................... 44 1.6.1 Types of Requests................................................................................................................................................... 44 1.7 Understanding Mileage Bands and Prioritization in the Global Locator ............................................................... 44 1.7.1 Countries with the UPS Store ............................................................................................................................... 44 1.8 The Locator XML Reference ..................................................................................................................................... 48 1.8.1 Describing UPS API Messages.............................................................................................................................. 48 1.8.2 Authenticating Client Applications ...................................................................................................................... 49 1.8.2.1 AccessRequest .................................................................................................................................................. 49 1.8.3 Locator Service ...................................................................................................................................................... 50 1.8.3.1 LocatorRequest ................................................................................................................................................ 50 1.8.3.2 LocatorResponse .............................................................................................................................................. 52 1.8.4 Locator Request ..................................................................................................................................................... 54 1.8.5 Locator Response ................................................................................................................................................... 76 1.9 Customer Integration Environment.......................................................................................................................... 104 1.9.1 System Availability .............................................................................................................................................. 104 1.9.2 Server Availability Check ................................................................................................................................... 104 Appendix A - Accessing Tech Support (US Site Example) ....................................................................................... 105 Appendix B – Locator Error Codes ................................................................................................................................ 109 XML Errors............................................................................................................................................................... 111 Appendix C – Service Level Options and Location Types ............................................................................................ 112 Appendix D – Business Classification Codes for UPS Access Point™ s ...................................................................... 115 Appendix E – Service Offering Code for UPS Access Point™ s .................................................................................. 116 Appendix F - Frequently Asked Questions: Locator ..................................................................................................... 116 Appendix G – Additional Services .................................................................................................................................. 120 Appendix H – Program Types ......................................................................................................................................... 121 Appendix I – Location Options........................................................................................................................................ 121

Page 4

Locator Package XML

07/13/2015

Page 5

Locator Package XML

07/13/2015

1.1 Important Information UPS Developer APIs Your development of an application using the UPS Web Service APIs are governed by the UPS Technology Agreement or UPS Customer Technology Agreement you entered into with UPS. The following are key legal requirements from these agreements for the UPS Web Service APIs. For more information on all requirements for the UPS Web Service APIs, please refer to the UPS Technology Agreement or the Customer Technology Agreement.

Key Legal Requirements for UPS Developer APIs Permitted Territories This document can only be used in the countries listed in Exhibit C of the UPS Technology Agreement or UPS Customer Technology Agreement.

Use The application must not be designed to allow distribution of information received through the UPS Web Service APIs to third parties, other than to persons having a bona fide interest in such information (e.g., the shipper, receiver or the third party payer).

Consent to Use of UPS Mark  

All screens or forms generated by your application including information received through the UPS Web Service APIs must include (1) the UPS Mark positioned in reasonable proximity to the Information and of an appropriate size to readily identify the source of the Information as UPS and (2) the following language at the bottom of every screen that displays the UPS Mark: "UPS, the UPS brand mark, and the Color Brown are trademarks of United Parcel Service of America, Inc. All Rights Reserved". Except as set forth in the preceding sentence, you have no right to use the UPS Mark without the prior written approval of UPS.

Page 6

Locator Package XML

07/13/2015



You shall not use the UPS Mark in association with any third party trademarks in a manner that might suggest co-branding or otherwise create potential confusion as to source or sponsorship of the application, or ownership of the UPS Mark.



The UPS Mark shall be used only as provided by UPS electronically or in hard copy form. The UPS Mark may not be altered in any manner, including proportions, colors, elements, etc., or animated, morphed or otherwise distorted in perspective or dimensional appearance.



The UPS Mark may not be combined with any other symbols, including words, logos, icons, graphics, photos, slogans, numbers or other design elements. A minimum amount of empty space must surround the UPS Mark separating it from any other object, such as type, photography, borders, edges, etc. The required area of empty space around the UPS Mark must be 1/3x, where x equals the height of the UPS Mark.

Copyright and Proprietary Notice In your application and any POD Letters you prepare you must include a prominent reproduction of UPS’s copyright and proprietary notices in a form and format specified by UPS (See Copyright Section of this document).

Display of Information The application must not display information concerning any other provider of shipping services or such other shipping services on any page, whether comprising one or more frames, displaying information your application receives from the UPS Web Service APIs. Your application must present all data within each field received through the UPS Web Service APIs without amendment, deletion or modification of any type.

1.2 Welcome to the UPS API Developer's Guides Welcome to the UPS API Developer's Guides. This guide provides the information you need to begin using UPS Developer APIs. UPS Developer APIs offer a fast and convenient way to access UPS service information using the Internet. With these Developer APIs, UPS lets you easily incorporate UPS technology in your own applications or your own web site. Your users— running your applications or visiting your web site—can have up-to-the-minute access to UPS services. © 2015 United Parcel Service of America, Inc. All Rights Reserved. Confidential and Proprietary

Page 7

Locator Package XML

07/13/2015

1.2.1 What's New for Locator July 2015 Release Features New Low Cost Offering (LCO) Service  Supported by UPS Access Point locations in BE, NL, LU and FR.  The message automatically included in the response XML will be: o Note: UPS Access PointTM Economy Packages will be [picked up / collected] the next business day. Accepts Restricted Articles  Filter applies to UPS Access Point locations  New Service Offering Code 013

Jan 2015 Release Features This release incorporates the ability to search UPS Access Point™ locations based on various criteria and parameters. -

One can search using Sort Criteria , Open Time Criteria Ability to return promotion link, Location Image, Featured Rank, Open24HoursIndicator for individual locations where applicable. One can search based on service offering.

New Service offering code (must be used with request option code 64)

Page 8

Locator Package XML

End Point Service Offering Codes 012

          

07/13/2015

Detailed description The location will have the capability to filter it with Pay At Store feature.

New Locator Request Elements /LocatorRequest/OriginAddress/AddressKeyFormat/SingleLineAddress /LocatorRequest/LocationSearchCriteria/EnhancedSearchOption /LocatorRequest/LocationSearchCriteria/EnhancedSearchOption/Code /LocatorRequest/LocationSearchCriteria/EnhancedSearchOption/Description /LocatorRequest/LocationSearchCriteria/AccessPointSearch/SearchIdCriteria /LocatorRequest/LocationSearchCriteria/OpenTimeCriteria /LocatorRequest/LocationSearchCriteria/OpenTimeCriteria/DayOfWeekCode /LocatorRequest/LocationSearchCriteria/OpenTimeCriteria/FromTime /LocatorRequest/LocationSearchCriteria/OpenTimeCriteria/ToTime /LocatorRequest/SortCriteria /LocatorRequest/SortCriteria/SortType

New Locator Response Elements

Page 9

Locator Package XML

       

07/13/2015

/LocatorResponse/SearchResults/DropLocation/OperatingHours/StandardHours/DayOfWeek/Open24HoursIndicator /LocatorResponse/SearchResults/DropLocation/LocationImage /LocatorResponse/SearchResults/DropLocation/LocationImage/SecureURL /LocatorResponse/SearchResults/DropLocation/LocationImage/NonSecureURL /LocatorResponse/SearchResults/DropLocation/LocationNewIndicator /LocatorResponse/SearchResults/DropLocation/PromotionalLinkURL /LocatorResponse/SearchResults/DropLocation/FeaturedRank /LocatorResponse/SearchResults/DropLocation/WillCallLocationIndicator

July 2014 Release Features This release incorporates the ability to search UPS Access Point™ locations based on various criteria and parameters. -

One can search UPS Access Point™ s based on Shipping, DCR/DCO availability. One can search and sort Click and Collect locations. Ability to return promotion information for individual locations where applicable. One can search based on service offering as follows.

New Service offering codes (must be used with request option code 64) End Point Service Offering Codes

Detailed description

Page 10

Locator Package XML

001

002 003

004 005 006

007 008 009

010

011  

07/13/2015

A commercial business sends a shipment to an authorized retail destination where it is held for the final consignee to claim A shipment that failed the first delivery at the consignees address, could not be redirected to a neighbor, and was redirected by UPS to a nearby UPS Access Point™ Click and Collect Consumer to consumer shipping option for shipments that are dropped off at a UPS Access Point™ and sent to a UPS Access Point™ for the final consignee to claim UPS Access Point™ allows customers to only Pickup/Collect shipments UPS Access Point™ allows customer to only Drop Off shipments Spare parts logistics for service engineers & technicians through the UPS Access Point™ network for picking up and dropping off parts at convenient locations The UPS Access Point™ is open early to allow consignees to Pick-up/Collect of packages UPS Access Point™ can accept packages that already have an acceptable ups shipping label with tracking number When a delivery change request to a retail location has been completed by Delivery Change Option (DCO) in Mychoice preferences and Delivery Change Request (DCR) at ups.com The location will have the capability to accept monies for Cash on Delivery (COD). and International Cash on Delivery (ICOD) shipments to the UPS Access Point™ locations

New Locator Request Elements 

/Locato rRequest/L ocationSea rchCriteria/Ac cessPoi ntSearc h/Inclu

deCriteria /LocatorRequest/LocationSearchCriteria/AccessPointSearch/IncludeCriteria/SearchFilter /LocatorRequest/LocationSearchCriteria/AccessPointSearch/IncludeCriteria/SearchFilter/DCRIndicator

Page 11

Locator Package XML

      

07/13/2015

/LocatorRequest/LocationSearchCriteria/AccessPointSearch/IncludeCriteria/SearchFilter/ShippingAvailabilityIndica tor /LocatorRequest/LocationSearchCriteria/AccessPointSearch/IncludeCriteria/SearchFilter/ShipperPreparationDelay /LocatorRequest/LocationSearchCriteria/AccessPointSearch/IncludeCriteria/SearchFilter/ClickAndCollectSortWith Distance /LocatorRequest/LocationSearchCriteria/AccessPointSearch/IncludeCriteria/ServiceOfferingList /LocatorRequest/LocationSearchCriteria/AccessPointSearch/IncludeCriteria/ServiceOfferingList/ServiceOffering /LocatorRequest/LocationSearchCriteria/AccessPointSearch/IncludeCriteria/ServiceOfferingList/ServiceOffering/C ode /LocatorRequest/LocationSearchCriteria/AccessPointSearch/IncludeCriteria/ServiceOfferingList/ServiceOffering/D escription

New Locator Response Elements             

/LocatorResponse/SearchResults/DropLocation/PromotionInformation /LocatorResponse/SearchResults/DropLocation/PromotionInformation/Locale /LocatorResponse/SearchResults/DropLocation/PromotionInformation/Promotion /LocatorResponse/SearchResults/DropLocation/ServiceOfferingList /LocatorResponse/SearchResults/DropLocation/ServiceOfferingList/ServiceOffering /LocatorResponse/SearchResults/DropLocation/ServiceOfferingList/ServiceOffering/Code /LocatorResponse/SearchResults/DropLocation/ServiceOfferingList/ServiceOffering/Description /LocatorResponse/SearchResults/DropLocation/AccessPointInformation/Availability /LocatorResponse/SearchResults/DropLocation/AccessPointInformation/Availability/ShippingAvailability /LocatorResponse/SearchResults/DropLocation/AccessPointInformation/Availability/ShippingAvailability/Availabil ityIndicator /LocatorResponse/SearchResults/DropLocation/AccessPointInformation/Availability/ShippingAvailability/Unavaila bleReason /LocatorResponse/SearchResults/DropLocation/AccessPointInformation/Availability/ShippingAvailability/Unavaila bleReason/Code /LocatorResponse/SearchResults/DropLocation/AccessPointInformation/Availability/ShippingAvailability/Unavaila bleReason/Description

Page 12

Locator Package XML

   

07/13/2015

/LocatorResponse/SearchResults/DropLocation/AccessPointInformation/Availability/DCRAvailability /LocatorResponse/SearchResults/DropLocation/AccessPointInformation/Availability/DCRAvailability/AvailabilityI ndicator /LocatorResponse/SearchResults/DropLocation/AccessPointInformation/Availability/DCRAvailability/Unavailable Reason /LocatorResponse/SearchResults/DropLocation/AccessPointInformation/Availability/DCRAvailability/Unavailable Reason/Code /LocatorResponse/SearchResults/DropLocation/AccessPointInformation/Availability/DCRAvailability/Unavailable Reason/Description

New Error Code 

335059=AccessPointSearch/IncludeCriteria/SearchFilter/ShipperPreparationDelay exceeds maximum value.

Appendix D for business classification code

1.2.2 How to Use this Guide If you are an experienced developer, you can begin developing applications quickly after reviewing "Required Steps for Integrating." If you would like a more step-by-step guide to developing and deploying the Developer APIs, "Planning Your Applications" provides advice and describes options for developing and deploying applications and web sites that use UPS Developer APIs. The "UPS Developer API Technologies" section explains key technologies on which the Developer APIs rely. That section also includes hints for using those technologies in various software development environments. If you would like to learn more about what the UPS API covered in this guide can do for your applications, refer to the section on understanding the UPS API Services in this guide. A complete technical reference to the Developer API covered in this guide is found in the API Reference section with details for the programming interfaces. © 2015 United Parcel Service of America, Inc. All Rights Reserved. Confidential and Proprietary

Page 13

Locator Package XML

07/13/2015

Additional material, including reference tables and lists, may be found in the appendices.

1.3 Required Steps for Integrating The required steps for integrating the UPS APIs are listed here for UPS XML Services.

UPS XML Services 1. 2. 3. 4. 5. 6. 7.

Review the UPS Technology Agreement available at www.ups.com. This agreement requires that you follow certain procedures and practices in using UPS Developer APIs. Develop applications that make use of standard HTTP communications protocols, encrypted channel security, and XMLbased document representations. Add your functionality specific to your application and/or web site to the skeleton code. Test your application and/or web site using the designated UPS staging environment. If you are a UPS Ready developer, review your application with UPS. Deploy your application for your customers. Ensure the UPS Shipper Account number is added to the userâ&#x20AC;&#x2122;s profile. This can be done at myups.com.

1.4 Planning Your Applications for XML Planning is a key part of any successful development activity, and UPS Developer API applications are no exception. This section helps that planning by describing the important activities of any UPS Developer API application project. It provides

Page 14

Locator Package XML

07/13/2015

an overview of the steps required to develop applications, and it describes key factors and choices necessary to deploy those applications.

1.4.1 UPS Developer API Applications Many different types of applications can take advantage of UPS Developer APIs. Those application types include dedicated desktop applications, databases, web applications, and documents. The following figures illustrate some of the possibilities for applications using UPS Developer APIs. The only essential requirement for all of these applications is that they must have access to the Internet.

Page 15

Locator Package XML

07/13/2015

Page 16

Locator Package XML

07/13/2015

Page 17

Locator Package XML

07/13/2015

The UPS Developer APIs can be implemented withal of these types of applications and many others. Virtually any software that needs instant, up-to date access to UPS services can take advantage of UPS Developer APIs.

1.4.2 Licensing the UPS Developer APIs As part of the UPS Technology Agreement, users of the APIs have certain obligations that are spelled out within the service agreement and its exhibits. Regardless of the manner in which the UPS Developer APIs are integrated into your specific e-commerce web site or enterprise application, you must adhere to appropriate usage requirements.

1.4.2.1 Branding Requirements UPS should receive attribution and branding in all applications (including websites and software applications) that use the Developer APIs. No End User, Third Party Developer or Access User should be permitted to use the Developer APIs without providing branded recognition to UPS. Your use of the UPS logo can in no way imply endorsement, sponsorship or certification of your ecommerce web site or enterprise application by UPS. You are not allowed to use or alter the information returned by the UPS Developer APIs in a way that misrepresents the information or the functionality of the service.

1.4.3 Developing Client Applications for Developer APIs When you develop software that uses the UPS Developer APIs, you are building a client application. Because the UPS Developer APIs rely on standard Internet based technology, you can develop those applications using a wide variety of software development platforms, including Microsoft's Visual Studio, the Java Standard Edition and Enterprise Edition distributions, and many open source projects. This section introduces important technologies available in each of these development environments. Later sections of this document include more details on using each platform. Look for the icons in the left margin, which identify information relevant to a particular development environment.

Page 18

Locator Package XML

07/13/2015

1.4.3.1 Microsoft Visual Studio Developers using the Microsoft Visual Studio environment can rely on the Microsoft XML Core Services (MSXML) for interacting with UPS Developer APIs. Those services include functions to help applications create requests for and interpret responses, and they include functions to manage the communications between applications and UPS.

1.4.3.2 Java Standard Edition and Enterprise Edition Java developers can find all the classes they need for UPS Developer APIs in the Java Standard Edition and Enterprise Edition distributions. The URL class in the java.net package provides the functions required for communication with UPS servers, and the Java API for XML Processing (JAXP) services let programs create requests and interpret responses from UPS.

1.4.3.3 Open Source There are a number of open source efforts that include technology useful for creating Developer API client applications; open source developers may find two particular projects to be especially helpful. The libcurl project is a library of functions that can manage the communications with UPS servers. For creating requests and interpreting responses, the xerces project provides essential functions in a variety of software languages.

1.4.4 Getting Technical Support Technical Support (U.S.) There are four channels for obtaining support for the UPS Developer Kit (UDK) APIs all of which are accessed through the UPS Developer Resource Center at the following link: http://www.ups.com/content/us/en/resources/techsupport/developercenter.html?WT.svl=SubNav Or by following these steps: 1. Go to www.UPS.com.

Page 19

Locator Package XML

07/13/2015

2. Mouse over the Support tab and select Technology Support 3. In the left navigation panel of the page select the link “Developer Resource Center”.

 Email Technical Support – available in the right hand column on the UPS Developer Resource Center web page. This is the support channel for technical support and questions regarding API integration. It is accessed by logging in to myUPS and attaching your XML Request/Response files and any other pertinent information about your integration [please see Appendix A for detailed instructions and screen shots]. UPS Email Technical Support can only support the XML Request/Response pair. They cannot consult customers and developers on how to integrate the XML into their internal or purchased software.  UPS Developer Kit Community – available in the right hand column of the UPS Developer Resource Center web page. This is a community forum for developers to answer one another’s questions and share information therefore the response times may be slower. If you have an immediate need for technical support contact UPS Email Tech Support above and they will respond within 4 business hours (see hours below). The remainder of the site contains online versions of all API developer guides and FAQs.  UPS Developer Kit Knowledge Base - available in the right hand column of the UPS Developer Resource Center web page. This is a self-service support .pdf document that can be opened or downloaded. It contains over 240 frequently asked questions about every mode and service supported by the UDK APIs. It’s also available in an online version at the UPS Developer Kit Community.  General Question Phone Support (U.S. only) – available in the right hand column of the UPS Developer Resource Center web page. Phone support is the least comprehensive support mechanism for the developer. This channel of support addresses questions about the user interface at ups.com and how to gain access to the APIs and navigate the Access Key request process. They do not provide technical support for XML Request/Response issues and questions. Those types of questions must go through Email Technical Support.

Page 20

Locator Package XML

07/13/2015

Got to ups.com and log in to myUPS.

Hover over the “Support” tab and select “Technology Support”.

On the Technology Support page select the Developer Resource Center link from the left navigation.

On the Developer Resource Center page select the “Email UPS” link in the right hand column.

5. Enter all relevant information including name, enter email address, select Support Category “Technical Support”, and select Support Topic “Developer Resource” [which identifies UPS Developer Kit APIs tech support]. Click next. 6. Scroll down to the middle of the email form and complete the fields “Your Telephone”, “Stage of Development”, “Developer Resource” which is which API you are integrating, “Attach File” where you attach your XML Request/Response Pair, and any pertinent description of the issues in the “What is your question or comment?” field. 7.

Select “Send Email” button.

8. A response is provided that explains someone from UPS will contact you. Please base the response time on the detailed information listed below about tech support hours of operation and response times. (For screen shots of this process please see Appendix A at the end of this guide.) 1st Level Email and Phone Technical Support Business Hours and Response Times: a. Hours of operation for 1st Level Email Tech Support: 8am to 8pm ET Monday through Friday. Hours of operation for 1st Level Phone Support: 7:30 am to 9pm ET Monday through Friday and 9am to 6pm ET Saturday and Sunday. The desk is closed on UPS Holidays. b. 1st Level Email Tech Support email response time is planned to be within 4 business hours of the initial request. Business hours are defined as hours of operation of the tech support desks when service technicians are working.

Page 21

Locator Package XML

07/13/2015

This means if you submit an email tech support request after business hours the 4 hour response clock will not begin until the following morning at 7:30am ET M-F and 9am ET Saturday and Sunday (UPS Holidays excluded). PLEASE NOTE: If you are sent an email from 1st Level Email Tech Support stating your case log # has been escalated, the 24 hour planned response clock starts from the time you receive the email from 1st Level Email Tech Support (provided the Escalation Support desk is open). If not, then the clock will begin when the Escalation Support desk opens.

Escalation Support Business Hours and Response Times: c. Hours of operation: 8am to 8pm ET Monday through Friday. The desk is closed weekends and on UPS Holidays. d.

Escalation Support desk response time is planned to be within 24 hours during normal hours of operation.

This means if your case log is escalated at 8:30pm on Friday, you will not receive an email response from the Escalation Support desk at the latest until Monday at 8pm (Saturdays, Sundays, and Holidays are excluded). Response times are from the time the case log was escalated plus 24 hours which do NOT include the weekends or UPS holidays. There may be some scenarios when the tech support team is meeting planned response times but it appears as if it’s taking too long. Below is a brief example where the planned response time is met but nothing happened over the weekend. Example – Customer submits tech support email at 8am on Friday. The clock for 4 hour response will not begin until 8am ET for the 1st level tech support team. They respond within 4 hours at 11:30am EST that same Friday stating the case log has been escalated and providing the case log #. The escalation desk receives the case log at 11:30am ET. They begin work on evaluating the problem and have planned to either update the customer within 24 hours or solve the problem within 24 hours. Either way, the customer will hear from the escalation desk within 24 hours with some type of disposition on their case log. The esca-

Page 22

Locator Package XML

07/13/2015

lation desk clock begins when they receive a case log from 1st level tech support during business hours, M-F 8am to 8pm ET. In this case, the clock begins at 11:30am ET if the escalation desk does not have an answer by 8pm ET on Friday the desk has until 11:30am ET the following Monday to either provide a resolution or a status update to the customer on the case log. The Escalation Desk continues work on the case log on Monday beginning at 8am ET. They receive resolution at 1030am ET Monday and send the resolution to the customer. The Escalation Desk has met their 24 hour planned response time.

Technical Support (Non-U.S.) For Non-US countries supported by the UPS Developer Kit follow the instructions in Appendix A. However, to get to the UPS Developer Resource Center page please complete the following steps. 1.

Select the Support tab and in the drop-down select Technology Support.

Select from the left navigation the “UPS Developer Resource Center” link.

Continue with email form as described above.

Please also note that email response times for non-US requests vary. Translations and escalations may delay the process. If a quicker response is required, please access the US web site directly and complete an email technical support form from the US web site.

1.4.5 Testing and Deploying Applications UPS maintains a special environment to support testing and staging of applications that rely on UPS Developer APIs. This environment is called the Customer Integration Environment (CIE) and allows developers test and debug their applications by simulating transactions with UPS. The CIE site responds to requests just like the UPS production environment; however, it does not initiate actual UPS business services. © 2015 United Parcel Service of America, Inc. All Rights Reserved. Confidential and Proprietary

Page 23

Locator Package XML

07/13/2015

For example, if you send a shipping request to the UPS production site, a UPS driver may show up at your location expecting to pick up a package (and expecting payment for the service.) Sending the shipping request to CIE will avoid this problem. CIE integration testing for the Locator tool is only supported for specific countries and cities as follows  Countries = DE, CA, MX and US  Cities = Neuss, Toronto, Mexico City and Atlanta

1.4.6 Keeping Up-to-Date As UPS adds new services and features, Developer API will evolve, offering more features and service benefits. Once you register to use UPS Developer API, you can return to the UPS Support area of ups.com for the latest updated information about UPS Developer API.   

It is essential that an accurate e-mail address for your company be maintained. In addition, UPS recommends that you complete the secondary contact information to ensure that your organization receives the latest updates. You should update your profile when changes or responsibilities for the UPS Developer API change within your company.

To change your profile information, go to UPS.com and log in using your MyUPS.com User ID.

1.5 UPS Developer API Technologies for XML The foundation technologies for the UPS Developer APIs are the same underlying technologies in use on the Internet today. They include the Hypertext Transfer Protocol (HTTP) with an encrypted channel and the Extensible Markup Language (XML). Because these technologies are critical to the Internet, most software development APIs provides many powerful features that make it easy for application programs to use them. This section provides a quick introduction to the technologies and to the API that can support them.

Page 24

Locator Package XML

07/13/2015

Today's Internet supports a wide variety of applications including email, instant messaging, web browsing, and voice communications. All of these applications have a well-defined set of rules that determines how they communicate. Those rules are known as protocols. As an Internet application themselves, the UPS Developer APIs also rely on protocols to set the rules for their communications. The primary protocol for UPS Developer APIs is the hypertext transfer protocol, or HTTP. HTTP is a relatively simple protocol. An application that wants to use a Developer API acts as an HTTP client. It sends its request to UPS as part of an HTTP POST message. UPS servers reply to each request using an HTTP response message.

As part of the POST message, client applications indicate the type of content the message contains using an HTTP Content-Type header. For UPS Developer APIs, that content type should be application/x-www-form-urlencoded. (Presently, Version 1.1 is supported) ÂŠ 2015 United Parcel Service of America, Inc. All Rights Reserved. Confidential and Proprietary

Page 25

Locator Package XML

07/13/2015

In many cases the UPS Developer API exchanges information that should be kept private. To protect confidential information, the Developer API relies on an encrypted channel in addition to HTTP. When two systems communicate using an encrypted channel, the channel encrypts all information they exchange. Note: SSLv3 is not supported.

Page 26

Locator Package XML

07/13/2015

1.5.2 Working with HTTP and an Encrypted Channel in Application Programs UPS Developer APIs are not the only Internet services that rely on the HTTP and an encrypted channel. Both protocols, in fact, were originally developed for web browsing, and they provide the foundation for the majority of Internet applications. Because HTTP and encrypted channels are so common, software development API make using these protocols very simple. Because HTTP and encrypted channels are commonly used for web browsing, software development API often rely on the same notation and abbreviations as standard web browsers. In particular, most API identify a specific service (such as a UPS Developer API) using a Uniform Resource Locator (URL). URLs begin with an abbreviation of the communication protocol. For a UPS Developer API that abbreviation will always be "https" to indicate HTTP and an encrypted channel. The protocol abbreviation is followed by a colon, two slashes, and the name of a server. Additional information about the specific service can follow the server name; it is written like the path to a file in a directory, with slashes separating individual folders. Figure 3 shows how a URL combines these individual components.

Page 27

Locator Package XML

07/13/2015

Figure 3. URLs identify communication protocols, servers, and specific services.

The subsections that follow provide brief introductions to using HTTP and an encrypted channel with various software development tools, including Microsoft Visual Studio, Java Standard and Enterprise Edition, and popular open source environments.

1.6.2.1 Microsoft Visual Studio The Microsoft Visual Studio environment includes many tools, classes, and libraries that simplify the use of HTTP and encrypted channel protocols. A very convenient set of tools are included in the Microsoft XML Core Services (MSXML). The following code fragment shows how a Visual Basic program can send a request and retrieve the response. To keep the example as simple as possible, no exception handling is included in the figure. Production software should, of course, appropriately handle all exceptions ÂŠ 2015 United Parcel Service of America, Inc. All Rights Reserved. Confidential and Proprietary

Page 28

Locator Package XML

07/13/2015

Figure 4. Visual Basic programs can use features of the MSXML tools to send and receive messages using HTTP and an encrypted channel.

1.5.2.2 Java Standard Edition and Enterprise Edition In a Java SE or EE environment, the URL class in the java.net package provides a convenient way to manage HTTP and encrypted channel communications. Figure 5 contains a small code fragment that demonstrates the use of this class. As above, the fragment doesn't include exception handling that should be inherent in any production software.

Page 29

Locator Package XML

07/13/2015

Figure 5. The URL class from the java.net package is a convenient way for Java programs to use HTTP and an encrypted channel

1.5.2.3 Open Source The libcurl project is an open source project that includes support for using HTTP and encrypted channel protocols. The fragment in Figure 6 shows how to set up libcurl to send a request using HTTP and an encrypted channel. It relies on a callback function to accept the server's response.

Figure 6. The open source libcurl library simplifies the use of HTTP and an encrypted channel.

Page 30

Locator Package XML

07/13/2015

1.5.2.4 Certificate Changes and Renewals UPS use the Chained Digital Certificates as a measure to improve security for UPS servers. Renewals of UPS.com Certificates are coordinated by UPS Security Services every year. There is a concern that some UPS Developer Kit users who store UPS Certificates internally may have issues when Certificates are renewed. It is recommended that UPS Developer Kit users not store UPS Certificates internally; however if a customer finds this necessary due to specific needs within their company, they may need to add renewed certificates to the their trust store. There are a number of ways one can add a certificate to the application. One way to obtain the proper certificate is by placing a UPS Developer Kit URL, https://onlinetools.ups.com/ups.app/xml/Locator, for example, in a browser, connect to the URL, and double-click on the "lock" on the bottom right of the window (using Internet Explorer 7). After that the steps can be followed to install the certificate. Also, in the event that the aforementioned solution does not work successfully for you we have been provided with the following certificate which should allow you to connect once it has been successfully added. You should be able to paste the following string into Notepad and save the file locally. Then, it will be necessary to have the client application reference the file so that it will know that this is the trusted certificate for making a connection to UPS. This is the Verisign Class 3 Secure Server CA - G2 certificate that the client must trust: -----BEGIN CERTIFICATE----MIIGLDCCBZWgAwIBAgIQbk/6s8XmacTRZ8mSq+hYxDANBgkqhkiG9w0BAQUFADCB wTELMAkGA1UEBhMCVVMxFzAVBgNVBAoTDlZlcmlTaWduLCBJbmMuMTwwOgYDVQQL EzNDbGFzcyAzIFB1YmxpYyBQcmltYXJ5IENlcnRpZmljYXRpb24gQXV0aG9yaXR5 IC0gRzIxOjA4BgNVBAsTMShjKSAxOTk4IFZlcmlTaWduLCBJbmMuIC0gRm9yIGF1 dGhvcml6ZWQgdXNlIG9ubHkxHzAdBgNVBAsTFlZlcmlTaWduIFRydXN0IE5ldHdv cmswHhcNMDkwMzI1MDAwMDAwWhcNMTkwMzI0MjM1OTU5WjCBtTELMAkGA1UEBhMC VVMxFzAVBgNVBAoTDlZlcmlTaWduLCBJbmMuMR8wHQYDVQQLExZWZXJpU2lnbiBU cnVzdCBOZXR3b3JrMTswOQYDVQQLEzJUZXJtcyBvZiB1c2UgYXQgaHR0cHM6Ly93

Page 31

Locator Package XML

07/13/2015

d3cudmVyaXNpZ24uY29tL3JwYSAoYykwOTEvMC0GA1UEAxMmVmVyaVNpZ24gQ2xh c3MgMyBTZWN1cmUgU2VydmVyIENBIC0gRzIwggEiMA0GCSqGSIb3DQEBAQUAA4IB DwAwggEKAoIBAQDUVo9XOzcopkBj0pXVBXTatRlqltZxVy/iwDSMoJWzjOE3JPMu 7UNFBY6J1/raSrX4Po1Ox/lJUEU3QJ90qqBRVWHxYISJpZ6AjS+wIapFgsTPtBR/ RxUgKIKwaBLArlwH1/ZZzMtiVlxNSf8miKtUUTovStoOmOKJcrn892g8xB85essX gfMMrQ/cYWIbEAsEHikYcV5iy0PevjG6cQIZTiapUdqMZGkD3pz9ff17Ybz8hHyI XLTDe+1fK0YS8f0AAZqLW+mjBS6PLlve8xt4+GaRCMBeztWwNsrUqHugffkwer/4 3RlRKyC6/qfPoU6wZ/WAqiuDLtKOVImOHikLAgMBAAGjggKpMIICpTA0BggrBgEF BQcBAQQoMCYwJAYIKwYBBQUHMAGGGGh0dHA6Ly9vY3NwLnZlcmlzaWduLmNvbTAS BgNVHRMBAf8ECDAGAQH/AgEAMHAGA1UdIARpMGcwZQYLYIZIAYb4RQEHFwMwVjAo BggrBgEFBQcCARYcaHR0cHM6Ly93d3cudmVyaXNpZ24uY29tL2NwczAqBggrBgEF BQcCAjAeGhxodHRwczovL3d3dy52ZXJpc2lnbi5jb20vcnBhMDQGA1UdHwQtMCsw KaAnoCWGI2h0dHA6Ly9jcmwudmVyaXNpZ24uY29tL3BjYTMtZzIuY3JsMA4GA1Ud DwEB/wQEAwIBBjBtBggrBgEFBQcBDARhMF+hXaBbMFkwVzBVFglpbWFnZS9naWYw ITAfMAcGBSsOAwIaBBSP5dMahqyNjmvDz4Bq1EgYLHsZLjAlFiNodHRwOi8vbG9n by52ZXJpc2lnbi5jb20vdnNsb2dvLmdpZjApBgNVHREEIjAgpB4wHDEaMBgGA1UE AxMRQ2xhc3MzQ0EyMDQ4LTEtNTIwHQYDVR0OBBYEFKXvCxHOwEEDo0plkEiyHOBX LX1HMIHnBgNVHSMEgd8wgdyhgcekgcQwgcExCzAJBgNVBAYTAlVTMRcwFQYDVQQK Ew5WZXJpU2lnbiwgSW5jLjE8MDoGA1UECxMzQ2xhc3MgMyBQdWJsaWMgUHJpbWFy eSBDZXJ0aWZpY2F0aW9uIEF1dGhvcml0eSAtIEcyMTowOAYDVQQLEzEoYykgMTk5 OCBWZXJpU2lnbiwgSW5jLiAtIEZvciBhdXRob3JpemVkIHVzZSBvbmx5MR8wHQYD VQQLExZWZXJpU2lnbiBUcnVzdCBOZXR3b3JrghB92f4Hz6getxB5Z/uniTTGMA0G CSqGSIb3DQEBBQUAA4GBAGN0Lz1Tqi+X7CYRZhr+8d5BJxnSf9jBHPniOFY6H5Cu OcUgdav4bC1nHynCIdcUiGNLsJsnY5H48KMBJLb7j+M9AgtvVP7UzNvWhb98lR5e YhHB2QmcQrmy1KotmDojYMyimvFu6M+O0Ro8XhnF15s1sAIjJOUFuNWI4+D6ufRf -----END CERTIFICATE----Finally, for more information on installing the latest VeriSign CA Root Certificate, please click on the links below:



https://knowledge.verisign.com/support/ssl-certificatessup-

Page 32

Locator Package XML

07/13/2015



port/index?page=content&id=SO7154&actp=search&viewlocale=en_US&searchid=130823 5124970 https://knowledge.verisign.com/support/ssl-certificatessupport/index?page=content&actp=CROSSLINK&id=AR1553 https://knowledge.verisign.com/support/ssl-certificatessupport/index?page=content&id=SO4785&actp=LIST

1.5.3 Extensible Markup Language (XML) The Extensible Markup Language (XML) is an international standard developed by the World Wide Web Consortium, the governing body for web standards and guidelines. XML provides a way to identify the structure of content within a document or, in the case of UPS Developer APIs, a message. Figure 7 shows how a simple XML message could describe a book.

Page 33

Locator Package XML

07/13/2015

Figure 7. XML identifies the structure of documents, as in this document describing a book.

As the figure illustrates, XML is a text-based format. XML messages contain regular text, though that text follows specific rules that XML defines. XML distinguishes different parts of a message with a label known as a tag. Tags in the example include <book>, <title>, <author>, <firstname>, etc. A tag can indicate the start of information if it begins with an angle bracket (<), and a tag can indicate the end of information if it begins with an angle bracket and a slash (</). A beginning tag, ending tag, and the information between the two make up an element. In this example the publisher element tells us that the publisher for the book is "John Wiley and Sons." The figure also shows how an XML message follows a defined structure. Elements can be contained within other elements, as <firstname> and

Page 34

Locator Package XML

07/13/2015

<lastname> are included within the <author> element. This structure indicates that firstname and lastname are "children" of the author "parent." Although XML elements can contain almost any text, there are two special characters that cannot appear within an element. Those characters are the less-than sign (<) and the ampersand (&). Elements that include these contents must replace the special characters with "&lt;" or "&amp;" respectively. The name of a large telecommunications company, for example, would appear as "AT&amp;T" within an XML message. Because XML is a text-based format, software has to take extra steps to use XML with binary data. For example, some UPS services return binary image data such as the image of a shipping label. To include this data in an XML message, UPS converts it from binary to text format using an algorithm known as Base64 encoding. The "The Base16, Base32, and Base64 Data Encodings" standard. Although XML messages consist of a series of text characters, most software development tools represent XML messages in a tree-like data structure. That representation clarifies the structure of the message. Figure 8 shows the same XML message as Figure 7, but it uses a more visual representation to highlight the message's structure.

Page 35

Locator Package XML

07/13/2015

The example of Figure 7 and Figure 8 is a relatively simple XML message with just a few elements. UPS Developer APIs rely on XML messages that are larger than this simple example, and it is difficult to show them in a pure graph like Figure 8 without losing legibility. Figure 9 shows an alternate way of depicting the tree-like structure of XML messages; it uses the same example as before.

Page 36

Locator Package XML

07/13/2015

A great deal of information on XML is available on the Internet. A good starting point for further research is the World Wide Web Consortiumâ&#x20AC;&#x2122;s main page on XML at http://www.w3.org/XML/.

1.5.4 Working with XML in Application Programs The popularity of Extensible Markup Language means that nearly all development environments include sophisticated support for creating and interpreting XML messages. This subsection provides a brief introduction to working with XML in Microsoft, Java, and Open Source environments. The examples it contains are only representative approaches; many other approaches are possible.

1.5.4.1 Microsoft Visual Studio The Microsoft XML Core Services (MSXML) offers one way to work with XML documents in Visual Studio applications. Figure 10 shows one approach for creating an XML message in Visual Basic, and Figure ÂŠ 2015 United Parcel Service of America, Inc. All Rights Reserved. Confidential and Proprietary

Page 37

Locator Package XML

07/13/2015

11 demonstrates how Visual Basic programs can interpret XML responses. To remain as simple as possible, the examples do not include any exception handling. Production software should, of course, provide full exception handling.

Page 38

Locator Package XML

07/13/2015

Figure 10. Visual Basic can create XML messages through the DOMDocument object.

Page 39

Locator Package XML

07/13/2015

Figure 11. Visual Basic can read the contents of XML messages after parsing them with the DOMDocument object.

Visual Basic also has built-in classes to interpret Base64-encoded values. The Convert.FromBase64String() function converts from a Base64-encoded string to an array of 8-bit unsigned integers

1.5.4.2 Java Standard Edition and Enterprise Edition The Java API for XML Processing (JAXP) is the preferred approach for working with XML messages in Java. Figure 12 shows how a BookClass object can be converted into an XML message, a process that JAXP calls marshalling. Similarly, Figure 13 shows the reverse process, where an XML message is converted into a BookClass object. This reverse process is unmarshalling. As above, exception handling code is omitted from these examples to make them as clear as possible.

Page 40

Locator Package XML

07/13/2015

1.5.4.3 Open Source

Page 41

Locator Package XML

07/13/2015

As of this writing, the most popular open source tool for working with XML is the xerces project. That project includes C++, Java, and Perl implementations of an XML library. The xerces distribution includes extensive sample applications. The code fragment in Figure 14 demonstrates creating an XML message in C++ with the xerces library. Figure 15 shows sample code for accessing an element within an XML message. In both cases exception handling is not shown in order to keep the examples as simple as possible. Production software should always contain full exception handling.

Page 42

Locator Package XML

07/13/2015

Page 43

Locator Package XML

07/13/2015

1.6 Understanding XML Locator Services The Locator API is a convenient and flexible way to find UPS shipping locations. With this UPS Developer API, your application can find UPS Centers, UPS Stores, UPS Drop Boxes, and Authorized Shipping Outlets. You can search for locations based on their types and on UPS services they make available. The Locator API can return search results as a list.

1.6.1 Types of Requests Applications use the RequestOption element in Locator requests to define the type of information they want UPS to provide. Values less than 8 request UPS locations. With values greater than 7, applications request a list of possible services, program types, and/or retail locations. The information from these requests may be used to refine a search in additional requests. For example, an application may request a list of all available additional services. It can then select the services it needs from that list an issue a second request for locations that offer those services. The following table lists the possible values for the Request Option element. RequestOption 1 8 16 24 32 40 48 56 64

Type of Request A list of locations All available additional services All available program types All available additional services and program types All available retail locations All available retail locations and additional services All available retail locations and program types All available retail locations, program types, and additional services UPS Access Pointâ&#x201E;˘ Search

1.7 Understanding Mileage Bands and Prioritization in the Global Locator 1.7.1 Countries with the UPS Store The UPS.com locator attempts to balance convenience for the customer while still giving preference to The UPS Store, our premier channel. The locator search functionality is divided into mileage bands. In the US and Canada within each of those ÂŠ 2015 United Parcel Service of America, Inc. All Rights Reserved. Confidential and Proprietary

Page 44

Locator Package XML

07/13/2015

bands, The UPS Store locations receive preferential treatment, as they are always sorted to the top, regardless of whether another retail channel's locations may be closer within that band. The sort order for the different Retail locations within each mileage band is: 1 – The UPS Store 2 – UPS Customer Centers and Drop Boxes 3 – Alliance Locations 4 – Authorized Shipping Outlets 5 – Authorized Service Providers

6 – UPS Access Point™ (Canada Only) In the non-US and Canada countries, within each of those bands, Mail Boxes Etc. locations receive preferential treatment, as they are always sorted to the top, regardless of whether another retail channel's locations may be closer within that band. The sort order for the different Retail locations within each mileage band is: 1 – Mail Boxes Etc. 2 – UPS Customer Centers and Drop Boxes 3 – UPS Access Point™ , Kiala Point, and UPS Paket Shop 4 – UPS Express 5 – Alliance Locations 6 – Authorized Shipping Outlets 7 – UPS Authorized Service Providers The channels are sorted in the above order within each mileage band.

The mileage bands are as follows:  Less than or equal to 1 mile 

Greater than 1 mile and less than or equal to 5 miles



Greater than 5 miles and less than or equal to 10 miles



Greater than 10 miles and less than or equal to 20 miles



Greater than 20 miles and less than or equal to 50 miles

Page 45

Locator Package XML

ď&#x201A;ˇ

07/13/2015

Greater than 50 miles and less than or equal to 200 miles

Example of Search Results and Bands

Note: The UPS Store (#6) at 9.6 miles is listed before closer Alliance (#7) and ASO (#8).

Page 46

Locator Package XML

07/13/2015

Page 47

Locator Package XML

07/13/2015

1.8 The Locator XML Reference This section documents the details of the XML messages, including the requests that clients send to UPS and the responses that UPS returns. The first subsection explains the notation that this section uses. It is followed by a section that describes how UPS verifies that client applications are authorized to use the API. The next subsections define the messages used by the tool for its services. The final subsection provides a list of error codes.

1.8.1 Describing UPS API Messages As noted previously, all messages that UPS Developer APIs send and receive consist of XML documents. This reference section defines the specific elements within those XML documents. Because XML documents follow a defined structure, this reference shows those elements using a compact, graphical notation. Here is an example of that notation, with some additional annotations to highlight important conventions:

ISBN must contain either ISBN10 or ISBN13, but not both.

Book ├─Title::string ├─Author::string [as many as 10] ├─Date │ ├─Year::integer │ ├─Month::integer │ └─Day::integer ├─ISBN │ ├─(1) ISBN-10::string │ └─(2) ISBN-13::string ├─Publisher::string └─Language::string [optional]

Author may be repeated up to 10 times.

Language is optional and may be omitted.

The figure indicates that a "Book" can contain six different child elements: Title, Author, Date, ISBN, Publisher, and Language. The Langauge element is marked "optional" so it is not required. All of the other five elements are required, however. Notice that the Author element can appear as many as ten times within the Book document. (The technical name for this property is cardinality.)

Page 48

Locator Package XML

07/13/2015

Some of the child elements can themselves contain child elements. The Date element, for example, consists of a Year element, a Month element, and a Day element. Finally, notice that the children of the ISBN element (ISBN-10 and ISBN-13) have a number in parentheses preceding them. This number indicates a choice. In this example, the ISBN element must have either an ISBN-10 child element or an ISBN13 child element, but it cannot have both. If an element has no child elements, the notation convention shows the type of content that the element can contain. In the example, Year, Month, and Day must contain integer numbers, while other primitive elements can contain arbitrary text strings.

1.8.2 Authenticating Client Applications UPS Shipping API Services are only available for authorized UPS customers. To enforce this policy, UPS requires that every message that a client application sends include important authentication information. That information is contained in an AccessRequest XML document that must begin each message.

1.8.2.1 AccessRequest

Each AccessRequest contains three child elements: an AccessLicenseNumber, a UserId, and a Password. The following figure shows an example AccessRequest document.

Page 49

Locator Package XML

07/13/2015

1.8.3 Locator Service Tool service relies on a single request and response. Client applications request locations by sending a LocatorRequest message to UPS. UPS replies with a LocatorResponse message. 1.8.3.1 LocatorRequest The LocatorRequest message consists of two complete XML documents. The first document is an AccessRequest. It is immediately followed by a LocatorRequest. When a client application is undergoing testing and integration, the document combination should be sent to the URL: https://wwwcie.ups.com/ups.app/xml/Locator Once a client application is in production, the document combination should be sent to the URL: https://www.ups.com/ups.app/xml/Locator The LocatorRequest document in the request must conform to the following XML structure. LocatorRequest XML Details Example LocatorRequest Message ÂŠ 2015 United Parcel Service of America, Inc. All Rights Reserved. Confidential and Proprietary

Page 50

Locator Package XML

07/13/2015

Page 51

Locator Package XML

07/13/2015

1.8.3.2 LocatorResponse The LocatorResponse message contains a single XML document that conforms to the following XML structure. <?xml version="1.0" encoding="ISO-8859-1" ?> <LocatorResponse> <Response> <TransactionReference><XpciVersion>1.0014</XpciVersion></TransactionReference> <ResponseStatusCode>1</ResponseStatusCode> <ResponseStatusDescription>Success</ResponseStatusDescription> </Response> <Geocode> <Latitude>33.42634582</Latitude><Longitude>-111.940078</Longitude> </Geocode> <SearchResults> <DropLocation> <LocationID>71339</LocationID> <AddressKeyFormat> <ConsigneeName>SHIP-N-GO - The Sunset Building</ConsigneeName> <AddressLine>50 SOUTH ELM STREET</AddressLine> <PoliticalDivision2>TEMPE</PoliticalDivision2> <PoliticalDivision1>AZ</PoliticalDivision1> <PostcodePrimaryLow>85281</PostcodePrimaryLow> <CountryCode>US</CountryCode> </AddressKeyFormat> <PhoneNumber>6029697744</PhoneNumber> <FaxNumber>6029697746</FaxNumber> <EMailAddress>shipngo@ups.com</EMailAddress> <LocationAttribute> <OptionType> <Code>01</Code><Description>Location</Description> </OptionType> <OptionCode> <Code>001</Code><Description>UPS Center</Description>

Page 52

Locator Package XML

07/13/2015

</OptionCode> </LocationAttribute> <LocationAttribute> <OptionType> <Code>02</Code> <Description>RetailLocation</Description> </OptionType> <OptionCode> <Code>01</Code> <Description>UPS Customer Counter</Description> </OptionCode> </LocationAttribute> <LocationAttribute> <OptionType> <Code>03</Code><Description>AdditionalServices </Description> </OptionType> <OptionCode> <Code>002</Code> <Name>UPS Packaging and Supplies</Name> </OptionCode> </LocationAttribute> <LocationAttribute> <OptionType> <Code>04</Code> <Description>ProgramType</Description> </OptionType> <OptionCode> <Code>01</Code> <Name>UPS Gold Shield</Name> </OptionCode> </LocationAttribute> <Distance> <Value>1.9</Value> <UnitOfMeasurement> <Code>MI</Code> <Description>MILES</Description>

Page 53

Locator Package XML

07/13/2015

</UnitOfMeasurement> </Distance> <SpecialInstructions /> <LatestGroundDropOffTime>Mon-Sat: 3:00pm</LatestGroundDropOffTime> <AdditionalChargeIndicator /> <StandardHoursOfOperation> Mon-Fri: 9:00am-5:30pm; Sat: 10:00am-2:30pm; Sun: Closed </StandardHoursOfOperation> <NonStandardHoursOfOperation>Dec 1: Closed</NonStandardHoursOfOperation> </DropLocation> </SearchResults> </LocatorResponse>

LocatorResponse XML Details Example LocatorResponse Message

1.8.4 Locator Request Locator Request The LocatorRequest message consists of two complete XML documents. The first document is an AccessRequest. It is immediately followed by a LocatorRequest. When a client application is undergoing testing and integration, the document combination should be sent to the URL: https://wwwcie.ups.com/ups.app/xml/Locator Once a client application is in production, the document combination should be sent to the URL: https://www.ups.com/ups.app/xml/Locator The LocatorRequest document in the request must conform to the following XML structure.

Page 54

Locator Package XML

07/13/2015

NAME

XPATH

REQUIRED

MAXALLOWED

TYPE

LENGTH

DESCRIPTION

LocatorRequest

/LocatorRequest

Yes

Container

N/A

N/A 1

Request

/LocatorRequest/Request

Yes

Container

N/A

TransactionReference

/LocatorRequest/Request/Transact ionReference

Container

N/A

CustomerContext

/LocatorRequest/Request/Transact ionReference/CustomerContext

String

1..512

TransactionReference identifies transactions between client and server. The client uses CustomerContext to synchronize request/response pairs. The client establishes CustomerContext, which can contain any information you want, as along as it is valid XML; it is echoed back by the server.

XpciVersion

/LocatorRequest/Request/Transact ionReference/XpciVersion

String

Note: UPS expects schema elements/tags as defined in the X-Path and presented in the schema structure i.e. no spelling or structural deviations. Elements/tags that are not defined in the schema or do not conform to the schema structure will be ignored by UPS.

Message version. Valid value is 1.0014

Page 55

REQUIRED

MAXALLOWED

ToolVersion

/LocatorRequest/Request/Transact ionReference/ToolVersion

Yes

String

RequestAction

/LocatorRequest/Request/Request Action

Yes

String

RequestOption

/LocatorRequest/Request/Request Option

Yes

String

1..4

OriginAddress

/LocatorRequest/OriginAddress

Container

N/A

LandmarkCode

/LocatorRequest/OriginAddress/La ndmarkCode

String

1..2

LENGTH

XPATH

TYPE

NAME

Yes

07/13/2015

Cond

Locator Package XML

DESCRIPTION

Indicates the action to be taken by the XML service.Must be 'Locator'. Indicates the type of request, Valid values are 1 = Locations (Drop Locations and Will call locations), 8 = All available Additional Services, 16 = All available Program Types, 24 = All available Additional Services and Program types, 32 = All available Retail Locations, 40 = All available Retail Locations and Additional Services, 48 = All available Retail Locations and Program Types, 56 = All available Retail Locations, Additional Services and Program Types, 64=Search for UPS Access Point™ Locations

The origin address country code is required for all requests. The user may input a landmark to obtain a UPS location closest to the point of interest.The user must also provide Political Division 2 and Political Division 1 or Postal Code and Country Code in the Address Key Format.Valid Values are: 1 = Airport 2 = Amusement center3 = Bus station4 = Cemetery5 = Ferry terminal 6 = Golf course7 = Government facility8 = Hospital9 = Military installation10 = Place of worship11 = Retail center12 = School, College or University13 = Stadium, performance arena14 = Subway or Metro station15 = Train station16 = Water bodiesCurrently not supported.

Page 56

Cond

Geocode

/LocatorRequest/OriginAddress/G eocode

Cond

Container

N/A

Latitude

/LocatorRequest/OriginAddress/G eocode/Latitude

Yes*

String

1..11

The latitude of the origin address or the center point of the area code.

Longitude

/LocatorRequest/OriginAddress/G eocode/Longitude

Yes*

String

1..11

AddressKeyFormat

/LocatorRequest/OriginAddress/Ad dressKeyFormat

Container

N/A

The longitude of the origin address or the center point of the area code. Contains all of the basic information about the origin such as Address Lines, City, State/Province, Postal Code and Country Code. The element CountryCode is required. The element Region is not relevant for this tool.

ConsigneeName

/LocatorRequest/OriginAddress/Ad dressKeyFormat/ConsigneeName

String

1..40

LENGTH

/LocatorRequest/OriginAddress/Ph oneNumber

Name. Not relevant for this tool

1..15

PhoneNumber

DESCRIPTION This container is applicable for Locations, Map and/or driving direction request. PhoneNumber Search, Map and/or driving are only supported for back-ward compatibility and they are deprecated. The originator's phone number.A phone number is required if the user chooses not to input any address information. The user may supply the phone number in either PCDATA format or the Structured Phone Number format. Country Code must also be supplied.Refer to the Universal Rules table for more information on phone number formats. If the originator's country is US, 10 digits allowed, otherwise 1..15 digits allowed. Note: Not for External use. Geocode is the latitude and longitude of the origin address. The Geocode is returned when a candidate list is not returned for a location request.The Geocode for the origin address will be required when a Map or Driving Directions are requested in the Request Option.

Yes

TYPE

XPATH

String

NAME

MAXALLOWED

07/13/2015

REQUIRED

Locator Package XML

Page 57

LENGTH 1..100 1..64 1..50 1…50

City or Town.

1..50

State or province

1..10

TYPE String String

Cond

PostcodePrimaryLow

/LocatorRequest/OriginAddress/Ad dressKeyFormat/PostcodePrimaryLow

String

/LocatorRequest/OriginAddress/Ad dressKeyFormat/PoliticalDivision1

String

Cond

PoliticalDivision1

String

/LocatorRequest/OriginAddress/Ad dressKeyFormat/PoliticalDivision2

String

PoliticalDivision2

Barrio or other sub-division of City

Main postal code. Required if the user does not submit the City, State/Province address combination or phone number.

String

/LocatorRequest/OriginAddress/Ad dressKeyFormat/PoliticalDivision3

PoliticalDivision3

/LocatorRequest/OriginAddress/Ad dressKeyFormat/AddressLine2

AddressLine2

Address Line Information.

/LocatorRequest/OriginAddress/Ad dressKeyFormat/AddressLine3

AddressLine3

Address Line Information. The user may submit street level address information or provide Intersection information. Only one address line can be submitted.

AddressLine

/LocatorRequest/OriginAddress/Ad dressKeyFormat/AddressLine

DESCRIPTION

XPATH

Cond

NAME

MAXALLOWED

07/13/2015

REQUIRED

Locator Package XML

Page 58

LENGTH 1..10 2 N/A 1..2 N/A 1..3 5

TYPE String String

Language code. Valid values are: US English = eng

Required for SearchOptionCode 01,02 and 05 for Freight location search.

String String

/LocatorRequest/Translate/Locale

Container

Locale

Contains the locale information for the request.

String

/LocatorRequest/Translate/Langua geCode

If present, indicates the maximum number of locations the client wishes to receive in response; ranges from 1 to 50 with a default value of 10

string

Yes

LanguageCode

MAXALLOWED

/LocatorRequest/Translate

Translate

MaximumListSize

/LocatorRequest/OriginAddress/M aximumListSize

Single Search String Could be the value of origin address, prominent landmark or neighborhood in single line.

Yes

SingleLineAddress

/LocatorRequest/OriginAddress/Ad dressKeyFormat/SingleLineAddress

Two-character country abbreviation

/LocatorRequest/OriginAddress/Ad dressKeyFormat/CountryCode

CountryCode

4 Digit postal code extension. Valid for US only.

REQUIRED

PostcodeExtendedLow

/LocatorRequest/OriginAddress/Ad dressKeyFormat/PostcodeExtendedLow

DESCRIPTION

XPATH

NAME

Yes

07/13/2015

Cond

Locator Package XML

Page 59

TYPE

LENGTH

String

N/A N/A 2 1..50 1…10 N/A

String

/LocatorRequest/LocationSearchC riteria

SearchOption

/LocatorRequest/LocationSearchC riteria/SearchOption

N/A

String String

LocationSearchCriteria

Container

/LocatorRequest/LocationID

Container

1 1

LocationID

/LocatorRequest/UnitOfMeasurem ent/Description

Description

Cond

/LocatorRequest/UnitOfMeasurem ent/Code

Required for Location, Map and/or driving directions request (Map and/or driving only supported for backward compatibility). Valid values are: MI = Miles or KM = Kilometers

Code

Cond

Container

Distance unit of measurement. This is required for the location, map and driving direction requests. (Request option 1, 2, 3, 4, 6) Options 2-6 only supported for backward compatibility

/LocatorRequest/UnitOfMeasurem ent

Not Used

Cond

UnitOfMeasurement

MAXALLOWED

/LocatorRequest/Translate/Code

Code

DESCRIPTION

XPATH

Cond

NAME

REQUIRED

07/13/2015

Locator Package XML

Not Used Location ID is the identification number of the UPS affiliated UPS location. Required if map ID is not provided in Map only request (request option 2). Required for Driving directions request. Used to indicate which locations the user wants mapped. Can only supply up to 5. Also used to get driving directions. Only one can be supplied to receive driving directions. This number is not to be exposed in the Graphical User Interface. The Location search criteria container allows the user to further define the basis to which they wish to receive the UPS locations. Only relevant when the user requests a Location search. Request option 1, 3 SearchOption contains the information that forms the basis of the location search, It contains the criteria for search by Locations/RetailLocations/ AdditionalServices/ProgramTypes, There should be one container for each type of search the user may wish to do, The user can specify either search by Locations or RetailLo-

Page 60

LENGTH N/A 2 N/A

TYPE Container

Code

/LocatorRequest/LocationSearchC riteria/SearchOption/OptionType/Cod e

Description

/LocatorRequest/LocationSearchC riteria/SearchOption/OptionType/Desc ription

OptionCode

/LocatorRequest/LocationSearchC riteria/SearchOption/OptionCode

Container

N/A

Code

/LocatorRequest/LocationSearchC riteria/SearchOption/OptionCode/Cod e

String

1..10

/LocatorRequest/LocationSearchC riteria/SearchOption/OptionType

Yes*

Container String

MAXALLOWED 1

Code for Option type. 01 - Location; 02 - RetailLocation; 03 - AdditionalServices; 04 - ProgramType; 05 Service Level Option

OptionType

No Zero or One

Yes*

DESCRIPTION cations, but not both, If this container is missing the default search would be for The UPS Store, UPS Center, UPS Drop Box, and Authorized Shipping Outlet location types. OptionType is a container that indicates the type of the location attribute. There are 4 types of attributes. They are: Location, RetailLocation, AdditionalServices and ProgramTypes. .If search criteria by Location or RetailLocation is not provided then the default search of The UPS Store, UPS Center, UPS Drop Box, and Authorized Shipping Outlet location types will be performed.

Yes*

XPATH

Yes

NAME

07/13/2015

REQUIRED

Locator Package XML

Not required for request. Option code contains the information of a particular Location/RetailLocation/ AdditionalService/ ProgramType depending on the option type. The SearchOptions can contain one or more OptionCodes which forms the criteria for the location search. Code for different Locations: '001' - UPS Customer Center, '002' - The UPSStore, '003' - UPS drop box, '004' authorized shipping outlet, '005' - MailBoxes Etc,'007' UPS Alliance, '009' - UPS Express, '010' - UPS Express,'011 - UPS Access Point™ / Kiala Point / UPS Paket Shop, '012' - UPS Express,'013' - UPSAuthorized Service Provider, '014' - UPS Authorized ServiceProvider, '015' - UPS Authorized Service Provider, '016' - UPS Authorized Service Provider,’017’- UPS Freight Customer Centers, '018' - UPS Access Point™ . These codes vary by country. It is strongly recommended that clients contact UPS to retrieve the primary search indi-

Page 61

XPATH

MAXALLOWED

TYPE

LENGTH

Description

/LocatorRequest/LocationSearchC riteria/SearchOption/OptionCode/Des cription

String

N/A

Name

/LocatorRequest/LocationSearchC riteria/SearchOption/OptionCode/Nam e

String

1..50

Relation

/LocatorRequest/LocationSearchC riteria/SearchOption/Relation

Container

N/A

REQUIRED

NAME

No Zero Or One No

07/13/2015

Locator Package XML

DESCRIPTION cator and the valid Location Types and Service Level Options for each country. The primary search indicator specifies whether to use Location Types or Service Level Options. The Retail Locations codes change dynamically. The valid list of codes for different retail location types can be obtained by a separate type of request (Request Option 32, 40, 48 and 56). The Additional service codes change dynamically. The valid list of codes for different additional services can be obtained by a separate type of request (Request Option 8, 24, 40 and 56). The Program Type codes change dynamically. The valid list of codes for different program types can be obtained by a separate type of request (Request Option 16, 24, 48 and 56). Codes for Service Level Option: '01' = Full Service, '02' = Shipping and Drop Off, '03' = Shipping, '04' = Drop Off, '05' = All, '06' = Self-Service, “07” = Collection and Prepaid Drop Off. The Request should include Services Level Options OR Location Types but not both. If both are passed, the Service Level Option will be ignored Only one Service Level Option can be requested at a time. **Note: The name for UPS Access Point™ , Kiala Point, and UPS Paket Shop (011) and UPS Authorized Service Provider (014, 015, 016) will change by country.

Not Used

Not valid for request. Only valid for the response. The relation container will contain the relation parameter (And/Or) that has to be used among multiple option codes in the location search. This is only applicable to option type AdditionalServices and ProgramTypes. If this container is not present for AdditionalServices and

Page 62

LENGTH

Code for the combination search option. Valid values are:

2 N/A

This Container contains Combination Search option Search By Location Type(s), Marketing Program(s) and (SLIC or Postal Code) on the WillCallSearch container

TYPE String String

Yes*

Container

Code

/LocatorRequest/LocationSearchC riteria/EnhancedSearchOption/Code

DescriptionNot relevant for this tool

String

No One

EnhancedSearchOption

/LocatorRequest/LocationSearchC riteria/EnhancedSearchOption

Yes*

Description

/LocatorRequest/LocationSearchC riteria/SearchOption/Relation/Descript ion

Applicable for AdditionalServices and ProgramTypesCode that describes the relation: 01 – And (Default); 02 – Or

Code

/LocatorRequest/LocationSearchC riteria/SearchOption/Relation/Code

DESCRIPTION ProgramTypes, the default relation of And is used.

XPATH

NAME

MAXALLOWED

07/13/2015

REQUIRED

Locator Package XML

10 = SLIC or Postal Code

Page 63

N/A

LENGTH 1..2 1..3

Defines the maximum radius the user wishes to search for a UPS location.If the user does not specify the default value is 100 miles.Whole numbers only.Valid values are:5 through 100 miles

Allows for users to further define the search criteria. Refer to the rules specified in section Service Search.

4..6

N/A

Allows the user to specify the maximum number of UPS locations to be returned in the response document. Valid values are 1 through 50.If user does not choose to enter a Maximum List Size Value the search response will be default to 5.

Scheduled Local Drop-off Time. Format: HHMM

N/A

String String Container String Container String

Code

/LocatorRequest/LocationSearchC riteria/ServiceSearch/ServiceCode/Co de

DESCRIPTION

Container that contains the service information as to Ground/Air Required if the customer provides ServiceSearch Time

TYPE

ServiceCode

/LocatorRequest/LocationSearchC riteria/ServiceSearch/ServiceCode

/LocatorRequest/LocationSearchC riteria/ServiceSearch/Time

Time

/LocatorRequest/LocationSearchC riteria/ServiceSearch

ServiceSearch

/LocatorRequest/LocationSearchC riteria/SearchRadius

SearchRadius

Cond

/LocatorRequest/LocationSearchC riteria/MaximumListSize

Yes*

MaximumListSize

String

MAXALLOWED

Description

/LocatorRequest/LocationSearchC riteria/EnhancedSearchOption/Descri ption

XPATH

NAME

REQUIRED

07/13/2015

Locator Package XML

Code indicating the different services. 01 - Ground, 02Air, 03 - Express, 04 - Standard.

Page 64

TYPE EMPTY

Container

N/A

Container that contains the optional service information such as Saturday Pick up.

String

Code that defines the optional service01 – Saturday pickup.

String

DescriptionNot relevant to the request.

Container

Search for Will Call LocationsExternal – Do not PutInternal – IVR Required if the user specifies Will Call location preference in the DCR application Note : Donot Include in the Developers guide

Description

/LocatorRequest/LocationSearchC riteria/ServiceSearch/ServiceCode/De scription

ServiceOptionCode

/LocatorRequest/LocationSearchC riteria/ServiceSearch/ServiceOptionC ode

Code

/LocatorRequest/LocationSearchC riteria/ServiceSearch/ServiceOptionC ode/Code

Yes*

Description

/LocatorRequest/LocationSearchC riteria/ServiceSearch/ServiceOptionC ode/Description

*Yes One

WillCallSearch

/LocatorRequest/LocationSearchC riteria/WillCallSearch

No Zero or one

SLIC

/LocatorRequest/LocationSearchC riteria/WillCallSearch/SLIC

*Yes One

String

1..5

PostcodePrimaryLow

/LocatorRequest/LocationSearchC riteria/WillCallSearch/PostcodePrimar yLow

String

1..10

XPATH

NAME

No Zero or one

LENGTH

MAXALLOWED 1

Description.Not applicable to request.

07/13/2015

*Yes Zero or One REQUIRED

Locator Package XML

DESCRIPTION

UPS code used to uniquely identify UPS district and region work units External – Do not Put Internal –Only used by IVR Note : Donot Iclude in the Developers guide "Postal Code. WillCall locations are searched based on the PostalCode and if no locations are found, then only SLIC will be used for WillCall search. Not for external use Internal – Only used by IVR Note : Do not include in the Developers guide"

Page 65

LENGTH 2 5 1..64

Address line

1..50

City.Required for Freight Will call search if FreightWillCallRequestType is 3

unbounded 1

N/A

TYPE String

Facility SLIC. Required for Freight Will call search if FreightWillCallRequestType is 2

String

Container

City

/LocatorRequest/LocationSearchC riteria/FreightWillCallSearch/FacilityA ddress/City

Container

Cond

AddressLine

/LocatorRequest/LocationSearchC riteria/FreightWillCallSearch/FacilityA ddress/AddressLine

String

Yes*

SLIC

/LocatorRequest/LocationSearchC riteria/FreightWillCallSearch/FacilityA ddress/SLIC

String

Yes*

FacilityAddress

/LocatorRequest/LocationSearchC riteria/FreightWillCallSearch/FacilityA ddress

String

MAXALLOWED

Cond

FreightWillCallRequestType

/LocatorRequest/LocationSearchC riteria/FreightWillCallSearch/FreightW illCallRequestType

/LocatorRequest/LocationSearchC riteria/FreightWillCallSearch

*Yes One

FreightWillCallSearch

unbounded 1

/LocatorRequest/LocationSearchC riteria/WillCallSearch/CountryCode

REQUIRED

CountryCode

XPATH

NAME

Cond

07/13/2015

Cond

Locator Package XML

DESCRIPTION A country code. Valid values for candidates to be returned are:US = United States (meaning US 50) and CA = Canada External – Do not Put Internal –Only used by IVR Note : Donot Include in the Developers guide US and Canada is applicable only for IVR

Freight Will Call Search Container. Required if SearchOption is '05-Freight Will Call Search' POSTAL_CODE - 1- Freight Will Call Search based on Postal Code. This search is for Postal code countries. DELIVERY_SLIC- 2 - Freight Will Call Search based on SLIC. DELIVERY_CITY_STATE - 3-Freight Will Call Search based City and/or state or both. This Search is for Non Postal code Countries

Facility Address Container

Page 66

LENGTH

String

1..8

Holds the information about the postal code extended. Required for Freight Will call search if FreightWillCallRequestType is 1

String

1..8

PostalCodeExtendedLow. 4 Digit postal code extension. Valid for US only.

String

1..50

State. Required if FrieghtWillCallRequestType is 3 if State is available.

String

Country Code.

PostalCodeExtendedLow

/LocatorRequest/LocationSearchC riteria/FreightWillCallSearch/FacilityA ddress/PostalCodeExtendedLow

State

/LocatorRequest/LocationSearchC riteria/FreightWillCallSearch/FacilityA ddress/State

Cond

CountryCode

/LocatorRequest/LocationSearchC riteria/FreightWillCallSearch/FacilityA ddress/CountryCode

Yes*

OriginOrDestination

/LocatorRequest/LocationSearchC riteria/FreightWillCallSearch/OriginOr Destination

Yes*

String

FormatPostalCode

/LocatorRequest/LocationSearchC riteria/FreightWillCallSearch/FormatP ostalCode

String

2..3

OriginOrDestination is required for FreightWillCallRequestType 1 Postal based and 3 City and/or State based search. If OriginOrDestination is 01 indicates Origin facilities and 02 indicate Destination facilities. FormatPostalCode would be required in the request when postal code is passed in Freight Will Call Search Request. This field can have any of the values - NFR, FR ,FS, NVR The values can be described as below: NFR='NoFormatRequested' ; FR='FormatRequested' ; FS='FormatAndSearch' NVR='NoValidationRequested'; Required if FreightWillCallRequestType is 1

DayOfWeekCode

/LocatorRequest/LocationSearchC riteria/FreightWillCallSearch/DayOfW eekCode

"Day Of week Code. Valid Values are 1 to 7. 1=Sunday; 2=Monday; 3=Tuesday ; 4=Wednesday; 5=Thursday; 6=Friday; 7=Saturday

String

PostalCodePrimaryLow

/LocatorRequest/LocationSearchC riteria/FreightWillCallSearch/FacilityA ddress/PostalCodePrimaryLow

XPATH

Cond

NAME

Yes*

TYPE

DESCRIPTION

MAXALLOWED

07/13/2015

REQUIRED

Locator Package XML

Page 67

N/A

This contains elements to refine (include) UPS Access Point™ address or geocode Search.

N/A

2 6..10

Status of UPS Access Point™ . Valid values are 01 = Active-available, 07 = Active-unavailable. The account number to use for UPS Access Point™ Search in the country. Uses to locate private network for the account. Once this parameter is present UPS Access Point™ address or geocode search is ignored. It cannot be combined with PublicAccessPointID search parameter.

This contains the list of Merchant Account numbers to be used for finding private network UPS Access Point™s.

6..10

String String Container Container

String

1 1 1

unbounded

The Public UPS Access Point™ ID to use for UPS Access Point™ Search. Once this parameter is present , address or geocode search is ignored. It cannot be combined with AccountNumber search parameter.

MerchantAccountNumber

Applicable for RequestOption 64 only. This contains inclusion and exclusion criteria for address search. It also contains Account Number and UPS Access Point™ Public ID search elements.

Yes*

MerchantAccountNumberList

/LocatorRequest/LocationSearchC riteria/AccessPointSearch/IncludeCrit eria/MerchantAccountNumberList /LocatorRequest/LocationSearchC riteria/AccessPointSearch/IncludeCrit eria/MerchantAccountNumberList/M erchantAccountNumber

LENGTH

IncludeCriteria

/LocatorRequest/LocationSearchC riteria/AccessPointSearch/IncludeCrit eria

N/A

AccountNumber

/LocatorRequest/LocationSearchC riteria/AccessPointSearch/AccountNu mber

DESCRIPTION

1..15

TYPE Container String

MAXALLOWED 1

AccessPointStatus

/LocatorRequest/LocationSearchC riteria/AccessPointSearch/AccessPoi ntStatus

PublicAccessPointID

/LocatorRequest/LocationSearchC riteria/AccessPointSearch/PublicAcce ssPointID

Cond

/LocatorRequest/LocationSearchC riteria/AccessPointSearch

AccessPointSearch

XPATH

NAME

07/13/2015

REQUIRED

Locator Package XML

Account number to be used for private network UPS Access Point™ search where UPS Access Point™ candidate list is obtained in search by address or geocode search.

Page 68

LENGTH N/A 0 0 1 0..3 N/A

String

N/A

TYPE Container

String

1 1

Container for Service offering code.

Container

ServiceOffering

Container to hold end point service offering List for UPS Access Point™ . Applicable only when UPS Access Point™ candidate list is obtained in search by address or geocode search.

Container

MAXALLOWED 1

ServiceOfferingList

/LocatorRequest/LocationSearchC riteria/AccessPointSearch/IncludeCrit eria/ServiceOfferingList /LocatorRequest/LocationSearchC riteria/AccessPointSearch/IncludeCrit eria/ServiceOfferingList/ServiceOffer ing

This containts the distance (in given UnitOfMeasurement) wherin to sort the click and collect access point locations above other UPS Access Point™ locations where UPS Access Point™ candidate list is obtained in search by address or geocode search.

ClickAndCollectSortWithDistance

Value for the number of days the to check for shipping availability from the current day. When this value is present, ShippingAvailabilityIndicator is implied implicitly.

ShipperPreparationDelay

Shipping Available indicator for UPS Access Point™ . Either this indi-cator is present or not present. Presence indicates search of ship-ping availability UPS Access Point™s. Any data in it is ignored.

ShippingAvailabilityIndicator

DCR/DCO Availability indicator for UPS Access Point™ . Either this indicator is present or not present. Presence indicates search for DCR access point locations. Any data in it is ignored.

DCRIndicator

/LocatorRequest/LocationSearchC riteria/AccessPointSearch/IncludeCrit eria/SearchFilter/DCRIndicator /LocatorRequest/LocationSearchC riteria/AccessPointSearch/IncludeCrit eria/SearchFilter/ShippingAvailability Indicator /LocatorRequest/LocationSearchC riteria/AccessPointSearch/IncludeCrit eria/SearchFilter/ShipperPreparation Delay /LocatorRequest/LocationSearchC riteria/AccessPointSearch/IncludeCrit eria/SearchFilter/ClickAndCollectSor tWithDistance

unbounded

SearchFilter

/LocatorRequest/LocationSearchC riteria/AccessPointSearch/IncludeCrit eria/SearchFilter

DESCRIPTION Container to hold one or more search criteria for UPS Access Point™s that allow DCR, Shipping and ClickAndCollect access. Only applicable to where UPS Access Point™ candidate list is obtained in search by address or geocode search.

XPATH

Yes*

NAME

REQUIRED

07/13/2015

Locator Package XML

Page 69

LENGTH 3 N/A N/A 1..15 1..3 N/A

TYPE String String

Container to hold a list of postal codes to exclude form the UPS Access Point™ address or geocode search.

No No

String String String

PostalCodeList

/LocatorRequest/LocationSearchC riteria/AccessPointSearch/ExcludeFro mResult/PostalCodeList

Container

MAXALLOWED 1 1

Radius

/LocatorRequest/LocationSearchC riteria/AccessPointSearch/ExcludeFro mResult/Radius

This contains the business name to exclude from UPS Access Point™ Search by address or geocode. Partial names are accepted. Public UPS Access Point™s within Radius (in specified Unit of Measure) of any included private UPS Access Point™s will be excluded from the results. Valid only if at least one IncludeCriteria/MerchantAccountNumber is provided.

BusinessName

/LocatorRequest/LocationSearchC riteria/AccessPointSearch/ExcludeFro mResult/BusinessName

ExcludeFromResult

BusinessClassificationCode

This contains the business classification code to exclude from UPS Access Point™ Search by address or geocode. Multiple occurrence of this tag is possible. Please refer to appendix D for detailed business codes.

This contains elements to exclude from UPS Access Point™ address or geocode search.

/LocatorRequest/LocationSearchC riteria/AccessPointSearch/ExcludeFro mResult /LocatorRequest/LocationSearchC riteria/AccessPointSearch/ExcludeFro mResult/BusinessClassificationCode

Not Used

/LocatorRequest/LocationSearchC riteria/AccessPointSearch/IncludeCrit eria/ServiceOfferingList/ServiceOffer ing/Code /LocatorRequest/LocationSearchC riteria/AccessPointSearch/IncludeCrit eria/ServiceOfferingList/ServiceOffer ing/Description

DESCRIPTION The applicable values are: 001-Direct To Retail; 002-Not In One ADL; 003-Click and Collect; 004-Pickup, 005Drop 0ff; 006-Drop Off Union;007-PUDO; 008-Early Pickup Delivery Time; 009-Accept prepaid drop offs; 010-DCO DCR intercept accepted; 011- Accepts Payments; 012-Pay At Store; 013-Accepts Restricted Articles.

Description

REQUIRED

Code

XPATH

Yes*

NAME

07/13/2015

Locator Package XML

Page 70

LENGTH

DESCRIPTION

N/A

Container to hold the postal code .

1..10

Primary postal code.

1..10

Secondary postal code.

N/A

Holds the details of Id search that needs to be performed.

N/A

Container for Open Time Criteria.

Day Of week Code. Valid Values are 1 to 7. 1=Sunday; 2=Monday; 3=Tuesday ; 4=Wednesday; 5=Thursday; 6=Friday; 7=Saturday .

TYPE Container String String String Container String String

unbounded MAXALLOWED

Yes* No

/LocatorRequest/LocationSearchC riteria/OpenTimeCriteria/FromTime

FromTime

DayOfWeek

/LocatorRequest/LocationSearchC riteria/OpenTimeCriteria/DayOfWeek

/LocatorRequest/LocationSearchC riteria/OpenTimeCriteria

OpenTimeCriteria

PrimaryPostalCode

SearchIdCriteria

/LocatorRequest/LocationSearchC riteria/AccessPointSearch/SearchIdCr iteria

PostalCode

Yes*

SecondaryPostalCode

XPATH /LocatorRequest/LocationSearchC riteria/AccessPointSearch/ExcludeFro mResult/PostalCodeList/PostalCode /LocatorRequest/LocationSearchC riteria/AccessPointSearch/ExcludeFro mResult/PostalCodeList/PostalCode/Pri maryPostalCode /LocatorRequest/LocationSearchC riteria/AccessPointSearch/ExcludeFro mResult/PostalCodeList/PostalCode/Se condaryPostalCode

NAME

07/13/2015

REQUIRED

Locator Package XML

From time . Time Format HHMM.

Page 71

TYPE

LENGTH 4 N/A

Container for Sort Criteria.

1...2

/LocatorRequest/SortCriteria/SortT ype

String

SortType

Container

/LocatorRequest/SortCriteria

To time . Time Format HHMM.

String

SortCriteria

MAXALLOWED

/LocatorRequest/LocationSearchC riteria/OpenTimeCriteria/ToTime

ToTime

DESCRIPTION

XPATH

NAME

REQUIRED

07/13/2015

Locator Package XML

For different sort type values

The location identifier where the user wants the icons to begin numbering. If the user does not supply a number the default is one.

1..2

Container

Default value: 01. Only required when the user does not want the default values for map. Applicable to all the requests requesting map External – Do not Put Internal – Only used by existing customers Note : Donot Include in the Developers guide.

String

Cond Zero or One

Number

/LocatorRequest/MapNavigation/N umber

/LocatorRequest/MapNavigation

MapNavigation

No Zero or One

01 -Closest Location; 02-Deadline for Drop-off by Air/Express; 03-Deadline for Drop-off by Ground/Standard; 04-Latest Close Time; 05-Earliest Open Time.

Page 72

PanX

/LocatorRequest/MapNavigation/P anX

String

PanY

/LocatorRequest/MapNavigation/P anY

String

MapID

/LocatorRequest/MapNavigation/M apID

1…255

MapID of the map. This is used to request a map. Do not put in developer’s guide. A list of 5 Location IDs is encrypted within the MapID for Map generation. .

1..2

String String

1 1

No Zero or One

/LocatorRequest/MapNavigation/Z oomFactor

String

ZoomFactor

/LocatorRequest/MapNavigation/M apDimensions/Width

"The default width of the image to be returned is set at 200 pixels. Other valid values are between 100 and 400If the request is for a map with the MapID, this value will be ignored." "The factor the user wishes to zoom in on the image provided in the response.Not populated for the initial request.Valid values are between 0 and 15. Refer to Zoom FactorIf the request is for a map with the MapID, and a non-zero value is provided for PanX/PanY, the zoom factor will be ignored." "The level to which the user wishes to pan on the Xaxis.The initial request the default value is 0. Following the initial response the user may wish to view the image further to the left or to the right. To do so another request is required with a value between –1, 0, 1." "The level to which the user wishes to pan on the Yaxis.The initial request the default value is 0. Following the initial response the user may wish to view the image further up or down the y-axis. To do so another request is required with a value between –1, 0, 1."

*Yes One

Width

No Zero or One

LENGTH

TYPE Container String

"The default height of the image to be returned is set at 200 pixels. Other valid values are between 100 and 400If the request is for a map with the MapID, this value will be ignored."

No Zero or One

/LocatorRequest/MapNavigation/M apDimensions/Height

Map Dimensions allows the user to define the size of the map they would like to receive.

DESCRIPTION

Cond Zero or One

Height

MAXALLOWED

/LocatorRequest/MapNavigation/M apDimensions

MapDimensions

No Zero or One

XPATH

*Yes One

NAME

07/13/2015

REQUIRED

Locator Package XML

Page 73

XPATH

MAXALLOWED

TYPE

LENGTH

DESCRIPTION

MapURL

/LocatorRequest/MapNavigation/M apURL

Cond Zero or One

String

Var

Not relevant for the request.

ImageMap

/LocatorRequest/MapNavigation/I mageMap

Cond Zero to Many

Container

Retains the image grid that is needed to determine the origin of the requests and the location of the UPS locations on the image grid.Not relevant for the request.

LocationID

/LocatorRequest/MapNavigation/I mageMap/LocationID

*Yes One

String

The location ID of a particular UPS location.Not relevant for the request.

XCoordinate

/LocatorRequest/MapNavigation/I mageMap/XCoordinate

*Yes One

String

1…3

The X coordinate of the UPS location. Value: 0-400.Not relevant for the request.

YCoordinate

/LocatorRequest/MapNavigation/I mageMap/YCoordinate

*Yes One

String

1…3

The Y coordinate of the UPS location. Value: 0-400.Not relevant for the request.

AllowAllConfidenceLevels

/LocatorRequest/AllowAllConfiden ceLevels

String

SearchOptionCode

/LocatorRequest/SearchOptionCo de

String

Indicator to allow confidence level in search Types: 01- Proximity Search Details 02 - Address Search Details 03- Proximity Search Summary 04Address Search Summary 05- Freight Will Call Search .OptionType and OptionCode is required for SearchOptionCode is 03 and 04.Do not use optionType and OptionCode with SearchOptionCode 01,02 and 05

REQUIRED

NAME

07/13/2015

Cond

Locator Package XML

Page 74

LENGTH

DESCRIPTION

N/A

ServiceGeoUnit Container. Required to search for the freight facility information

Service Code. Required if ServiceGeoUnit Container present. Valid value is '096' .

GeoPoliticalUnit. Required if ServiceGeoUnit container present.Valid value is '002' .

TYPE

/LocatorRequest/FreightIndicator

Container

FreightIndicator

String

/LocatorRequest/ServiceGeoUnit/ GeoPoliticalUnit

String

Yes*

GeoPoliticalUnit

String

/LocatorRequest/ServiceGeoUnit/ ServiceCode

MAXALLOWED

Cond

ServiceCode

/LocatorRequest/ServiceGeoUnit

REQUIRED

ServiceGeoUnit

XPATH

NAME

Yes*

07/13/2015

Locator Package XML

FreightIndicator. Required for Freight Location Search.

Page 75

Locator Package XML

07/13/2015

1.8.5 Locator Response Locator Response The LocatorResponse message contains a single XML document that conforms to the following XML structure.

LENGTH

DESCRIPTION

N/A

Container for LocatorResponse

N/A

Container for Response

N/A

Container for customer provided data and the XPCI Version.

0..512

Customer provided data. May be XML. If this data is present in the request, it is echoed back to the customer.

MAXALLOWED

TYPE Container Container Container String Any

XpciVersion

CustomerContext

/LocatorResponse/Respo nse/TransactionReferenc e/CustomerContext /LocatorResponse/Respo nse/TransactionReferenc e/XpciVersion

Yes

TransactionReference

/LocatorResponse/Respo nse/TransactionReferenc e

/LocatorResponse/Respo nse

Yes

Response

/LocatorResponse

REQUIRED

LocatorResponse

NAME

XPATH

Identifies the version of the message. Current version is 1.0014 Page 76

LENGTH 1 1..15 N/A 1..15 1..15 1..50 1..5 N/A 1..512

Not Used

1..50

String Container String String

1 1 1

String String TYPE Container String String

MAXALLOWED

The Xpath name of the element in error. This is a valid Xpath pointing to an element in the request document.

Identifies the element in error.

No No No No

Number of seconds to wait until retry. This field is populated on special conditions of the Transient Error only, as defined by the service. A number between 1 and 86400 (24 hours)

String

ErrorLocationAttributeName

Describes the error code.

String

ErrorLocationElementReference

ErrorLocationElementName

/LocatorResponse/Respo nse/Error/ErrorLocation /LocatorResponse/Respo nse/Error/ErrorLocation/E rrorLocationElementName /LocatorResponse/Respo nse/Error/ErrorLocation/E rrorLocationElementReference /LocatorResponse/Respo nse/Error/ErrorLocation/E rrorLocationAttributeName

ErrorLocation

A numeric value that describes the error. Each tool defines a range of error codes. Refer to error conditions, in the appropriate chapter, for a complete list of interchange errors.

MinimumRetrySeconds

/LocatorResponse/Respo nse/Error/MinimumRetryS econds

Describes the severity of the error. Refer to Table 2 â&#x20AC;&#x201C; Error Codes

Yes* Yes*

ErrorDescription

/LocatorResponse/Respo nse/Error/ErrorCode /LocatorResponse/Respo nse/Error/ErrorDescriptio n

ErrorCode

If an error is encountered during the interchange, the Response contains an error. If the error is present, then the ErrorSeverity and ErrorCode are required.

/LocatorResponse/Respo nse/Error/ErrorSeverity

Describes the Response Status Code.

ErrorSeverity

Identifies the success or failure of the interchange. 1 = Success0 = Failure

/LocatorResponse/Respo nse/Error

DESCRIPTION

Error

ResponseStatusCode

Yes

ResponseStatusDescription

XPATH /LocatorResponse/Respo nse/ResponseStatusCod e /LocatorResponse/Respo nse/ResponseStatusDesc ription

NAME

07/13/2015

REQUIRED

Locator Package XML

The name of the attribute in error. This is the name of the attribute contained by the Error Location element. Page 77

TYPE

LENGTH

Unbounded

The contents of the element in error.

Geocode

/LocatorResponse/Geoco de

Cond

Container

Latitude

/LocatorResponse/Geoco de/Latitude

Yes*

Longitude

/LocatorResponse/Geoco de/Longitude

Yes*

SearchResults

/LocatorResponse/Search Results

Yes

GeocodeCandidate

/LocatorResponse/Search Results/GeocodeCandidate

AddressKeyFormat

/LocatorResponse/Search Results/GeocodeCandidate/ AddressKeyFormat

Geocode is the latitude and longitude of the origin address. The Geocode is provided in the first successful response. Required to be returned when the origin address or phone number is submitted in the request. One of the following: The latitude of the origin address. The center point of the exchange . The center point of the postal code or city.

N/A

The longitude of the origin address or the center point of the exchange.

Container for search results.

N/A

1…11 1…11

DESCRIPTION

If the origin address provided in the location, map or driving direction request document does not have a match, a list of candidate addresses, geocodes and optionally a landmark will be returned.

N/A

Container Container

1 1 1 1

N/A

MAXALLOWED

/LocatorResponse/Respo nse/Error/ErrorDigest

Container String String

REQUIRED

ErrorDigest

NAME

XPATH

Cond

07/13/2015

Yes*

Locator Package XML

Contains all of the basic information about candidate address. Page 78

MAXALLOWED

TYPE

LENGTH

String

1..40

String

1..100

String

1..35

String

1…50

City.

String

1…50

State/Province.

String

1…10

Postal Code.

String

1..10

4 Digit postal code extension. Valid for US only.

String

1…2

No Cond

Subdivision within a City. e.g., a Barrio.

CountryCode

Address Line Information. The address level or Intersection information must be returned if provided in the request. Only one address lines will be returned.

PostcodeExtendedLow

Name. Not relevant for candidate list.

PostcodePrimaryLow

DESCRIPTION

PoliticalDivision1

Cond

PoliticalDivision2

Cond

PoliticalDivision3

Cond

AddressLine

ConsigneeName

XPATH /LocatorResponse/Search Results/GeocodeCandidate/ AddressKeyFormat/ConsigneeName /LocatorResponse/Search Results/GeocodeCandidate/ AddressKeyFormat/AddressLine /LocatorResponse/Search Results/GeocodeCandidate/ AddressKeyFormat/PoliticalDivision3 /LocatorResponse/Search Results/GeocodeCandidate/ AddressKeyFormat/PoliticalDivision2 /LocatorResponse/Search Results/GeocodeCandidate/ AddressKeyFormat/PoliticalDivision1 /LocatorResponse/Search Results/GeocodeCandidate/ AddressKeyFormat/PostcodePrimaryLow /LocatorResponse/Search Results/GeocodeCandidate/ AddressKeyFormat/PostcodeExtendedLo w /LocatorResponse/Search Results/GeocodeCandidate/ AddressKeyFormat/CountryCode

Yes*

NAME

07/13/2015

REQUIRED

Locator Package XML

A country code. Valid values for candidates to be returned are: US = United States (meaning US 50)

Page 79

Container TYPE

LENGTH N/A

String

1…11

String

1…11

The longitude of the origin address or the center point of the area code, same as before.

String

1..50

If a Landmark code was provided in the request, a candidate list of Landmark Names will be returned along with the corresponding address and Geocode.

Variable

Disclaimer. In the event the user requested Ground and Air service types and the maximum UPS locations list size has not been met, the list of locations will continue with locations that provide either ground or air within the search radius. The disclaimer will note this deviation from the requested search criteria. The disclaimer is also the location where the user will receive information regarding a one-time pickup option if the first location is greater than 20 miles from the origin.

Container

N/A

When a location request is submitted with a valid origin address, UPS locations will be returned.

String

1..10

String

MAXALLOWED 1 1

The latitude of the origin address or the center point of the area code, same as before.

Yes*

/LocatorResponse/Search Results/DropLocation /LocatorResponse/Search Results/DropLocation/Locati onID

Geocode is the latitude and longitude of the origin candidate.

Unbounded 1

LocationID

Cond

DropLocation

/LocatorResponse/Search Results/Disclaimer

Cond

Disclaimer

Yes*

Latitude

DESCRIPTION

LandmarkName

/LocatorResponse/Search Results/GeocodeCandidate/ LandmarkName

Geocode

Yes*

Longitude

/LocatorResponse/Search Results/GeocodeCandidate/ Geocode /LocatorResponse/Search Results/GeocodeCandidate/ Geocode/Latitude /LocatorResponse/Search Results/GeocodeCandidate/ Geocode/Longitude

Yes*

XPATH

Cond

NAME

07/13/2015

REQUIRED

Locator Package XML

The location ID that corresponds to the UPS location. Do not expose the Location ID.

Page 80

LENGTH 15 N/A

Contains all of the basic information about a location, Consignee Name, Building Name, Address Lines, City, State/Province, Postal Code and Country Code.

1..40

2 N/A 15

String

The longitude of the location address or the center point of the area code.

Container

TYPE Container String String EMPTY Container String

The latitude of the location address or the center point of the area code.

String

MAXALLOWED

Geocode is the latitude and longitude of the location address. The Geocode for the location address will be returned when Location or Locations and Map are requested in the Request Option.

Name. (Also includes the building name)Return if available.

1 1 1 1

No Yes

ConsigneeName

"Indicates to the response recipient that the information has changed, and a new audio file should be produced.ONLY FOR IVR"

AddressKeyFormat

/LocatorResponse/Search Results/DropLocation/Addre ssKeyFormat /LocatorResponse/Search Results/DropLocation/Addre ssKeyFor-

Contains the name of the IVR file that relates to this drop location. The file is an audio recording of information related to the location.ONLY FOR IVR

Longitude

Yes

Latitude

Yes

Geocode

/LocatorResponse/Search Results/DropLocation/Geoco de /LocatorResponse/Search Results/DropLocation/Geoco de/Latitude /LocatorResponse/Search Results/DropLocation/Geoco de/Longitude

Yes*

TextToSpeechIndicator

PhraseID

/LocatorResponse/Search Results/DropLocation/IVR/P hraseID /LocatorResponse/Search Results/DropLocation/IVR/T extToSpeechIndicator

OriginOrDestination will returned for FreightWillCallRequestType 1 Postal based and 3 City and/or State based search. OriginOrDestination will be 01 for origin facilities and 02 for Destination facilities

/LocatorResponse/Search Results/DropLocation/IVR

DESCRIPTION

IVR

*Yes

OriginOrDestination

/LocatorResponse/Search Results/DropLocation/Origin OrDestination

Yes*

XPATH

*Yes

NAME

07/13/2015

REQUIRED

Locator Package XML

Integrated Voice Response information.ONLY FOR IVR

Page 81

LENGTH 1..100 1..35 1…50 1…50

String

1…10

Postal Code.

String

1..10

4 Digit postal code extension. Valid for US only.

1…2

A country code. Valid values to be returned are: US = United States (meaning US 50).

TYPE String String String String

State/Province.

String

MAXALLOWED 1 1 1

Yes* No

City.

CountryCode

Subdivision within a City. e.g., a Barrio.

PostcodeExtendedLow

Address Line Information of the UPS location The address level or Intersection information. Only two address lines will be returned. The second line may contain such information as the building name, the suite, and room.

PostcodePrimaryLow

DESCRIPTION

PoliticalDivision1

Yes*

PoliticalDivision2

Yes*

PoliticalDivision3

Yes*

AddressLine

/LocatorResponse/Search Results/DropLocation/Addre ssKeyFormat/AddressLine /LocatorResponse/Search Results/DropLocation/Addre ssKeyFormat/PoliticalDivision3 /LocatorResponse/Search Results/DropLocation/Addre ssKeyFormat/PoliticalDivision2 /LocatorResponse/Search Results/DropLocation/Addre ssKeyFormat/PoliticalDivision1 /LocatorResponse/Search Results/DropLocation/Addre ssKeyFormat/PostcodePrimaryLow /LocatorResponse/Search Results/DropLocation/Addre ssKeyFormat/PostcodeExtendedLo w /LocatorResponse/Search Results/DropLocation/Addre ssKeyFormat/CountryCode

XPATH mat/ConsigneeName

Yes*

NAME

07/13/2015

REQUIRED

Locator Package XML

Page 82

LENGTH 1..15 1..15 1..50 N/A N/A

String

Code for Option type. Values are: 01 Location; 02 RetailLocation; 03 AdditionalServices; 04 ProgramType.

1…50

Description for Option type such as Location, RetailLocation, AdditionalServices and ProgramType.

String

TYPE String String Container Container

OptionType is a container that indicates the type of the location attribute. There are 4 types of attributes. They are: Location, RetailLocation, AdditionalServices and ProgramType.

String

MAXALLOWED

LocationAttribute is a container that contains the information about the location’s LocationType/ RetailLocationType/ AdditionalServices/ ProgramType.

1 1 1

Email address of the UPS location. Returned when available.

Yes* Cond

The UPS location's Fax number. A fax number of the location will be returned when available.Refer to the Universal Rules table for more information on phone number formats. 10 digits allowed for US, otherwise 1..15 digits allowed. The fax number will be returned as string.

Description

The UPS locations Phone number. A phone number of the location will be returned. 10 digits allowed for US, otherwise 1..15 digits allowed. The phone number will be returned as a string.

Code

DESCRIPTION

OptionType

/LocatorResponse/Search Results/DropLocation/Locati onAttribute/OptionType /LocatorResponse/Search Results/DropLocation/Locati onAttribute/OptionType/Code /LocatorResponse/Search Results/DropLocation/Locati onAttribute/OptionType/Descriptio n

Cond

LocationAttribute

/LocatorResponse/Search Results/DropLocation/Locati onAttribute

FaxNumber

Yes*

EMailAddress

/LocatorResponse/Search Results/DropLocation/FaxNu mber /LocatorResponse/Search Results/DropLocation/EMail Address

Yes*

PhoneNumber

/LocatorResponse/Search Results/DropLocation/Phone Number

Yes*

XPATH

Yes*

NAME

07/13/2015

REQUIRED

Locator Package XML

Page 83

LENGTH

DESCRIPTION

N/A

OptionType is a container that indicates the type of the location attribute. There are 4 types of attributes. They are: Location, RetailLocation, AdditionalServices and ProgramTypes. If search criteria by Location OptionType code 01, then all location types will be returned to the user.

TYPE Container String

MAXALLOWED 1

Category

/LocatorResponse/Search Results/DropLocation/Locati onAttribute/OptionCode/Category

OptionCode

/LocatorResponse/Search Results/DropLocation/Locati onAttribute/OptionCode

Yes*

XPATH

Yes*

NAME

07/13/2015

REQUIRED

Locator Package XML

Only applicabe for OptionType = 03 (Additional Services). Valid values are 06-Non transportation 07-Transportation

Page 84

LENGTH 1..10 1..50 1…50

Name will indicate the name Additional Services/ Program Types depending on the option code. Text will be displayed in the locale requested.

String

TYPE String String

MAXALLOWED

Description is only applicable for Location and Retail Location. The description for Program types and additional service is not provided with Location detail. It is only provided when the request is for All available additional services or all available Program types. Customer should be using Description section to retrieve the Location type information. Example of Location Type is UPS Access Point™. Text will be displayed in the locale requested.

Code for different Location types: '001' UPS Customer Center; '002' The UPS Store; please refer Appendix I for more Location Option Codes. The Retail Location Type codes change dynamically. The valid list of codes for different retail location types can be obtained by a separate type of request (Request Option 32, 40, 48 and 56).The Additional service codes change dynamically. The valid list of codes for different additional services can be obtained by a separate type of request (Request Option 8, 24, 40 and 56). The Program Type codes change dynamically. The valid list of codes for different program types can be obtained by a separate type of request (Request Option 16, 24, 48 and 56).

Name

DESCRIPTION

Description

/LocatorResponse/Search Results/DropLocation/Locati onAttribute/OptionCode/Descripti on /LocatorResponse/Search Results/DropLocation/Locati onAttribute/OptionCode/Name

Yes

Code

/LocatorResponse/Search Results/DropLocation/Locati onAttribute/OptionCode/Code

XPATH

Yes*

NAME

07/13/2015

REQUIRED

Locator Package XML

Page 85

LENGTH N/A

TransportationPickUpSchedule container contains details of Latest Drop Off time/Pickup Time for the transportations services (Ground/Air/Standard/Express/International) of the location.

N/A

PickUp container contains details of day of week and corresponding pickup times for that service.

Day of week. 1 = Sunday; 2 = Monday; 3 = Tuesday; 4=Wednesday; 5=Thursday; 6=Friday; 7=Saturday.

N/A

PickUpDetails container contains either pickup time or NoPickupIndicator. Either PickUpTime or NoPickupIndicator

TYPE Container Container String Container String String

DESCRIPTION

Pickup time of transportation service for a location in military format (HHMM) e.g. 0930, 1700, 1845 etc.

MAXALLOWED 1 Unbounded 1

Yes* Yes*

NoPickUpIndicator

PickUpTime

PickUpDetails

Yes*

DayOfWeek

Yes*

Pickup

Cond.

TransportationPickUpSchedule

XPATH /LocatorResponse/Search Results/DropLocation/Locati onAttribute/OptionCode/Transport ationPickUpSchedule /LocatorResponse/Search Results/DropLocation/Locati onAttribute/OptionCode/Transport ationPickUpSchedule/PickUp /LocatorResponse/Search Results/DropLocation/Locati onAttribute/OptionCode/Transport ationPickUpSchedule/PickUp/DayOfWeek /LocatorResponse/Search Results/DropLocation/Locati onAttribute/OptionCode/Transport ationPickUpSchedule/PickUp/PickUpDetails /LocatorResponse/Search Results/DropLocation/Locati onAttribute/OptionCode/Transport ationPickUpSchedule/PickUp/PickUpDetails/ PickUpTime /LocatorResponse/Search Results/DropLocation/Locati onAttribute/OptionCode/Transport ationPickUpSchedule/PickUp/PickUpDetails/ NoPickUpIndicator

Cond

NAME

07/13/2015

REQUIRED

Locator Package XML

Presence or Absence Indicator. If present, Indicates that there is no pickup time for the day. Page 86

LENGTH N/A

The crow flies distance from the origin to the UPS location.

1..4

The straight line distance from the origin to the UPS location. Distance value may include one decimal and followed by one decimal place.

N/A

The unit of measurement the user will see the distance is based on the user input provided in the search request.

The distance unit of measurement code. The unit of measurement used in the search request is returned. Values returned are:MI = Miles or KM = Kilometers.

5,10

May return the description of the unit of measure specified in the request. Valid values are:Miles or KM = Kilometers.

Variable N/A

Container String String

DESCRIPTION

Variable

Container String String

Container TYPE

MAXALLOWED 1 1 1 1

Yes* Yes* Yes*

String

LatestGroundDropOffTime

/LocatorResponse/Search Results/DropLocation/Latest GroundDropOffTime

SpecialInstructions

Segment

/LocatorResponse/Search Results/DropLocation/Speci alInstructions /LocatorResponse/Search Results/DropLocation/Speci alInstructions/Segment

Description

Code

Yes*

UnitOfMeasurement

/LocatorResponse/Search Results/DropLocation/Distan ce/UnitOfMeasurement /LocatorResponse/Search Results/DropLocation/Distan ce/UnitOfMeasurement/C ode /LocatorResponse/Search Results/DropLocation/Distan ce/UnitOfMeasurement/D escription

Value

Distance

/LocatorResponse/Search Results/DropLocation/Distan ce /LocatorResponse/Search Results/DropLocation/Distan ce/Value

Yes*

XPATH

Cond

NAME

07/13/2015

REQUIRED

Locator Package XML

Walking directions.

Walking directions, last 50 feet.

The latest ground time the users can Drop-off the package at the location to be picked up. The time information is based on the time at the UPS location. When a user specifies a Drop-off Time and Ground as the Service Type, the locations that have latest Drop-off times equal to or later than the specified Drop-off time and service type are returned.

Page 87

LENGTH 4..6 Variable Variable 1….6

The center number of the drop location if it is The UPS store.

1..255

Variable 0

TYPE String String String String String

The non-standard hours of operation of the drop location. The location's time may differ because of holidays, weekends, or other factors that are beyond the locations control. Seven days preceding a given holiday the Non Standard Hours Of Operation will be returned along with the standard hours of operation if available.

String

MAXALLOWED 1 1

Cond

The standard hours of operation of the drop location will be returned when available. The location's time may differ because of holidays.

HomePageURL

/LocatorResponse/Search Results/DropLocation/Home PageURL

Presence or Absence Indicator. If present, Indicates if the UPS location would have an additional charge. ASO locations will require an additional charge.

Number

/LocatorResponse/Search Results/DropLocation/Numb er

NonStandardHoursOfOperation

The latest airtime the users can Drop-off the package at the location to be picked up. The time information is based on the time at the UPS location. When a user specifies a Drop-off Time and Air as the Service Type, the locations that have latest Drop-off times equal to or later than the specified Drop-off time and service type are returned.

WillCallHoursOfOperation

/LocatorResponse/Search Results/DropLocation/NonSt andardHoursOfOperation /LocatorResponse/Search Results/DropLocation/WillCa llHoursOfOperation

DESCRIPTION

StandardHoursOfOperation

Cond

AdditionalChargeIndicator

/LocatorResponse/Search Results/DropLocation/Additi onalChargeIndicator /LocatorResponse/Search Results/DropLocation/Stand ardHoursOfOperation

LatestAirDropOffTime

/LocatorResponse/Search Results/DropLocation/Latest AirDropOffTime

XPATH

Zero or One Zero or One No

NAME

07/13/2015

REQUIRED

Locator Package XML

The home page URL of the drop location if it is The UPS store.

The will call hours of operation of the drop location will be returned when available. The location's time may differ because of holidays.

Page 88

LENGTH 1..255

TYPE

unbounded 1..255

Container Container String String String

String

MAXALLOWED 1 Unbounded 1 1 1

Yes*

Textual disclaimer about the drop location.

SLIC.

1..50

FacilityType

UPS Access Point™ Economy packages pickup time comment text.

TimeZone.

Timezone

String String

SLIC

Comment code is 01 for UPS Access Point™ Economy packages pickup time comment.

Disclaimer

/LocatorResponse/Search Results/DropLocation/Disclai mer /LocatorResponse/Search Results/DropLocation/SLIC /LocatorResponse/Search Results/DropLocation/Timez one /LocatorResponse/Search Results/DropLocation/Facilit

Comments returned about the location. Text will be displayed in the locale supported by country. If Country Code is FR, and locale passed in the request is “fr_FR” then text will be displayed in French language, else comment will be displayed in English language.

Container for CommentType Code and Text.

Text

DESCRIPTION

Container for Additional Comments about Location. Text will be displayed in the Locale requested.

Code

Yes*

CommentType

Yes*

AdditionalComments

/LocatorResponse/Search Results/DropLocation/Additi onalComments /LocatorResponse/Search Results/DropLocation/Additi onalComments/CommentType /LocatorResponse/Search Results/DropLocation/Additi onalComments/CommentType/Co de /LocatorResponse/Search Results/DropLocation/Additi onalComments/CommentType/Tex t

Cond

Comments

/LocatorResponse/Search Results/DropLocation/Comm ents

Yes*

XPATH

Cond

NAME

07/13/2015

Zero or One Zero or One REQUIRED

Locator Package XML

PKG/FRT. Page 89

LENGTH

DESCRIPTION

N/A

Operating Hours.

N/A

StandardHours Container.

Hours Type. Valid values are: 10-Regular Operating Hours; 11-Will Call Hours; 12= Same Day Will Call Hours; 50-Drop Off Hours; 51-Prep Hours; 14- Customer Pickup.

N/A

Day Of Week.

Day of week. 1 = Sunday; 2 = Monday; 3 = Tuesday; 4=Wednesday; 5=Thursday; 6=Friday; 7=Saturday.

Open time of a location in military format (HHMM) e.g. 930, 1700, 1845 etc. with exception for midnight. For midnight the time will be returned as 0.

TYPE Container Container String Container String String String

MAXALLOWED unbounded 1 1

Cond Cond

unbounded

CloseHours

OpenHours

Day

DayOfWeek

Yes*

HoursType

Yes*

StandardHours

/LocatorResponse/Search Results/DropLocation/Opera tingHours/StandardHours /LocatorResponse/Search Results/DropLocation/Opera tingHours/StandardHours/Ho ursType /LocatorResponse/Search Results/DropLocation/Opera tingHours/StandardHours/Da yOfWeek /LocatorResponse/Search Results/DropLocation/Opera tingHours/StandardHours/Da yOfWeek/Day /LocatorResponse/Search Results/DropLocation/Opera tingHours/StandardHours/Da yOfWeek/OpenHours /LocatorResponse/Search Results/DropLocation/Opera tingHours/StandardHours/Da yOfWeek/CloseHours

Yes*

OperatingHours

/LocatorResponse/Search Results/DropLocation/Opera tingHours

XPATH yType

NAME

07/13/2015

REQUIRED

Locator Package XML

Close time of a location in military format (HHMM) e.g. 930, 1700, 1845 etc. with exception for midnight. For midnight the time will be returned as 0. Page 90

LENGTH 4 4 0 4…5

Presence/ Absence Indicator. Presence denotes for the given day, if the location is open 24 hours. Absence denotes the location is not open for 24 hours on the given day.

N/A

LocalizedInstruction container. Applicable for SearchOptionCode 01,02,03

Container String

Locale

1..750

TYPE String String String String

MAXALLOWED 1 1 1

No No No

Presence absence Indicator. Indicator present mean location closed; Or else open.

String

Last50ftInstruction

PrepHours for Hour Type 51. Prep Hours of a location in military format (HHMM) e.g. 930, 1700, 1845 etc. with exception for midnight. For midnight the time will be returned as 0.

unbounded 1

Locale

LatestDropOffHours for Hour Type 50. Latest Drop Off time of a location in military format (HHMM) e.g. 930, 1700, 1845 etc. with exception for midnight. For midnight the time will be returned as 0.

LocalizedInstruction

/LocatorResponse/Search Results/DropLocation/Locali zedInstruction /LocatorResponse/Search Results/DropLocation/Locali zedInstruction/Locale /LocatorResponse/Search Results/DropLocation/Locali zedInstruction/Last50ftInstruction

DESCRIPTION

Open24HoursIndicator

ClosedIndicator

Cond

PrepHours

Yes*

LatestDropOffHours

XPATH /LocatorResponse/Search Results/DropLocation/Opera tingHours/StandardHours/Da yOfWeek/LatestDropOffHour s /LocatorResponse/Search Results/DropLocation/Opera tingHours/StandardHours/Da yOfWeek/PrepHours /LocatorResponse/Search Results/DropLocation/Opera tingHours/StandardHours/Da yOfWeek/ClosedIndicator /LocatorResponse/Search Results/DropLocation/Opera tingHours/StandardHours/Da yOfWeek/Open24HoursIndic ator

Yes*

NAME

07/13/2015

REQUIRED

Locator Package XML

Holds the additional instructions in each language supported by the country. The max length of the additional instruction text is 750 characters.

Page 91

LENGTH N/A 5 1..100 N/A 2 3

TYPE Container String

Container to hold the list of service offerings at the end point.

Container to hold the end point service offering code and description.

Container String

Holds the value of the facility location code.

String

Holds the value of the hub sort code or airport code

N/A

unbounded MAXALLOWED 1

This container is only for Freight Will call Search.

Promotion text for the given location.

No Yes* Yes*

Locale (language/ dialect) for the promotion code.

N/A

ServiceOffering

Container to hold any promotion text for the location.

Container String

ServiceOfferingList

/LocatorResponse/Search Results/DropLocation/Servic eOfferingList /LocatorResponse/Search Results/DropLocation/Servic eOfferingList/ServiceOffering

DESCRIPTION

Container

FreightSortFacilityCode

HubSortCode

unbounded 1

SortCode

/LocatorResponse/Search Results/DropLocation/SortC ode /LocatorResponse/Search Results/DropLocation/SortC ode/HubSortCode /LocatorResponse/Search Results/DropLocation/SortC ode/FreightSortFacilityCo de

Cond

Promotion

Locale

PromotionInformation

XPATH

Yes*

NAME

07/13/2015

REQUIRED

Locator Package XML

Page 92

LENGTH 3 1..35 1

Container String

N/A

String

1..15

The Public UPS Access Point™ ID associated with UPS Access Point™ .

String

1..255

Image URL associated with UPS Access Point™ .

String

1..10

TYPE String String

MAXALLOWED 1 1

Container for UPS Access Point™ specific parameters.

to display the telephone number to the end user.

Yes* Yes* No

Valid Values: 0 = Do not display phone number, 1 = Display phone number. This indicator will be returned only for the contact type Telephone number. This indicator is used by the clients to determine whether to display the telephone number to the end user.

LoadCapacityRatio

Description of the service offering. Text will be displayed in the locale requested.

ImageURL

The applicable values are: 001-Direct To Retail; 002-Not In One ADL; 003-Click and Collect; 004-Pickup, 005-Drop 0ff; 006-Drop Off Union;007-PUDO; 008-Early Pickup Delivery Time; 009-Accept prepaid drop offs; 010-DCO DCR intercept accepted; 011- Accepts Payments; 012-Pay At Store; 013-Accepts Restricted Articles.

PublicAccessPointID

DESCRIPTION

AccessPointInformation

/LocatorResponse/Search Results/DropLocation/Acces sPointInformation /LocatorResponse/Search Results/DropLocation/Acces sPointInformation/PublicAccessPoint ID /LocatorResponse/Search Results/DropLocation/Acces sPointInformation/ImageURL /LocatorResponse/Search Results/DropLocation/Acces sPointInformation/LoadCapacityRati

DisplayPhoneNumberIndicator

/LocatorResponse/Search Results/DropLocation/Displa yPhoneNumberIndicator

Code

Description

/LocatorResponse/Search Results/DropLocation/Servic eOfferingList/ServiceOffering/Cod e /LocatorResponse/Search Results/DropLocation/Servic eOfferingList/ServiceOffering/Des cription

XPATH

NAME

07/13/2015

REQUIRED

Locator Package XML

Page 93

MAXALLOWED

TYPE

LENGTH

Container

N/A

unbounded

Container

N/A

String

1..3

Business Classification code of UPS Access Point™. Please refer to appendix D for a list of business classification.

String

0..35

Description of business classification.

Container

N/A

Container to hold Business classification of UPS Access Point™.

AccessPointStatus

Container to hold list for business classification.

Description

DESCRIPTION

Code

Yes*

BusinessClassification

Yes*

BusinessClassificationList

/LocatorResponse/Search Results/DropLocation/Acces sPointInformation/BusinessClassific ationList /LocatorResponse/Search Results/DropLocation/Acces sPointInformation/BusinessClassific ationList/BusinessClassificatio n /LocatorResponse/Search Results/DropLocation/Acces sPointInformation/BusinessClassific ationList/BusinessClassificatio n/Code /LocatorResponse/Search Results/DropLocation/Acces sPointInformation/BusinessClassific ationList/BusinessClassificatio n/Description /LocatorResponse/Search Results/DropLocation/Acces sPointInformation/AccessPointStatu s

Yes*

XPATH o

NAME

07/13/2015

REQUIRED

Locator Package XML

Container for UPS AccessPoint status.

Page 94

MAXALLOWED

TYPE

LENGTH

String

1..35

String

1..10

Container

N/A

Container to hold the list of private networks.

Container

N/A

Container to hold the private network details.

String

1..10

Value of networkID.

String

1..50

Yes* Yes* No

Holds the value of facility SLIC of Access Point Location. Not implemented currently. For future use.

NetworkDescription

Description of status code.

unbounded

NetworkID

Valid status values are 01 = Active-available, 07 = Active-unavailable, 06 = Suspended, 08 = Terminated.

PrivateNetwork

DESCRIPTION

PrivateNetworkList

FacilitySLIC

Yes*

Description

Yes*

Code

XPATH /LocatorResponse/Search Results/DropLocation/Acces sPointInformation/AccessPointStatu s/Code /LocatorResponse/Search Results/DropLocation/Acces sPointInformation/AccessPointStatu s/Description /LocatorResponse/Search Results/DropLocation/Acces sPointInformation/FacilitySLIC /LocatorResponse/Search Results/DropLocation/Acces sPointInformation/PrivateNetworkLis t /LocatorResponse/Search Results/DropLocation/Acces sPointInformation/PrivateNetworkLis t/PrivateNetwork /LocatorResponse/Search Results/DropLocation/Acces sPointInformation/PrivateNetworkLis t/PrivateNetwork/NetworkI D /LocatorResponse/Search Results/DropLocation/Acces sPointInformation/PrivateNetworkLis t/PrivateNetwork/Network Description

Yes*

NAME

07/13/2015

REQUIRED

Locator Package XML

Description of the Network.

Page 95

MAXALLOWED

TYPE

LENGTH

Container

N/A

Container

N/A

String

Presence or absence indicator. Presence means the location is available for shipping.

Container

N/A

Container to hold shipping unavailable reason.

String

Code for shipping unavailability. Code for DCR/DCO unavailability. Codes are 01Temporarily Unavailable, 02-Location Full, 03-Unavailable, 04-Weather.

String

1..35

No Cond

Holds status of shipping availablity.

Description

Container to hold the status of shiping or DRC/DCO availability of a UPS Access Point™ .

Code

DESCRIPTION

UnavailableReason

Cond

AvailableIndicator

Cond

ShippingAvailability

Yes*

Availability

XPATH /LocatorResponse/Search Results/DropLocation/Acces sPointInformation/Availability /LocatorResponse/Search Results/DropLocation/Acces sPointInformation/Availability/Shippi ngAvailability /LocatorResponse/Search Results/DropLocation/Acces sPointInformation/Availability/Shippi ngAvailability/AvailableIndicator /LocatorResponse/Search Results/DropLocation/Acces sPointInformation/Availability/Shippi ngAvailability/UnavailableReason /LocatorResponse/Search Results/DropLocation/Acces sPointInformation/Availability/Shippi ngAvailability/UnavailableReason/Co de /LocatorResponse/Search Results/DropLocation/Acces sPointInformation/Availability/Shippi ngAvailability/UnavailableReason/De scription

Yes*

NAME

07/13/2015

REQUIRED

Locator Package XML

Description for shipping unavailability.

Page 96

LENGTH

DESCRIPTION

N/A

Holds status of DCR/DCO availablity.

Presence or absence indicator. Presence means the location is available for DCR/DCO.

N/A

Container to hold shipping unavailable reason.

Code for DCR/DCO unavailability. Codes are 01-Temporarily Unavailable, 02-Location Full, 03-Unavailable, 04-Weather.

1..35

Description for DCR/ DCO unavailability.

N/A

Location Image Container.

N/A

TYPE Container String Container String String Container String

MAXALLOWED 1 1 1 1

Cond Cond Yes*

Code

/LocatorResponse/Search Re-

UnavailableReason

SecureURL

AvailableIndicator

Yes*

LocationImage

/LocatorResponse/Search Results/DropLocation/Locati onImage

DCRAvailability

Cond

Description

XPATH /LocatorResponse/Search Results/DropLocation/Acces sPointInformation/Availability/DCRA vailability /LocatorResponse/Search Results/DropLocation/Acces sPointInformation/Availability/DCRA vailability/AvailableIndicator /LocatorResponse/Search Results/DropLocation/Acces sPointInformation/Availability/DCRA vailability/UnavailableReason /LocatorResponse/Search Results/DropLocation/Acces sPointInformation/Availability/DCRA vailability/UnavailableReason/Co de /LocatorResponse/Search Results/DropLocation/Acces sPointInformation/Availability/DCRA vailability/UnavailableReason/De scription

NAME

07/13/2015

REQUIRED

Locator Package XML

Secure URL for Location Image. Page 97

LENGTH

DESCRIPTION

N/A

Non Secure URL for Location Image.

N/A

Indicator for New Location.

N/A

Promotional link URL for specific location.

0...1

Null or blank would mean that this location is not featured, 1 = means that this location is featured location 1 and 2 = means that this location is featured location 2.

Y- Will call location If the value of this indicator is “Y” – that signifies a will call location which serves the customers address. "N" - that signifies it is not a will call indicator.

Map Navigation is a returned when the map is requested in the request document. Internal purpose only.

1..2

TYPE String String String String Container String

MAXALLOWED 1 1 1 1

Container String

Yes*

Cond

MapDimensions

/LocatorResponse/Search Results/MapNavigation/Map Dimensions

Number

/LocatorResponse/Search Results/MapNavigation /LocatorResponse/Search Results/MapNavigation/Num ber

MapNavigation

No No

WillCallLocationIndicator

/LocatorResponse/Search Results/DropLocation/WillCa llLocationIndicator

LocationNewIndicator

FeaturedRank

/LocatorResponse/Search Results/DropLocation/Featur edRank

NonSecureURL

PromotionalLinkURL

/LocatorResponse/Search Results/DropLocation/Locati onImage/NonSecureURL /LocatorResponse/Search Results/DropLocation/Locati onNewIndicator /LocatorResponse/Search Results/DropLocation/Promo tionalLinkURL

XPATH sults/DropLocation/Locati onImage/SecureURL

Cond

NAME

07/13/2015

REQUIRED

Locator Package XML

The location identifier where the user wants the icons to begin numbering. If the user does not supply a number the value returned is one.

Map Dimensions define the size of the map.

Page 98

LENGTH

DESCRIPTION

"The value provided in the request will be returned, else the default width of the image returned is set at 200 pixels. Other valid values are between 100 and 400"

"The value provided in the request will be returned, else the default width of the image returned is set at 200 pixels.Other valid values are between 100 and 400"

1..2

The factor the picture has to be in order to show all of the UPS locations. Refer to sections Zoom Factor.This value should be used in the map request if a map needs to be reproduced using the mapID

"The level to which the user wishes to pan on the X-axis.Never returned. Following the initial response the user may wish to view the image further to the left or to the right. To do so another request is required with a value of –1, 0, or 1."

"The level to which the user wishes to pan on the Y-axis.The initial request the default value is 0. Following the initial response the user may wish to view the image further up or down the y-axis. To do so another request is required with a value of –1, 0 or 1."

1…10

A list of 5 Location IDs are encrypted within the MapID for Map generation.

1…512

A Link to the map with the five UPS locations and the origin location specified in the MapID.

N/A

TYPE String String String

String

MAXALLOWED 1 1 1 1

String

Yes*

MapID

Container String

Yes*

No Yes*

ImageMap

/LocatorResponse/Search Results/MapNavigation/Imag eMap

PanY

MapURL

/LocatorResponse/Search Results/MapNavigation/Pan Y /LocatorResponse/Search Results/MapNavigation/MapI D /LocatorResponse/Search Results/MapNavigation/Map URL

PanX

/LocatorResponse/Search Results/MapNavigation/Pan X

ZoomFactor

/LocatorResponse/Search Results/MapNavigation/Zoo mFactor

Width

/LocatorResponse/Search Results/MapNavigation/Map Dimensions/Width

REQUIRED

Height

/LocatorResponse/Search Results/MapNavigation/Map Dimensions/Height

NAME

Yes*

XPATH

Yes*

07/13/2015

Yes*

Locator Package XML

Retains the image grid that is needed to determine the origin of the requests and the location of the UPS locations on the image grid. Page 99

LENGTH 10

The location ID of a particular UPS location.

The X coordinate of the UPS location.

TYPE String String

DESCRIPTION

The Y coordinate of the UPS location.

Required if the request document indicates Directions.

Variable

Step-by-step directions from the Origin to the specified location, including the last 10 feet (Special instructions).

1..4

The distance for that segment.Will not be returned for special instructions.

The calculated distance for that segment.Distance value may include one decimal and followed by one decimal place.

N/A

Container String

Container

Container String

MAXALLOWED 1

Yes*

1 1 unbounded 1

String

UnitOfMeasurement

Container

Value

Yes*

Distance

/LocatorResponse/Search Results/DrivingDirections/Dir ections/Distance /LocatorResponse/Search Results/DrivingDirections/Dir ections/Distance/Value /LocatorResponse/Search Results/DrivingDirections/Dir ections/Distance/UnitOfMea surement

Cond

Segment

Yes*

Directions

Cond

/LocatorResponse/Search Results/DrivingDirections/Dir ections /LocatorResponse/Search Results/DrivingDirections/Dir ections/Segment

/LocatorResponse/Search Results/DrivingDirections

XCoordinate

Yes*

DrivingDirections

LocationID

Yes*

YCoordinate

XPATH /LocatorResponse/Search Results/MapNavigation/Imag eMap/LocationID /LocatorResponse/Search Results/MapNavigation/Imag eMap/XCoordinate /LocatorResponse/Search Results/MapNavigation/Imag eMap/YCoordinate

Yes*

NAME

07/13/2015

REQUIRED

Locator Package XML

The unit of measurement the user will see the distance is based on the user input provided in the search request.

Page 100

LENGTH

DESCRIPTION

2..3

The distance unit of measurement code. The unit of measurement used in the search request is returned.Valid values are:“MI”

5,10

May return the description of the unit of measure specified in the request. Valid values are:“Miles”

4…6

The estimated time it will take for that segment. Time will not be provided for walking directions.Format: HHMM

N/A

The estimated total distance from the origin to the destination.The total distance can include one decimal, followed by one decimal place.

N/A

The estimated distance between the origin and the destination.

1..6

The calculated distance from the origin to the UPS location.Distance value may include one decimal and followed by one decimal place.

N/A

The unit of measurement the user will see the distance is based on the user input provided in the search request.

2..3

TYPE String String Container Container String String Container String

MAXALLOWED 1 1 1 1

No Cond

Code

UnitOfMeasurement

Yes*

Value

Yes*

Distance

/LocatorResponse/Search Results/DrivingDirections/To talDistance/Distance /LocatorResponse/Search Results/DrivingDirections/To talDistance/Distance/Value /LocatorResponse/Search Results/DrivingDirections/To talDistance/Distance/UnitOfMe asurement /LocatorResponse/Search Results/DrivingDirections/To talDistance/Distance/UnitOfMe asurement/Code

Yes*

Description

Cond

TotalDistance

/LocatorResponse/Search Results/DrivingDirections/To talDistance

Code

Yes*

Time

XPATH /LocatorResponse/Search Results/DrivingDirections/Dir ections/Distance/UnitOfMea surement/Code /LocatorResponse/Search Results/DrivingDirections/Dir ections/Distance/UnitOfMea surement/Description /LocatorResponse/Search Results/DrivingDirections/Dir ections/Time

Yes*

NAME

07/13/2015

REQUIRED

Locator Package XML

The distance unit of measurement code. The unit of measurement used in the search request is returned. Valid xalues are MI and KM Page 101

TYPE

LENGTH

String

"5,10" 4..6

Container

N/A

Container

N/A

String

1..50 N/A

Option code is a container that contains the information of a particular retail location type or additional service or program type that is available currently. One or more of this container will be returned to give all the available codes for Retail Type or Additional Services or Program Type.

Container

unbounded 1 1 1

String

MAXALLOWED 1

No Yes*

Description for Option type such as RetailLocation, AdditionalServices and ProgramType.

Code for Option type.

Code

unbounded

OptionCode

/LocatorResponse/Search Results/AvailableLocationAtt ributes/OptionCode

OptionType

The total estimated period of time it would take to drive from the origin to the location.Format: HHMM

OptionType is a container that indicates the type of the location attribute that are available. For example if the Option Type is RetailLocation the list of all available retail locations will be returned in 1 or many corresponding OptionCodes.

Yes*

Description

/LocatorResponse/Search Results/AvailableLocationAtt ributes/OptionType /LocatorResponse/Search Results/AvailableLocationAtt ributes/OptionType/Code /LocatorResponse/Search Results/AvailableLocationAtt ributes/OptionType/Descripti on

May return the description of the unit of measure specified in the request. Valid values are: Miles and Kilometer

This container contains the information about the currently existing Retail Locations or Additional Services or Program types.

Yes*

AvailableLocationAttributes

/LocatorResponse/Search Results/AvailableLocationAtt ributes

Description

DESCRIPTION

Yes*

TotalTime

XPATH /LocatorResponse/Search Results/DrivingDirections/To talDistance/Distance/UnitOfMe asurement/Description /LocatorResponse/Search Results/DrivingDirections/To talTime

Yes*

NAME

07/13/2015

REQUIRED

Locator Package XML

Page 102

LENGTH

DESCRIPTION

1..10

The valid list of codes and description for Retail Locations or Additional Services or Program Types that is currently available in the database. This can be obtained by a separate type of request (Request Option 8, 16, 24, 32, 40, 48 and 56).

1..50

Description is only applicable for Program types and Additional Services. It is not provided with Location detail. It is only provided when the request is for All available additional services or all available Program types. Text will be displayed in the locale requested.

1..50

Name will indicate the name of Location/Retail Location or Additional Services or Program Types depending on the option code. Text will be displayed in the locale requested. Text will be displayed in the locale requested.

TYPE String String String String

MAXALLOWED 1 1 1

/LocatorResponse/AllowA llConfidenceLevels

Description

AllowAllConfidenceLevels

Code

Yes*

Name

/LocatorResponse/Search Results/AvailableLocationAtt ributes/OptionCode/Code /LocatorResponse/Search Results/AvailableLocationAtt ributes/OptionCode/Descript ion /LocatorResponse/Search Results/AvailableLocationAtt ributes/OptionCode/Name

Yes*

XPATH

NAME

07/13/2015

REQUIRED

Locator Package XML

Confidence level.

Page 103

Locator Package XML

07/13/2015

1.9 Customer Integration Environment The Customer Integration Environment allows customers to test their application prior to launch. This environment is intended for integration testing of customer applications with the UPS servers. No stress testing should ever be performed by customers against any UPS systems. Once your application has been thoroughly tested, you should redirect the application to the UPS Production Environment. Please note that while the Customer Integration Environment maintains system availability 24 hours, 7 days each week, there are occasional system down times to allow for server maintenance.

Locator Test your Locator application with locations in the following locales. Note: In the Customer Integration Environment, Locator will only work in the following locales: Country Country United States Canada Germany Mexico

City Atlanta Toronto Neuss Mexico City

For integration testing, you should direct your Locator software to https://wwwcie.ups.com/ups.app/xml/Locator.

1.9.1 System Availability The Customer Integration Environment is available 24 hours a day, 7 days a week.

1.9.2 Server Availability Check All of the UPS services work using HTTPS POST. Using the same URL as you point your application to, perform an HTTP GET. If the server is available, it will reply with the service name, remote user, server port, server name and servlet path. To see this in action, type the following URL in your web browser: https://wwwcie.ups.com/ups.app/xml/Locator. You should see the following in the browser window: Service Name: Locator Remote User: null Server Port: 80 Server Name: /wwwcie.ups.com Servlet Path: /ups.app

Page 104

Locator Package XML

07/13/2015

Appendix A - Accessing Tech Support (US Site Example) Go to ups.com and log in to myUPS with your ID and PW. Hover over the “Support” tab, and select “Technology Support” from the drop-down.

Page 105

Locator Package XML

07/13/2015

From the Technology Support page select the Developer Resource Center link from the left navigation.

Page 106

Locator Package XML

07/13/2015

From the Developer Resource Center page select the “Email UPS” link in right hand column.

Complete Name, email address, Support Category must be “Technical Support”, and Support Topic must be “Developer Resource”. Select the “Next” button.

Page 107

Locator Package XML

07/13/2015

Scroll down the page and complete the remainder of the email form including “Your Telephone”, “Stage of Development”, “Developer Resource” which is which API you are integrating, “Attach File” where you attach your XML Request/Response Pair, and any pertinent description of the issues in the “What is your question or comment?” field. Select “Send Email” button.

The screen below will appear. Please see “Technical Support (US)” within this document for tech support hours of operation and response times.

Page 108

Locator Package XML

07/13/2015

Appendix B – Locator Error Codes To discover errors, check the ResponseStatusCode element. A “1” normally indicates a successful response, whereas a “0” indicates an error, either Transient or Hard. When an error occurs there will also be an error code, and an error description. Success – Successful responses may or may not include Warnings.  (without warnings) Request is processed as anticipated by the client.  (with warnings) Warning messages indicate that UPS was able to process the request; however (potentially) unanticipated results have also occurred. The warning contains information in the response that should be passed to the end user. Errors – will return two different levels of severity.  Transient errors are temporary errors, due to temporary high server loads or scheduled maintenance, for example. The application may re-issue the request at a later time.  Hard errors indicate that an error existed in the request that UPS could not resolve. These errors are critical and prevent requests from processing. Applications should not re-issue requests with Hard errors without first correcting the error. The following table lists the errors that UPS may return in response to a request. Error Code

Severity

Description

350002

Hard

Maximum list size is invalid. It cannot be less than 1 or greater than 50.

350003

Hard

Landmark code is invalid. It cannot be less than 1 or greater than 16.

350004 350005

Hard Hard

350006

Hard

350007 350008 350009 350010 350019 350020 350021 350022 350023 350024 350027 350028 350029

Hard Hard Hard Hard Hard Hard Hard Hard Hard Hard Hard Hard Hard

350031 350032

Hard Hard

Search Radius is invalid. It cannot be less than 5 and greater than 100. The unit of measurement is invalid. Valid value is MI and KM. Map Height is invalid. Valid value is an integer, greater than 100 or less than 400. Map Width is invalid. Valid value is an integer, greater than 100 or less than 400. Zoom Factor is invalid. It cannot be less than 0 or greater than 15. Request option is not supplied or is invalid. The Pan Value is invalid. Valid values are -1, 0, or 1. The latitude value is invalid. It should be a number. The longitude value is invalid. It should be a number. The maximum list size is invalid. It should be a number. Search radius is invalid. It should be a number. Time is invalid. Valid format is HHMM. Map Start Number is not valid. Zoom Factor is not an integer. Pan X is not an integer. Pan Y is not an integer. Service code that indicates ground or air is required when service time is present. More origin information must be provided to complete the request.

350035

Hard

350036

Hard

The Latitude is missing. It is required if geocode is present in the request. The Longitude is missing. It is required if geocode is present in the request.

Page 109

Locator Package XML

07/13/2015

Error Code 350037 350038 350039 350040 350041 350042 350043 350044

Severity Hard Hard Hard Hard Hard Hard Hard Hard

Description SearchOption node should contain OptionType node. SearchOption node should contain OptionCode node. Saturday pick up is only applicable for air. The request action is invalid. Location ID is required for Request Option 2 The maximum candidate list size supplied is not valid. Location ID is required for DrivingDirections request. Origin geocode is required for request option 2.

350045

Hard

Both location type and retail location type are present in the request.

350046 350047 350048 350049 350050 350051 350052 350102 350103 350104 350105 350201 350202 350203 350204 350205 350206 350208 350209 350210 350212 350216 350217 350218 355001 355002 355003 350106

Hard Hard Hard Hard Hard Hard Hard Hard Hard Hard Hard Hard Hard Hard Hard Hard Hard Hard Hard Hard Hard Hard Hard Hard Transient Transient Transient Hard Hard

Option type code is invalid . Valid values are, 01, 02, 03, 04 and 05. Relation parameter is invalid. Valid values are 01 and 02. Service code is invalid. Valid values are 01, 02, 03 and 04. Service option code is invalid. Valid values are 01. Willcallsearch node should include SLIC. Willcallsearch node should include postal code. Willcallsearch node should include country code. The Country code is missing. The language code is missing. The country code is invalid. Valid Value is US. The language code is invalid. Valid value is ENG. Unable to find any locations. Geocode was expected for this request. Unable to produce results. Unable to retrieve driving directions. Unable to produce a geospatial coordinate from the request. The Program type code provided is invalid. Request Option is invalid. Additional Services code provided is Invalid. Will call Locations not found. Invalid Retail Location Type code. There are no available additional services. There are no available retail location types. There are no available program types. The locator service is unavailable. No map was produced. The Locator system is temporarily unavailable. The city is not supported in the Customer Integration Environment

350107 350214 350221 355004 355005 355006 355007 355008 355009 355010

Hard Hard Hard Hard Hard Hard Hard Hard Hard

The country is not supported in the Customer Integration Environment. A map could not be rendered. The search criteria did not return any results. Missing or Invalid Search Option Code for Freight Location Search. Missing ServiceGeoUnit Container for Freight Location Search. Missing or Invalid ServiceCode for Freight Location Search. Missing or Invalid GeoPoliticalUnit for Freight Location Search. Ambiguous Locations. Do not use freight location code (17) or freight Indicator (FreightIndicator) with any other valid small package location option codes. Missing or Invalid Freight Will Call Search Request Type.

Page 110

Locator Package XML

Error Code 355011 355012 355013 355014 355015 355016 355017 355018 355019 355020 355021 355022 355023 355024 335042

Severity Hard Hard Hard Hard Hard Hard Hard Hard Hard Hard Hard Hard Hard Hard Hard Hard

335044 Hard 335046 335047 335049 335051

Hard Hard Hard Hard

07/13/2015

Description Missing SLIC. SLIC exceeds the maximum number of 20. Missing Postal Code. Postal Code exceeds the maximum number of 20. Missing City, State or Province Deliver City or State exceeds the maximum number of 20. Invalid Day Of Week Code. Missing or Invalid Format Postal Code. Missing or Invalid Locale. Missing required data. Please verify the request parameters and try again. Location not found for postal code country. Location not found for non Postal code country. Missing or Invalid OriginOrDestination value. Invalid Postal Code or Country Code. Search Criteria missing for AccessPointSearch by Address. AccessPointSearch/ExcludeFromResult/Raduis and IncludeCriteria/MerchantAccountNumberList/MerchantAccountNumber are both required. AccessPointSearch invalid if both UPS Account Number and PublicAccessPointID present. AccessPointSearch can search by maximum 50 MerchantAccountNumber AccessPointSearch can search by excluding maximum 50 BusinessClassificationCode. AccessPointSearch can search by excluding maximum 50 PostalCodes. AccessPointSearch/IncludeCriteria/SearchFilter/ShipperPreparationDelay exceeds maximum value.

335059

XML Errors Error Code 10001

Severity Hard

Description The XML document is not well formed.

10002

Hard

The XML document is well formed but the document is not valid.

10003

Hard

The XML document is either empty or null

10006

Hard

10013

Hard

Although the document is well formed and valid, the element content contains values which do not conform to the rules and constraints contained in this specification The message is too large to be processed by the Application

Page 111

Locator Package XML

07/13/2015

Appendix C – Service Level Options and Location Types Shipping

Drop Off Staffed

Drop Off Unstaffed

Collection and Prepaid Drop Off

Argentina (AR)

Australia (AU)

Austria (AT)

Azerbaijan (AZ)

Bahamas (BS)

Bahrain (BH)

Belgium (BE)

Bermuda (BM)

Bolivia (BO)

Bosnia (BA)

Brazil (BR)

Canada (CA)

Cayman Islands (KY)

Chile (CL)

Colombia (CO)

Costa Rica (CR)

Croatia (HR)

Denmark (DK) Dominican Republic (DO)

Ecuador (EC)

Egypt (EG)

El Salvador (SV)

Finland (FI)

France (FR)

Germany (DE)

Ghana (GH)

Gibraltar (GI)

Guatemala (GT)

Honduras (HN)

Indonesia (ID)

Ireland (IE)

Italy (IT)

Full Service

Shipping & Drop Off

Albania (AL)

Algeria (DZ)

Country

Page 112

Locator Package XML

07/13/2015

Kenya (KE)

Khazakstan (KZ)

Kuwait (KW)

Luxembourg (LU)

Malaysia (MY)

Malta (MT)

Mauritius (MU)

Mexico (MX)

Moldova (MD)

Morocco (MA)

Netherlands (NL)

New Zealand (NZ)

Nicaragua (NI)

Nigeria (NG)

Norway (NO)

Oman (OM)

Pakistan (PK)

Panama (PA)

Paraguay (PY)

Peru (PE)

Philippines (PH)

Portugal (PT)

Puerto Rico (PR)

Qatar (QA)

Saudi Arabia (SA)

Serbia (RS)

Singapore (SG)

South Africa (ZA)

Spain (ES)

Sweden (SE)

Switzerland (CH)

Thailand (TH) United Arab Emirates (AE)

United Kingdom (GB)

United States (US)

Uruguay (UY)

US Virgin Islands (VI)

Venezuela (VE)

Page 113

Locator Package XML

07/13/2015

Note: MBE can be found in countries that do not have The UPS Store. When MBE and The UPS Store are in the same country, MBE is categorized as a Authorized Shipping Outlet.

Page 114

Locator Package XML

07/13/2015

Appendix D – Business Classification Codes for UPS Access Point™ s Business Classification Type Code

Business Classification Type Name

001 002 003 004 005 006 007 008 009 010 011 012 013 014 015 016 017 018 019 020 021 022 023 024 025 026 027 028 029 030 031 032 033 034 035 036 037 038

BAKERY BOOKSTORE CHEMIST'S / PHARMACY CLOTHES_SHOES CONVENIENCE_SHOP DRY_CLEANING DRUGSTORE ELECTRONICS_SHOP FLOWER_SHOP FRUIT_STAND FOOD_SHOP GAS_STATION GROCERY_STORE GIFT_SHOP HARDWARE_STORE HOME_FURNISHING HOTEL_RESTAURANT NIGHT_SHOP LIQUOR_STORE NEWSSTAND OTHER PET_SHOP PHOTO_SHOP RECORD_SHOP SUPERMARKET SHOE_STORE SWEET_SHOP TOBACCO_SHOP TELECOM_STORE VIDEO_STORE VEGETABLE_STORE OFFICE SUPPLIES PACK AND SHIP BEAUTY SUPPLY GENERAL GOODS TOY STORE COBBLER/SHOE REPAIR ALTERATIONS

Page 115

Locator Package XML

07/13/2015

Appendix E – Service Offering Code for UPS Access Point™ s End Point Service Offering Codes 001

002 003

004 005 006

007 008 009

010

011 012 013

Detailed description A commercial business sends a shipment to an authorized retail destination where it is held for the final consignee to claim A shipment that failed the first delivery at the consignees address, could not be redirected to a neighbor, and was redirected by UPS to a nearby UPS Access Point™ Click and Collect Consumer to consumer shipping option for shipments that are dropped off at a UPS Access Point™ and sent to a UPS Access Point™ for the final consignee to claim UPS Access Point™ allows customers to only Pickup/Collect shipments UPS Access Point™ allows customer to only Drop Off shipments Spare parts logistics for service engineers & technicians through the UPS Access Point™ network for picking up and dropping off parts at convenient locations The UPS Access Point™ is open early to allow consignees to Pick-up/Collect of packages UPS Access Point™ can accept packages that already have an acceptable ups shipping label with tracking number When a delivery change request to a retail location has been completed by Delivery Change Option (DCO) in Mychoice - preferences and Delivery Change Request (DCR) at ups.com The location will have the capability to accept monies for Cash on Delivery (COD). and International Cash on Delivery (ICOD) shipments to the UPS Access Point™ locations The location will have the capability to filter it with Pay At Store feature. The location will have the capability to filter it with Accepts Restricted Articles feature.

Appendix F - Frequently Asked Questions: Locator

API All

Category General - security

Question Does UPS support chained or unchained digital certificates?

Answer Currently, the Ship API uses an unchained cert which will be migrated to chained Sept '09. In the case of the Ship API, INET is responsible for those urls and corresponding Digital Certs. They are being renewed at the end of this month as unchained. They will migrate to chained in Sept '09.

Page 116

Locator Package XML

07/13/2015

API All

Category API availability

Question Within what countries are the Developer APIs available?

All

Mail Innovations

Is Mail Innovations available within any of the Developer APIs?

All

UPS Logos High Resolution

How do I get access to higher resolution logos than what are available within the downloads for the UPS Developer Kit Developer APIs?

All

Technical Support email form Technical Support email form

Is XPCI a required field within the email support form? From where is XPCI version number obtained and what does it mean?

All

Answer The Developer APIs are available in the countries listed at ups.com by API and by country under the UPS Developer Kit - Developer APIs. Click on any particular API to go to the API page and scroll to the bottom of the page to get the country listing for that particular API. There is no UPS API available for Mail Innovations services at this time nor did we see one at http://www.upsmailinnovations.com. Additionally we are not aware of any plans to support the services through the UPS Developer APIs. The customer may however contact a Mail Innovations representative by clicking the Support tab of the site for any additional questions or concerns. Customers are not routinely provided these UPS shield graphics without having a design/layout submitted to UPS Brand Management for approval. The customer needs to visit: https://www.upsbrandexchange.com/brandHome.awsp This site will take them through the process for downloading a limited set of sample images for layout, and how to secure an approval for customer use, as well as the high-resolution graphics. No.

XPCI stands for XML Package Carrier Interface (XPCI) and defines a vocabulary and structure for describing packages, shipments, and the activity details for package carriers and their customers. XPCI is a set of DTDs that defines the terminology, transaction enveloping, and XML message definitions. For a client to be XPCI-compliant, the client must generate a wellformed XML message that validates against the XPCI DTDs. Several DTDs, organized into three categories, define XPCI: Vocabulary — This DTD defines the basic business vocabulary of XPCI. All tags used in a message are defined in this DTD. Interchange — This DTD defines the transactionenveloping scheme. Every message includes transaction information. Message — Each message has an associated DTD that defines the vocabulary of the message. The version and date would have been related to versioning however the APIs were not versioned so they

Page 117

Locator Package XML

07/13/2015

API