Yahoo! Maps Web Services - AJAX API Getting Started Guide

We are shutting down this service on September 13, 2011. We suggest using maps from our partner Nokia. Please visit developer.here.net for more information.

Learn the fundamentals of the Yahoo! Maps AJAX API and start creating your own maps. This page contains:

Download all of the cheatsheets and example code in the Yahoo Maps API Reference Bundle.

For detailed descriptions of the classes and methods in the API, check out v3.8 Reference Manual.

Introduction and Prerequisites

The Yahoo! AJAX Maps API lets developers add maps to their web sites using DHTML and JavaScript®. Maps are fully embeddable and scriptable using the JavaScript programming language. Yahoo! Maps AS-Flash API's built-in geocoder means that you can specify a physical address or latitude/longitude coordinates for your map's location, as you like.

In order to create and test applications using Yahoo! Maps AJAX API, you'll need to use a supported web browser: Firefox 2, Internet Explorer 6 or 7, Opera 9 or Safari 3. Newer versions of these browsers are also supported. You can code your JavaScript applications using your favorite text editor or IDE.

An application ID is required to use the Yahoo! Maps AJAX API. You can get an application ID here.

For best results, you should launch your web pages from a web server. However, it's possible to run applications directly from your hard drive by double-clicking on them. This can be done by lowering the security settings in the Internet Explorer browser or by setting the UniversalBrowserRead property in Firefox.

Displaying a Yahoo! Map

All the API classes and methods necessary to interact with Yahoo! Maps are available to your application when you include Yahoo! Maps AJAX API library in your web page. This example uses the demonstration application ID "YD-eQRpTl0_JX2E95l_xAFs5UwZUlNQhhn7lj1H"; you cannot use this Application ID and must request one here.

You need at least one div container in which to place the map. Here, it's called "map". By default, the map will expand to fit the size of the div container. You should provide a height and width for the div container or else the map may not size as expected.

Now you're ready to display a map. You can use latitude and longitude coordinates to specify map locations, or you can use the built-in geocoding feature. To plot latitude and longitude coordinates, create a lat/lon object, create a Map object, and then instantiate the Map object at the lat/lon location using the drawZoomAndCenter method.

Run the example above

Adding controls to your Yahoo! Map

There are various controls you can place on your new Yahoo! Map. There is the Pan control, Zoom (long and short), Zoom Scale (on by default), and Map Types. All of these controls can be added by calling methods built into your map variable of type YMap.

Run the example above

Adding a Logger to your Yahoo! Map

The Yahoo! Maps API contains a utility variable called YLog. Utilizing YLog can be very helpful in debugging and viewing data while your application is running. In this example we have refactored our previous code to a function called startMap() and calling it when the window loads. Then we added an event to our Yahoo! Map so that it alerts the logger with its position when a click has occurred on the map.

Run the example above

Placing a Marker on your Yahoo! Map

Placing a simple marker on a map requires two steps. First, create a YGeoPoint object at the location you want to place the marker on the map. Place the marker on the map using the addMarker method. A SmartWindow marker would require the creation of a YMarker (in which you would set the custom markup) and use the addOverlay method of YMap. Markers can have simple labels, SmartWindows, or both. A SmartWindow is a small balloon that opens when the user clicks on the marker. All markers can be indexed so that you can use JavaScript to cycle through them like an array. You can use HTML for both the SmartWindow and simple labels.

Run the example above

Drawing Polylines on your Yahoo! Map

The Yahoo! Maps API the allows drawing of polylines. This can be done by overlaying a YPolyline variable that contains a listing of points that correspond to the line segments that make up a polyline. We first create an array that will store a set of YGeoPoints. We will add a new YGeoPoint to our array on every mouseclick over the map. Then we will pass this array to a YPolyline variable that will then be overlayed on a YMap using the addOverlay method. There is a helper function at the end which simply checks that we have at least two points before we try to draw a polyline.

