Welcome to the UpsLocator SDK documentation. This guide will help you get started with integrating and using the UpsLocator SDK in your project.
- SDK version:
1.0.0
Search for UPS shipping locations based on type and available services. In order to obtain your bearer token please follow the instructions at https://developer.ups.com/get-started, or use the UPS Authorization API.
This SDK is compatible with the following versions: TypeScript >= 4.8.4
To get started with the SDK, we recommend installing using npm:
npm install ups_locatorThe UpsLocator API uses Basic Authentication.
You need to provide your username and password when initializing the SDK.
When you initialize the SDK, you can set the username and password as follows:
const sdk = new UpsLocator({ username: 'YOUR_USERNAME', password: 'YOUR_PASSWORD' });If you need to set or update the username and password after initializing the SDK, you can use:
const sdk = new UpsLocator();
sdk.username = 'YOUR_USERNAME';
sdk.password = 'YOUR_PASSWORD';The SDK provides various services to interact with the API.
Below is a list of all available services with links to their detailed documentation:
| Name |
|---|
| LocationsService |
| DeprecatedService |
The SDK includes several models that represent the data structures used in API requests and responses. These models help in organizing and managing the data efficiently.
Below is a list of all available models with links to their detailed documentation:
| Name | Description |
|---|---|
| LocatorRequestWrapper | N/A |
| LocatorResponseWrapper | N/A |
| LocatorRequest | N/A |
| LocatorRequestRequest1 | N/A |
| LocatorRequestOriginAddress | Container for origin address information. |
| LocatorRequestTranslate | Contains the locale information for the request. |
| LocatorRequestUnitOfMeasurement | Distance unit of measurement. This is required for location requests (request option 1). |
| LocatorRequestLocationSearchCriteria | 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). |
| LocatorRequestSortCriteria | Container for Sort Criteria |
| LocatorRequestServiceGeoUnit | ServiceGeoUnit Container. Required to search for the freight facility information |
| RequestTransactionReference | TransactionReference identifies transactions between client and server. |
| OriginAddressAddressKeyFormat | Contains all of the basic information about the origin such as: Address Lines, City, State/Province, Postal Code and Country or Territory Code. The element CountryCode is required. |
| OriginAddressGeocode | Geocode is the latitude and longitude of the origin address. |
| LocationSearchCriteriaSearchOption | SearchOption contains the information that forms the basis of the location search, It contains the criteria for search by Locations, Retail Locations, Additional Services, or Program Types. 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 Retail Locations, 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. |
| LocationSearchCriteriaServiceSearch | Allows for users to further define the search criteria. Refer to the rules specified in Service Search section. |
| LocationSearchCriteriaFreightWillCallSearch | Freight Will Call Search Container. Required if SearchOption is '05-Freight Will Call Search' |
| LocationSearchCriteriaAccessPointSearch | Applicable for request option 64 only. This contains inclusion and exclusion criteria for address search. It also contains Account Number and Access Point Public ID search elements. |
| LocationSearchCriteriaOpenTimeCriteria | Container to hold open times of the Location. |
| SearchOptionOptionType | OptionType is a container that indicates the type of search for locations. There are 5 types of search. They are search by: Location, Retail Location, Additional Services, Program Type, and a Service Level Option. If search criteria by Location or Retail Location is not provided the default search of The UPS Store, UPS Center, UPS Drop Box, and Authorized Shipping Outlet location types will be performed. |
| SearchOptionOptionCode | Option code contains the information of a particular Location, Retail Location, Additional Service, Program Type or End Point Service Offering depending on the option type. The SearchOptions can contain one or more OptionCodes which forms the criteria for the location search. |
| SearchOptionRelation | 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 Additional Services and Program Types. If this container is not present for Additional Services and Program Types, the default relation of And is used. |
| ServiceSearchServiceCode | Container that contains the service information such as Ground/Air. Required if the customer provides ServiceSearch Time. |
| ServiceSearchServiceOptionCode | Container for the optional service information such as Saturday Pick up. |
| FreightWillCallSearchFacilityAddress | Facility Address Container |
| AccessPointSearchIncludeCriteria | This contains elements to refine (include) UPS Access point address or geocode Search. |
| AccessPointSearchExcludeFromResult | This contains elements to exclude from UPS Access Point address or geocode search. |
| IncludeCriteriaMerchantAccountNumberList | This contains the list of Merchant Account numbers to be used for finding private network access points. |
| IncludeCriteriaSearchFilter | Container to hold one or more search criteria for UPS Access Points that allow DCR, Shipping and ClickAndCollect access. Only applicable when the UPS access point candidate list is obtained in search by address or geocode search. |
| IncludeCriteriaServiceOfferingList | Container to hold end point service offering List for UPS Access point. Applicable only when a UPS Access Point candidate list is obtained in search by address or geocode search. |
| ServiceOfferingListServiceOffering | |
| ExcludeFromResultPostalCodeList | Container to hold a list of postal codes to exclude from the access point address or geocode search. |
| PostalCodeListPostalCode | Container to hold the postal code . |
| LocatorResponse | Container for LocatorResponse. |
| LocatorResponseResponse1 | Container for Response. |
| LocatorResponseSearchResults | Container for search results. |
| LocatorResponseGeocode | 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.Will not be returned when the requestoption =64 |
| ResponseTransactionReference | Container for customer provided data and the XPCI Version. |
| ResponseError | 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. |
| ErrorErrorLocation | |
| SearchResultsGeocodeCandidate | |
| SearchResultsDropLocation | |
| SearchResultsAvailableLocationAttributes | |
| GeocodeCandidateAddressKeyFormat | Contains all of the basic information about candidate address. |
| GeocodeCandidateGeocode | Geocode is the latitude and longitude of the origin candidate. |
| DropLocationIvr | Integrated Voice Response information. ONLY FOR IVR. |
| DropLocationGeocode | Geocode is the latitude and longitude of the location address. The Geocode for the location address will be returned when Location is requested in the Request Option. |
| DropLocationAddressKeyFormat | Contains all of the basic information about a location, Consignee Name, Building Name, Address Lines, City, State/Province, Postal Code and Country or Terriotry Code. |
| DropLocationLocationAttribute | LocationAttribute is a container that contains the information about the location's Location Type, Retail Location Type, Additional Services, or Program Type. |
| DropLocationDistance | Container for the straight line distance from the origin to the UPS location. |
| DropLocationSpecialInstructions | |
| DropLocationAdditionalComments | Container for Additional Comments about Location.Text will be displayed in the Locale requested. |
| DropLocationOperatingHours | Operating Hours. |
| DropLocationLocalizedInstruction | |
| DropLocationPromotionInformation | |
| DropLocationSortCode | This container is only for Freight Will call Search. |
| DropLocationServiceOfferingList | Container to hold the list of service offerings at the end point. |
| DropLocationAccessPointInformation | Container for UPS Access Point specific parameters. |
| DropLocationLocationImage | Location Image container. |
| LocationAttributeOptionType | |
| LocationAttributeOptionCode | |
| OptionCodeTransportationPickUpSchedule | TransportationPickUpSchedule container contains details of Latest Drop Off time/Pickup Time for the transportation services (Ground/Air/Standard/Express/International) of the location. |
| TransportationPickUpSchedulePickUp | |
| PickUpPickUpDetails | PickUpDetails container contains either pickup time or NoPickupIndicator. Either PickUpTime or NoPickupIndicator |
| DistanceUnitOfMeasurement | The unit of measurement the user will see for the distance is based on the user input provided in the search request. |
| AdditionalCommentsCommentType | |
| OperatingHoursStandardHours | |
| StandardHoursDayOfWeek | |
| AccessPointInformationBusinessClassificationList | Container to hold list for business classification. |
| AccessPointInformationAccessPointStatus | Container for UPS AccessPoint status. |
| AccessPointInformationPrivateNetworkList | Container to hold the list of private networks. |
| AccessPointInformationAvailability | Container to hold the status of shipping or DRC/DCO availability of a UPS Access Point. |
| BusinessClassificationListBusinessClassification | |
| PrivateNetworkListPrivateNetwork | |
| AvailabilityShippingAvailability | Holds status of shipping availability. |
| AvailabilityDcrAvailability | Holds status of DCR/DCO availability. |
| ShippingAvailabilityUnavailableReason | Container to hold shipping unavailable reason. |
| DcrAvailabilityUnavailableReason | Container to hold shipping unavailable reason. |
| AvailableLocationAttributesOptionType | 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. |
| AvailableLocationAttributesOptionCode | 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. |
| AvailableLocationAttributesOptionCodeTransportationPickUpSchedule | Container to hold information regarding pickup details for each day of the week. |
| AvailableLocationAttributesTransportationPickUpSchedulePickUp | |
| AvailableLocationAttributesPickUpPickUpDetails | Container to hold information regarding pickup time and pickup availability indicator. |
This SDK is licensed under the MIT License.
See the LICENSE file for more details.