We do a lot of shipping - tens of thousands of pieces a day - so our team has developed a niche expertise around automating the process. Tracking packages is important to us, sometimes in unexpected ways.
Why are tracking numbers important?
From an accounting perspective, we aren’t allowed to recognize revenue until a package has been delivered to the customer - often several days after we have shipped it. A difference of four days may not seem like a big deal, but it’s important for us (and the government!) to paint an accurate financial picture. This is true, incidentally, for anything you order online: although your credit card is charged immediately, the books aren’t balanced until the item arrives at your doorstep.
We send various emails around a package's shipment status: a survey after your dress has arrived, or a friendly reminder to return an overdue dress.
We try to be smart about scheduling when we ship a dress. Knowing exactly how long it will take to arrive back to our warehouse, and its current transit status, is important for maintaining inventory.
And underneath all of this is a goal to decrease our costs: for example, shipping via a truck rather than airplane.
How to track UPS packages with cURL
If you try to search Google for how to use the UPS API you don’t get much more than a link to the UPS. There’s a cottage industry around understanding and wrapping shipping APIs. I think most developers don’t bother to try because they seem intimidating and arcane.
In practice, we’ve found it’s really not so intimidating (though it is a bit arcane). Here’s the minimum you need to use `curl` and start fetching tracking information directly from the UPS!
Create a UPS account
This is by far the least intuitive step of the process. You have to both create the UPS account, and then fill out another online form (instructions here) to request API access. I had initially thought there would be a delay, but in fact they give you API credentials immediately after registering.
Take note of your Access Key, which they also email you after requesting API access.
(If you’re already doing UPS shipping, you probably already have a UPS account and just need the API Access Key.)
Download the documentation
Once you’ve logged in, you can access the documentation for all UPS APIs. Their APIs are all XML-based. You can choose between a SOAP interface or a simplified XML. I'm partial to their basic XML interface. Oddly, if you know the direct link you can download the documentation. Specifically, we will be looking at the tracking API.
The documentation contains sample SOAP and XML requests, WSDL files, XML schemas, and detailed documentation on all of the input and output fields. Their API is surprisingly robust and well-documented.
Create the request XML
The UPS API has a strange format: you literally concatenate two XML files, and then POST the result to a URL.
The first part has your credentials, and the second is the actual tracking request.
<?xml version="1.0" ?> <AccessRequest xml:lang='en-US'> <AccessLicenseNumber>ACCESS_LICENSE_NUMBER</AccessLicenseNumber> <UserId>username</UserId> <Password>password</Password> </AccessRequest> <?xml version="1.0" ?> <TrackRequest> <Request> <RequestAction>Track</RequestAction> </Request> <TrackingNumber>1Z0020421361795425</TrackingNumber> </TrackRequest>
curl away!
url -X POST -d @ups.xml https://wwwcie.ups.com/ups.app/xml/Track
The output XML has all of the information you would expect to find on the website: tracking status, package weight, shipping method, etc. The document is well-formed and easy to parse.
For Python programmers…
I implemented package tracking, along with other API features, in a most-excellent library called ClassicUPS. Feel free to make a pull request!
Conclusion
As customers, we refresh the UPS website to see when our package will be delivered. But that status information is used by merchants, auditors, accountants, marketers, and lawyers to provide accountability for transactions between buyers and sellers. There is a lot of opportunity for businesses to use tracking status in clever ways, and from an engineering perspective, it is surprisingly easy to fetch and work with this information directly from the UPS.
Happy hacking!