Hack 91. Plot Multiple Points on Your Own Map

Use the Yahoo! Maps Web Service to plot several locations on a map at once.

An online mapping service such as Yahoo! Maps (http://maps.yahoo.com)is a vast improvement over the multifold paper maps that are stashed in your glove compartment. Enter your starting address and an end address at Yahoo! Maps, and you'll get a detailed map, along with directions that include every turn you need to make to reach your destination. Finding a single address on a map is easy, but plotting several unique points on an interactive map used to be a task that only map service providers could accomplish.

Yahoo! has opened this ability to anyone with a bit of scripting knowledge, and you can plot dozens of points on a map instantly with the Yahoo! Maps Web Service (http://developer.yahoo.net/maps). The key to plotting several points is building a Yahoo! Maps Annotation file: an XML file with information about the points you want to plot on your map. If you're familiar with the syndication format RSS, you're most of the way there. The Yahoo! Maps Annotation file uses the RSS 2.0 format with some proprietary extensions that describe locations. This hack shows how to put together an RSS file that Yahoo! Maps will understand, and it explains how that file plots points on a Yahoo! Map.

5.16.1. Assembling Your Locations

Imagine it's Saturday morning, and you've decided to spend the day going to garage sales in your area. You open the paper, find a list of garage sales in the classified ads, and want to choose the most efficient route for visiting the sales. Unless the paper provides a list of sales on a map, it's difficult to visualize where each address is located. This is where the Yahoo! Maps Web Service can help.

To start building your map, you need to have your location data in a digital format. A spreadsheet works well for data entry, so open Excel and add the addresses you want to plot on a map. This hack expects the data in five columns, in this order: address, city, state, Zip Code, and notes about the address. Now you can copy the garage sale addresses from the paper and include notes about what you're most interested in at that particular sale. Figure 5-35 shows a sample spreadsheet in Excel.

Figure 5-35. Excel spreadsheet with garage sale addresses

Once you've added all the addresses you want to plot, save the file in the plain text comma-separated value (CSV) format and call the file garage_sales.csv. Now that your location data is in a digital format, you can easily convert the CSV file into the Yahoo! Maps Annotation format with some Perl.

5.16.2. The Code

This script accepts a filename for a CSV file and uses the data in the file to create a geo-aware RSS 2.0 file. You won't need any extra modules, so you can simply save the following code to a file called csv_to_geoRSS.pl:

	#!/usr/bin/perl
	# csv_to_geoRSS.pl
	# Converts a CSV file with addresses to geo-aware RSS
	# Usage: csv_to_geoRSS.pl <CSV File>

	use strict;

	# Open the incoming file
	open(CSV, "<@ARGV" ) or die "Can't open @ARGV : $!";

	# Change the .csv extension to .xml for RSS file
	my $RSSfile = $ARGV[0];
	$RSSfile =~ s!csv$!xml!;

	# Open the RSS file for writing
	open(RSS, ">$RSSfile") or die "Can't open file: $!";

	print RSS<<"HEADER_END";
	<?xml version="1.0"?>
	<rss version="2.0" xmlns:geo="http://www.w3.org/2003/01/geo/wgs84_pos#"
			xmlns:ymaps="http://api.maps.yahoo.com/Maps/V1/AnnotatedMaps.xsd"> 
	<channel> 
	HEADER_END

	# Loop through the CSV file, adding items
	while(<CSV>) {
		chomp;
		my($address, $city, $state, $zip, $notes) = split(/,/, $_);

	print RSS<<"ITEM_END";
	  <item>
		<title>$address</title>
		<link />
		<description>$notes</description>
		<ymaps:Address>$address</ymaps:Address>
		<ymaps:CityState>$city, $state</ymaps:CityState>
		<ymaps:Zip>$zip</ymaps:Zip>
		<ymaps:Country>us</ymaps:Country>
	</item>
ITEM_END
}
	# Finish the RSS
	print RSS "</channel>\n";
	print RSS "</rss>";

	# Close the files
	close CSV;
	close RSS;

As you look through the script, you can see that the RSS format contains the standard <title>, <link>, and <description> tags. It also has some Yahoo!-specific extension tags including <ymaps:Address>, <ymaps:CityState>, <ymaps:Zip>, and <ymaps:Country>. Because the garage sales in this example don't have titles or links, the address is used as a title and the link tags are blank in the final RSS file. You could easily add more columns to the spreadsheet to hold titles or links.

Also keep in mind that if your source spreadsheet file data contains commas (in the address or note columns, for example), you may need to adjust the script to accommodate. Try saving the spreadsheet as a tab-delimited file and changing the line in the code that separates data by commas so that it instead separates data by tabs:

my($address, $city, $state, $zip, $notes) = split(/\t/, $_);

This measure should help ensure your data lines up properly in the RSS file.

5.16.3. Running the Hack

To create the RSS file, pass the name of your CSV file to the script, like so:

perl csv_to_geoRSS.pl garage_sales.csv

The script will create a file called garage_sales.xml that contains the properly formatted RSS for plotting points on a Yahoo! Map. Upload the RSS file to a publicly available web server and note the URL. The RSS file needs to be available online so Yahoo! Maps can use the data.

5.16.4. Building the Map

Once your RSS file is in place, building your map is simply a matter of constructing the proper Yahoo! Maps URL. You'll need a Yahoo! Application ID, which you can pick up at http://api.search.yahoo.com/webservices/register_application. With your Application ID and RSS URL, link to your custom map like this:

	http://api.maps.yahoo.com/Maps/V1/AnnotatedMaps?appid=insert App 

	ID&xmlsrc=insert RSS URL

For this example, the URL would be:

	http://api.maps.yahoo.com/Maps/V1/AnnotatedMaps?appid=insert App 

	ID&xmlsrc=http://example.com/garage_sales.xml

When you browse to the URL, Yahoo! fetches the RSS file and plots the addresses on a map, like the one shown in Figure 5-36.

Figure 5-36. Yahoo! map with plotted addresses

Hover over the points on the map to see details, including notes about each address. You can also click the Printable Version link at the top of the page to see a numbered map of the points and a list of the addresses below the mapperfect for taking with you to those garage sales. Beyond personal use, you now have a unique map you can share with others via email or on the Web.

5.16.5. Hacking the Hack

This hack gives the most basic example of plotting several points on a map, and there are more ways to use the Yahoo! Maps service. If you have longitude and latitude data instead of addresses, you can use geoRSS 2.0

(http://brainoff.com/worldkit/doc/rss.php) to plot points. geoRSS is a standard RSS file with extra <geo:lat> and <geo:long> tags or specially formatted text in the <description> tag to describe coordinates.

If you want to change the look and feel of your map, you can add special tags that provide alternate icons for plotted points. You can also design your own pop up to describe items and give the pop-up URL in a <ymaps:ItemUrl> tag. You can read the complete Yahoo! Maps API documentation at http://developer.yahoo.net/maps.