Hack 25. Track Your UPS Packages

With Google Maps and a simple Greasemonkey user script, you can watch your UPS packages travel across the country.

Anyone who's received a package delivered by UPS, or any other large shipping company, probably has had the experience of wondering where the heck the package is right now, and when exactly it's going to arrive. By entering the package's tracking number into a form on the UPS web site, you can get back a list of the cities which the package has traveled through to date. Of course, this is enough information to allow us to visualize the package's progress on a map!

3.10.1. The Hack

As usual, the trick of mashing up Google Maps with information from another site, such as that from the UPS tracking form, involves a bit of contortion, to get around security restrictions in the browser. One solution to this problem (at least for Mozilla Firefox users) is to use a Greasemonkey user script to modify the contents of a web page to include a link to a map of the things on that page. The Greasemonkey approach [Hack #27] is exactly the one taken by Matthew King, when he decided he wanted to visualize the path traversed by his new laser printer, on its way from the warehouse to his hometown.

First, you'll need to be running Mozilla Firefox. You'll also want to install the latest version of the Greasemonkey extension from http://greasemonkey.mozdev.org/, if you haven't done this already; see "Add Google Maps to Any Web Site" [Hack #27] for more information on how this works. To install the UPS tracking user script, visit http://www.thrall.net/~mking/maps/upstrack.user.js in Firefox, and then select Tools images/U2192.jpg border=0> Install User Script from the menu bar. A confirmation window will pop up, in which you can simply click OK.

Now you're ready to track your UPS packages! Visit the UPS package tracking form at http://www.ups.com/content/us/en/index.jsx, enter a tracking number, click the checkbox to accept the terms and conditions of use, and then click the button marked Track. A summary page will load, with a "View package progress" link. Click this link as well. You should get a results page that looks something like Figure 3-16. This particular example shows the course of a box of O'Reilly's Mapping Hacks sent from the company's warehouse in Tennessee to our old house in San Francisco.

So far this looks just like the regular UPS package details page, with a list of cities, dates, and status messages. However, if you look closely, you'll see that the Greasemonkey script you installed earlier has added a special link to this page that reads simply "Map Progress." Go on, click it! A new window should open, showing a map of your package's progress across the country, as shown in Figure 3-17.

Figure 3-16. The UPS package tracking details page, augmented by Greasemonkey

Figure 3-17. The Google Maps representation of a package's travels

If you don't have a package of your own to track, you can always try out Matt King's example page at http://www.thrall.net/~mking/maps/ups_sample.html.

3.10.2. The Code

The Greasemonkey code for this hack is actually really simple and offers a good example of how to use Greasemonkey to pick elements from an existing page on the Web and use them to insert new elements into the same page. This first chunk of code from upstrack.user.js extracts all the locations from the UPS detailed results page:

	var lastLoc = null;
	var loc = null;
	var locations = new Array;
	var allDivs, thisDiv;
	allDivs =
	 document.evaluate("//div[@class='modulepad']", document, null,
	 XPathResult.UNORDERED_NODE_SNAPSHOT_TYPE, null);
	for (var i = 0; i < allDivs.snapshotLength; i++) {
	 thisDiv = allDivs.snapshotItem(i);
	 var html = thisDiv.innerHTML;
	 html = html.split(/[	

]+/).join(' ');
	 html = html.replace("
 ", '');
	 if (html.indexOf(', US') == -1)
	 continue;
	 loc = html;
	 if (loc == lastLoc)
	 continue;
	 locations[locations.length] = loc;
	 lastLoc = loc;
	}

The code starts by creating an empty array of locations and then passes an XPath to Firefox's document.evaluate( ) method to find all of the HTML div elements of the class modulepad, which apparently contain the location strings. The script then iterates over each div node, extracting the location string, cleaning it up a bit, and then pushing it on to the array of locations, checking each one to make sure that it's not redundant with the locations already stored.

The next bit of code in the script handles the insertion of the Map Progress link into the results page:

	if (locations.length > 1) {
	 locations.reverse();
	 var locStr = locations.join(" to ");
	 allDivs =
	 document.evaluate("//span[@class='brownbold']", document, null,
	 XPathResult.UNORDERED_NODE_SNAPSHOT_TYPE, null);
	 for (var i = 0; i < allDivs.snapshotLength; i++) {
	 thisDiv = allDivs.snapshotItem(i);
	 var html = thisDiv.innerHTML;
	 var estr = escape(locStr).replace(/ //g, '%2F');
	 html += '     '
	 + '<a href="http://www.thrall.net/~mking/maps/upstrack.cgi?
	 + v=0.4&trip= + estr +
	 " target="_blank">Map Progress</a>';
	 thisDiv.innerHTML = html;
	 }
	}

In this section, the code checks to see if any locations were found, and, if so, joins them with the string "to", yielding something like NASHVILLE TN to KANSAS CITY MO to SAN FRANCISCO CA in the locStr variable. The script then looks for div elements of the class brownbold, which presumably holds the "Package Progress:" text displayed on the page above the list of locations, and inserts a link to Matt King's http://www.thrall.net/~mking/maps/upstrack.cgi script into the div's innerHTML, passing a URL-escaped rendition of locStr as an HTTP GET parameter. This results in the Map Progress link that you can click to show the map in a new browser window. The server-side script geocodes each location and returns a Google Map with markers based on the UPS logo over each location, with colored polylines connecting themthus describing the path of your package.

3.10.3. Hacking the Hack

You'll note that this code also ensures that the location is within the United States, which means it won't work if the package's origin or destination is outside the States. If you live outside the U.S. (and are feeling adventurous), you might try removing or commenting that line out in your local copy of upstrack.user.js (buried somewhere in your Mozilla user directory) and then restarting Firefox to see if it does indeed work for you.