How to use the Yahoo Maps API

Yahoo has released their competitor to the Google Maps API. I'm not familiar with the latter, but the main difference appears to be that Yahoo's maps can't be embedded in your own pages: the closest you can get is with the much-reviled frames. However, the popup windows shown on the map have links so you can direct people to one or more web pages at your site. You can see sample maps here.

[NOTE: This page refers to the legacy Yahoo Maps API. While it still functions, using the new AJAX version is recommended.]

This mini-tutorial outlines the basic steps to get something up and running:

1. Find an RSS 2.0 file you're familiar with. If you don't have such a file, find one from some other site or use this one:



2. To avoid clutter, remove all the items except one. The file above only has one item.

3. In the rss element, add the following namespaces (the one above already has this):

xmlns:ymaps="http://api.maps.yahoo.com/Maps/V1/AnnotatedMaps.xsd"
xmlns:geo="http://www.w3.org/2003/01/geo/wgs84_pos#"

4. In the item element, add the following, changing this to be a real address and zip:

<ymaps:Address>PUT YOUR ADDRESS HERE</ymaps:Address>
<ymaps:Zip>PUT YOUR ZIP HERE</ymaps:Zip>

The XML file above already has those elements.

5. Get a Yahoo application ID at this page.

6. Store the RSS 2.0 file on a server somewhere, and load the following URL, replacing the bracketed items with your application ID and the URL to the RSS 2.0 file. The URL has been split into two lines:

http://api.maps.yahoo.com/Maps/V1/annotatedMaps? appid=[YOUR_APP_ID]&xmlsrc=[URL _TO_XML]

7. If all goes well that should display a map with the address you specified shown by an icon.

8. If you want to use a latitude/longitude instead of a street address, add this to the item element instead of the Address and Zip elements:

<geo:lat>37.8</geo:lat>
<geo:long>-122.4</geo:long>

9. The documentation describes the various options available:

* Points can be indicated using either a street address or lat/long
* The regular, hover, and clicked-on icons can be set for each item
* A legend can be created, for instance showing gas stations and restaurants. The gas stations would have a different set of icons from the restaurants.
* The text that's displayed when the icon is clicked on is set using the description element.
* Links can be added to the popup window.
* The link that's accessed when the user clicks the name in the list is set using the Link element.

There appear to be at least two current issues:

* If you want to set the magnification level, you also need to set the center coordinates in lat/long format; see the description above.
* Special characters like & might not be handled correctly; if a name might include one of those characters put it in a CDATA section.