Run the example above

Placing Smart Markers on your Yahoo! Map

The Yahoo! Maps API allows the creation of rich interactive markers that we call smart markers. This is allowed by creating an event that triggers on a mouse click which will display HTML markup by calling the openSmartWindow function found in YMarker. The addAutoExpand(new_label) function automatically adds a mouseover event that when triggered will expand to show the "new_label" for that marker.

Run the example above

Adding multiple custom markers on your Yahoo! Map

You can place multiple markers on the map at desired YGeoPoint location using your custom marker image. We did this by utilizing the YImage component of the Yahoo! Maps API. The function added is called createCustomMarkerImage() and simply generates the details of the custom marker image which is then used in YMarker constructor. This tells YMarker to use the specified image instead of the default simple marker image.

Run the example above

Displaying Traffic Information on your Yahoo! Map

The YMap variable type has the ability to search traffic or local data sources and allow developers to utilize that data for display or other purposes. The traffic search shown below should be used with an EventsList.onEndTrafficSearch event.

Run the example above

Yahoo! Pipes RSS output information overlay

Overlay RSS output from Yahoo! Pipes on a Map

Run example

Yahoo! Pipes JSON output information overlay

Overlay JSON output from Yahoo! Pipes on a Map

Run example/View source

Local search results overlay

Search and overlay local business results within given radius of YGeoPoint

Run example/View source

Overlaying GeoRSS XML data

Creating your own data/map mashup can now be accomplished by simply passing valid GeoRSS format resource. More information on supported GeoRSS format.

Run the example above

Overlaying custom object at YGeoPoint

Easily place your custom objects on the map.

Run example/View source

Overlaying custom object at YCoordPoint

Easily place your custom objects on the map.

Run example/View source

YPolyline

Overlay custom line on the map using YPolyline class, this example also illustrates flexible positioning of pan and zoom control using YCoordPoint

Run example/View source

GeoRSS export

Export your map in GeoRSS format

Run example/View source

More complex example making use of built in features such as local search, traffic and polyline overlays

Run example/View source

GeoRSS overlay with polyline

Define polyline in GeoRSS and overlay result on the map

Run example/View source

Get zoom level given radius from center

Given distance from center of the map return best fit zoom level

Run example/View source

Custom position of controls

Position pan / zoom controls anywhere within map container

Run example/View source

Changing Marker Images Dynamically

Use the new built in features to automatically change a marker image

Run example/View source

Using YMapTypeControl to position map types

Using the new YMapTypeControl, the ability to position to orientation and location of map types is available.

Run example/View source

Other Features of the Yahoo! Maps AJAX API

This Getting Started Guide only scratches the surface of what is possible using the Yahoo! Maps AJAX API. Here is but a small sampling of other things you can do:

  • Have your overlays and tools respond to user events such as rollovers and mouse clicks by using the removeMarker, removeZoomControl, and removePanControl methods.
  • Use setZoomLevel and resizeTo methods to quickly change the size and magnification of your map.
  • Enable or disable draggable maps using the disableDragMap and enableDragMap methods.
  • Use the timing parameter of panToLatLon and panToXY to slowly (or quickly) move to new map regions.

For detailed descriptions of the classes and methods in the API, check out v3.8 Reference Manual.

Rate Limit

The Yahoo! AJAX Maps API is limited to 50,000 queries per IP per day. See information on rate limiting.

Terms of Use

Use of the Yahoo! Maps APIs is governed by the Yahoo! Maps APIs Terms of Use and the Yahoo! Maps Terms of Use. These Terms of Use supplant the general Yahoo! Developer Network Terms of Use. See also the Usage Policy for more information about acceptable usage of these APIs or to request additional queries.

Support & Community

All Yahoo! Maps Web Services are discussed on the yws-maps mailing list.

The yws-maps-ajax mailing list is available for Ajax API specific questions.

Ready to get started?