Installs: 4 648

Dependents: 3

Stars: 87

Watchers: 20

Forks: 69

Open Issues: 1

Language: PHP

0.6.0 2015-09-25 14:16 UTC


Build Status StyleCI Scrutinizer Code Quality Code Coverage Code Climate Latest Stable Version Total Downloads License SensioLabsInsight Join the chat at

This library is aimed at wrapping all the UPS API into a simple to use PHP Library. It currently covers the Quantum View®, Tracking API, Shipping API, Rating API and Time in Transit API. Feel free to contribute.

Table Of Content

  1. Requirements
  2. Installation
  3. Address Validation Class
  4. QuantumView Class
  5. Tracking Class
  6. Rate Class
  7. TimeInTransit Class
  8. Locator Class
  9. Shipping Class
  10. Logging
  11. License


This library uses PHP 5.5+.

To use the UPS API, you have to request an access key from UPS. For every request, you will have to provide the Access Key, your UPS User ID and Password.


It is recommended that you install the PHP UPS API library through composer. To do so, run the Composer command to install the latest stable version of PHP UPS API:

composer require gabrielbull/ups-api

Address Validation Class (Street Level)

The Address Validation Class allow you to validate an address at street level. Suggestions are given when address is invalid.

Note: UPS has two Address Validations. This is Street Level option, which includes all option of the normal Address Validation class and adds street level validation.

Not all countries are supported, see UPS documentation. Currently US & Puerto Rico are supported.


$address = new \Ups\Entity\Address();
$address->setAttentionName('Test Test');
$address->setAddressLine1('Address Line 1');
$address->setAddressLine2('Address Line 2');
$address->setAddressLine3('Address Line 3');
$address->setCity('New York');     

$xav = new \Ups\AddressValidation($accessKey, $userId, $password);
try {
    $response = $xav->validate($address, $requestOption = \Ups\AddressValidation::REQUEST_OPTION_ADDRESS_VALIDATION, $maxSuggestion = 15);
} catch (Exception $e) {


Adress Validation parameters are:

  • address Address object as constructed in example
  • requestOption One of the three request options. See documentation. Default = Address Validation.
  • maxSuggestion Maximum number of suggestions to be returned. Max = 50

QuantumView Class

The QuantumView Class allow you to request a Quantum View Data subscription.


$quantumView = new Ups\QuantumView($accessKey, $userId, $password);

try {
    // Get the subscription for all events for the last hour
    $events = $quantumView->getSubscription(null, (time() - 3600));

    foreach($events as $event) {
        // Your code here
        echo $event->Type;

} catch (Exception $e) {


QuantumView parameters are:

  • name Name of subscription requested by user. If null, all events will be returned.
  • beginDateTime Beginning date time for the retrieval criteria of the subscriptions. Format: Y-m-d H:i:s or Unix timestamp.
  • endDateTime Ending date time for the retrieval criteria of the subscriptions. Format: Y-m-d H:i:s or Unix timestamp.
  • fileName File name of specific subscription requested by user.
  • bookmark Bookmarks the file for next retrieval.

If you provide a beginDateTime, but no endDateTime, the endDateTime will default to the current date time.

To use the fileName parameter, do not provide a beginDateTime.

Tracking Class

The Tracking Class allow you to track a shipment using the UPS Tracking API.


$tracking = new Ups\Tracking($accessKey, $userId, $password);

try {
    $shipment = $tracking->track('TRACKING NUMBER');

    foreach($shipment->Package->Activity as $activity) {

} catch (Exception $e) {


Tracking parameters are:

  • trackingNumber The package’s tracking number.
  • requestOption Optional processing. For Mail Innovations the only valid options are Last Activity and All activity.

Rate Class

The Rate Class allow you to get shipment rates using the UPS Rate API.


$rate = new Ups\Rate(

try {
    $shipment = new \Ups\Entity\Shipment();

    $shipperAddress = $shipment->getShipper()->getAddress();

    $address = new \Ups\Entity\Address();
    $shipFrom = new \Ups\Entity\ShipFrom();


    $shipTo = $shipment->getShipTo();
    $shipTo->setCompanyName('Test Ship To');
    $shipToAddress = $shipTo->getAddress();

    $package = new \Ups\Entity\Package();

    $dimensions = new \Ups\Entity\Dimensions();

    $unit = new \Ups\Entity\UnitOfMeasurement;



} catch (Exception $e) {


  • rateRequest Mandatory. rateRequest Object with shipment details

This Rate class is not finished yet! Parameter should be added when it will be finished.

TimeInTransit Class

The TimeInTransit Class allow you to get all transit times using the UPS TimeInTransit API.


$timeInTransit = new Ups\TimeInTransit($access, $userid, $passwd);

try {
    $request = new \Ups\Entity\TimeInTransitRequest;

    // Addresses
    $from = new \Ups\Entity\AddressArtifactFormat;    

    $to = new \Ups\Entity\AddressArtifactFormat;

    // Weight
    $shipmentWeight = new \Ups\Entity\ShipmentWeight;
    $unit = new \Ups\Entity\UnitOfMeasurement;

    // Packages

    // InvoiceLines
    $invoiceLineTotal = new \Ups\Entity\InvoiceLineTotal;

    // Pickup date
    $request->setPickupDate(new DateTime);

    // Get data
    $times = $timeInTransit->getTimeInTransit($request);

    foreach($times->ServiceSummary as $serviceSummary) {

} catch (Exception $e) {


  • timeInTransitRequest Mandatory. timeInTransitRequest Object with shipment details, see example above.

Locator Class

The Locator class allows you to search for UPS Access Point locations.


$locatorRequest = new \Ups\Entity\LocatorRequest;

$originAddress = new \Ups\Entity\OriginAddress;
$address = new \Ups\Entity\AddressKeyFormat;

$geocode = new \Ups\Entity\GeoCode;

$translate = new \Ups\Entity\Translate;

$acccessPointSearch = new \Ups\Entity\AccessPointSearch;

$locationSearch = new \Ups\Entity\LocationSearchCriteria;


$unitOfMeasurement = new \Ups\Entity\UnitOfMeasurement;

try {
    // Get the locations
    $locator = new Ups\Locator($accessKey, $userId, $password);
    $locations = $locator->getLocations($locatorRequest, \Ups\Locator::OPTION_UPS_ACCESS_POINT_LOCATIONS);

    foreach($locations->SearchResults->DropLocation as $location) {
        // Your code here

} catch (Exception $e) {


Locator class parameters are:

  • locatorRequest Mandatory. locatorRequest object with request details, see example
  • requestOption Optional. Type of locations you are searching for.

Shipping Class.

Documentation for this class is coming.


All constructors take a PSR-3 compatible logger.

Besides that, the main UPS class has a public method setLogger to set it after the constructor ran.

Requests & responses (including XML, no access keys) are logged at DEBUG level. At INFO level only the event is reported, not the XML content. More severe problems (e.g. no connection) are logged with higher severity.

Example using Monolog

// Create logger
$log = new \Monolog\Logger('ups');
$log->pushHandler(new \Monolog\Handler\StreamHandler('logs/ups.log', \Monolog\Logger::DEBUG));

// Create Rate object + insert logger
$rate = new Ups\Rate($key, $username, $password, $useIntegration, $log);


PHP UPS API is licensed under The MIT License (MIT).