Hack 86. Track a Package Across the U.S.

Use free data sources to map your package's progress across the U.S.

Being able to see where a package is on its way to your door was developed as a business process-management tool. But it has turned out to be really popular with customers, too. What if you could take the next step, not only seeing a list of towns your new cell phone is visiting, but seeing them on a map! This hack presents one way of doing this.

7.10.1. Preparation

If you didn't do [Hack #66], take a quick look at it, because Openmap will be used to map our package shipment stops. In essence, you need to install a Version 1.4 or later Java Development Kit and Openmap 4.6. Make sure to copy the file openmap.properties from the program's installation directory into your home directory. After Java and Openmap are set up, you need to make a small modification to the openmap.properties file. Open openmap.properties in a text editor. Search for openmap.layers=. The second occurrence should look something like this:

openmap.layers=date dtlayer distlayer quake daynight cities test graticule demo shapePolitical

We will be creating a new layer that we want to show up on the map, so add the word "shipment" at the front of the list, which should give you this:

openmap.layers=shipment date dtlayer distlayer quake daynight cities test graticule demo shapePolitical

7.10.2. Getting Location Information

The first thing we have to do, obviously, is find out where the package has been. There are a variety of ways to do this, depending on the shipping company. Most, such as UPS and FedEx, have APIs for accessing the information you can get from their web site. Unfortunately, these are more difficult to get going with than, for example, the Amazon, eBay, or Google API. Working with them quickly transforms your project from a hack into a full-scale software development effort.

Instead of making use of the programming APIs of the major shippers, we'll use a much older hacking technique: copy and paste. Look up your package's tracking information in the usual way. Then create a text file listing the city and state of each location in chronological order, and save it in a file named places.txt. Your file should look something like this:

Seattle, WA Austin, Texas Chicago, Illinois Boston, Massachusetts Medford, Massachusetts

Now we're ready to map these locations. To do this, we'll need to translate our list of place names into a list of geographic coordinates, which is a job we already tackled in [Hack #85], which leverages a U.S. Geological Survey database of places for this purpose.

7.10.3. The Code

PackageTracker.java is a Java program that can be run from the command line. It knows how to read the little place-name text file we created and use the GNISCoords class [Hack #85] for geocoding the entries. It can write the new information to disk, or simply to stdout, which can be piped into other applications on Unix-ish operating systems like Mac OS X, Linux, and Solaris. For our purposes, write it to disk so that our mapping program can find it.

The program is too long to print here in full, so we've made it available online at http://mappinghacks.com/code/PackageTracker.java.

7.10.4. Running the Hack

Compile the Java file like this.

$ javac org/rajsingh/maphacks/shipment/PackageTracker.java

If you did the GNIS hack in another place, move the file GNISCoords.class to the same directory as PackageTracker.class and PackageTracker.java.

Now you can run the program. You'll have to provide three items of information on the command line:

• The full path to the file containing the place names, which we called places.txt.
• The full path for the file in which you want the geocoded information saved.
• A value of yes to signal the program to modify Openmap's properties. If you're curious about the Openmap properties file, there's plenty of information about it at http://openmap.bbn.com/cgi-bin/faqw.py?req=show&file=faq06.004.htp.

$ java -cp . org.rajsingh.maphacks.shipment.PackageTracker yes

7.10.5. The Results

Remember that we started this hack wanting to put our package "on the map"? Well, we're finally there. Since we automatically added our data to Openmap's properties file, all we need to do is run the program. Your final result should look something like Figure 7-7.

Figure 7-7. The resting places of a random package, as it makes its way across the U.S.

See [Hack #66] to learn how to get state boundaries on your map as well.

Raj Singh