Yahoo! Maps Ajax Web Services

My Apps Sign in

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:

Introduction and Prerequisites
Examples

Display a Yahoo! Map
Add controls to your Yahoo! Map
Add a logger to a Yahoo! Map
Place a marker on a Yahoo! Map
Draw Polylines on a Yahoo! Map
Place Smart Markers on a Yahoo! Map
Add multiple custom markers on Yahoo! Map
Traffic information overlay
Yahoo! Pipes RSS output information overlay
Yahoo! Pipes JSON output information overlay
Local search results overlay
Overlay GeoRSS XML data
Overlay custom objects at YGeoPoint location
Overlay custom objects at YCoordPoint location
Overlay polyline on Yahoo! Map
Export Yahoo! Map in GeoRSS format
GeoRSS overlay with polyline
Get zoom level given radius from center
Custom position of controls
Change Marker Images Dynamically
Use YMapTypeControl to position map types

Other Features of the Yahoo! Maps AJAX API
Rate Limit
Terms of Service
Support & Community

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.

Yahoo! Maps Cheatsheets

YMap

YEvent, YGeoRSS, YMarker

Remaining, Supporting Classes

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.

function startMap(){
		// Add the ability to change between Sat, Hybrid, and Regular Maps
		map.addTypeControl();
		// Add the zoom control. Long specifies a Slider versus a "+" and "-" zoom control
		map.addZoomLong();
		// Add the Pan control to have North, South, East and West directional control
		map.addPanControl();
		// Specifying the Map starting location and zoom level
		map.drawZoomAndCenter("San Francisco", 3);
		// Add an event to report to our Logger
		YEvent.Capture(map, EventsList.MouseClick, reportPosition);

function reportPosition(_e, _c){
			// It is optional to specify the location of the Logger.
			// Do so by sending a YCoordPoint to the initPos function.
			var mapCoordCenter = map.convertLatLonXY(map.getCenterLatLon());

YLog.initPos(mapCoordCenter); //call initPos to set the starting location

// Printing to the Logger
			YLog.print("You Made a MouseClick!");
			YLog.print("Latitude:" + _c.Lat);
			YLog.print("Longitude:" + _c.Lon);
		}
	}

window.onload = startMap;
</script>
</body>
</html>

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.

<html>
<head>
<script type="text/javascript"
src="http://api.maps.yahoo.com/ajaxymap?v=3.8&appid=YD-eQRpTl0_JX2E95l_xAFs5UwZUlNQhhn7lj1H"></script>
<style type="text/css">
#map{
height: 75%;
width: 100%;
}
</style>
</head>
<body>
<div id="map"></div>
<script type="text/javascript">
	// Create a Map that will be placed in the "map" div.
	var map = new YMap(document.getElementById('map'));
	function startMap(){
		// Add the ability to change between Sat, Hybrid, and Regular Maps
		map.addTypeControl();
		// Add the zoom control. Long specifies a Slider versus a "+" and "-" zoom control
		map.addZoomLong();
		// Add the Pan control to have North, South, East and West directional control
		map.addPanControl();
		// Specifying the Map starting location and zoom level
		map.drawZoomAndCenter("San Francisco", 3);
		// Add an event to report to our Logger
		YEvent.Capture(map, EventsList.MouseClick, reportPosition);
		function reportPosition(_e, _c){
			// It is optional to specify the location of the Logger.
			// Do so by sending a YCoordPoint to the initPos function.
			var mapCoordCenter = map.convertLatLonXY(map.getCenterLatLon());
			YLog.initPos(mapCoordCenter); //call initPos to set the starting location
			// Printing to the Logger
			YLog.print("You Made a MouseClick!");
			YLog.print("Latitude:" + _c.Lat);
			YLog.print("Longitude:" + _c.Lon);

YLog.print("Adding marker at....");
			YLog.print("
Latitude:" + _c.Lat + "
Longitude:" + _c.Lon);
			var currentGeoPoint = new YGeoPoint( _c.Lat, _c.Lon );
			map.addMarker(currentGeoPoint);
		}
	}
window.onload = startMap;
</script>
</body>
</html>

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.

<html>
<head>
<script type="text/javascript"
src="http://api.maps.yahoo.com/ajaxymap?v=3.8&appid=YD-eQRpTl0_JX2E95l_xAFs5UwZUlNQhhn7lj1H"></script>
<style type="text/css">
#map{
	height: 75%;
	width: 100%;
}
</style>
</head>
<body>
<div id="map"></div>
<script type="text/javascript">
	// Create a Map that will be placed in the "map" div.
	var map = new YMap(document.getElementById('map'));
	// Create an array to contain the points of our polyline
	polylinePoints = [];
	function startMap(){
		// Add the ability to change between Sat, Hybrid, and Regular Maps
		map.addTypeControl();
		// Add the zoom control. Long specifies a Slider versus a "+" and "-" zoom control
		map.addZoomLong();
		// Add the Pan control to have North, South, East and West directional control
		map.addPanControl();
		// Specifying the Map starting location and zoom level
		map.drawZoomAndCenter("San Francisco", 3);
		// Add an event to report to our Logger
		YEvent.Capture(map, EventsList.MouseClick, myCallback);

function myCallback(_e, _c){
			// It is optional to specify the location of the Logger.
			// Do so by sending a YCoordPoint to the initPos function.
			var mapCoordCenter = map.convertLatLonXY(map.getCenterLatLon());

YLog.initPos(mapCoordCenter); //call initPos to set the starting location

// Printing to the Logger
			YLog.print("You Made a MouseClick!");
			YLog.print("Latitude:" + _c.Lat);
			YLog.print("Longitude:" + _c.Lon);

// Printing to the Logger
			YLog.print("Adding marker at....");
			YLog.print("
Latitude:" + _c.Lat + "
Longitude:" + _c.Lon);
			var currentGeoPoint = new YGeoPoint( _c.Lat, _c.Lon );
			map.addMarker(currentGeoPoint)

// Draw our Polylines
			polylinePoints.push(currentGeoPoint);
			if (canDisplayPolyLines){
				map.addOverlay(new YPolyline(polylinePoints, 'black',7,0.7));
				YLog.print("Polyline added lines");
			}
		}
		this.canDisplayPolyLines = function (){
			return (polylinePoints.length > 1);
		}
	}

window.onload = startMap;
</script>
</body>
</html>

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.

<html>
<head>
<script type="text/javascript"
src="http://api.maps.yahoo.com/ajaxymap?v=3.8&appid=YD-eQRpTl0_JX2E95l_xAFs5UwZUlNQhhn7lj1H"></script>
<style type="text/css">
#map{
	height: 75%;
	width: 100%;
}
</style>
</head>
<body>
<div id="map"></div>
<script type="text/javascript">
	// Create a Map that will be placed in the "map" div.
	var map = new YMap(document.getElementById('map'));
	// Create an array to contain the points of our polyline
	polylinePoints = [];
	function startMap(){
		// Add the ability to change between Sat, Hybrid, and Regular Maps
		map.addTypeControl();
		// Add the zoom control. Long specifies a Slider versus a "+" and "-" zoom control
		map.addZoomLong();
		// Add the Pan control to have North, South, East and West directional control
		map.addPanControl();
		// Specifying the Map starting location and zoom level
		map.drawZoomAndCenter("San Francisco", 3);
		// Add an event to report to our Logger
		YEvent.Capture(map, EventsList.MouseClick, myCallback);

function myCallback(_e, _c){
			/*
			   It is optional to specify the location of the Logger.
			   Do so by sending a YCoordPoint to the initPos function.
			 */
			var mapCoordCenter = map.convertLatLonXY(map.getCenterLatLon());
			YLog.initPos(mapCoordCenter); //call initPos to set the starting location
			currentGeoPoint = new YGeoPoint( _c.Lat, _c.Lon);
			placeMarker(currentGeoPoint);
			displayPolyLines(currentGeoPoint);
		}

function placeMarker(geoPoint){
			// Printing to the Logger
			YLog.print("Adding marker at....");
			YLog.print("
Latitude:" + geoPoint.Lat + "
Longitude:" + geoPoint.Lon);
			var newMarker= new YMarker(geoPoint);
			newMarker.addAutoExpand("Add a Label to a Marker for this Effect");
			var markerMarkup = "<b>You can add markup this</b>";
			    markerMarkup += "<i> easy</i>";
			YEvent.Capture(newMarker, EventsList.MouseClick,
				function(){
					newMarker.openSmartWindow(markerMarkup);
				});
			map.addOverlay(newMarker);
		}

function displayPolyLines(g_point){
			polylinePoints.push(g_point);
			if (canDisplayPolyLines){
				map.addOverlay(new YPolyline(polylinePoints, 'black',7,0.7));
				YLog.print("Polyline added lines");
			}
		}

this.canDisplayPolyLines = function() {
			// Check to make sure we have at least 2 points to connect
			return (polylinePoints.length > 1);
		}
	}

window.onload = startMap;
</script>
</body>
</html>

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.

<html>
<head>
<script type="text/javascript"
src="http://api.maps.yahoo.com/ajaxymap?v=3.8&appid=YD-eQRpTl0_JX2E95l_xAFs5UwZUlNQhhn7lj1H"></script>
<style type="text/css">
#map{
	height: 75%;
	width: 100%;
}
</style>
</head>
<body>
<div id="map"></div>
<script type="text/javascript">
	// Create a Map that will be placed in the "map" div.
	var map = new YMap(document.getElementById('map'));
	// Create an array to contain the points of our polyline
	polylinePoints = [];
	function startMap(){
		// Add the ability to change between Sat, Hybrid, and Regular Maps
		map.addTypeControl();
		// Add the zoom control. Long specifies a Slider versus a "+" and "-" zoom control
		map.addZoomLong();
		// Add the Pan control to have North, South, East and West directional control
		map.addPanControl();
		// Specifying the Map starting location and zoom level
		map.drawZoomAndCenter("San Francisco", 3);
		// Add an event to report to our Logger
		YEvent.Capture(map, EventsList.MouseClick, myCallback);

function placeMarker(geoPoint){
			// Printing to the Logger
			YLog.print("Adding marker at....");
			YLog.print("
Latitude:" + geoPoint.Lat + "
Longitude:" + geoPoint.Lon);

var newMarker= new YMarker(geoPoint, createCustomMarkerImage());
			newMarker.addAutoExpand("Add a Label to a Marker for this Effect");
			var markerMarkup = "<b>You can add markup this</b>";
			    markerMarkup += "<i> easy</i>";

YEvent.Capture(newMarker, EventsList.MouseClick,
				function(){
					newMarker.openSmartWindow(markerMarkup);
				});
			map.addOverlay(newMarker);
		}
		function createCustomMarkerImage(){
		 	var myImage = new YImage();
		  	myImage.src = 'https://s.yimg.com/zz/combo?a/i/us/map/gr/mt_ic_c.gif';
		 	myImage.size = new YSize(20,20);
		  	myImage.offsetSmartWindow = new YCoordPoint(0,0);
			return myImage;
		}

this.canDisplayPolyLines = function() {
			// Check to make sure we have at least 2 points to connect
			return (polylinePoints.length > 1);
		}
	}

window.onload = startMap;
</script>
</body>
</html>

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.

var setupMarker = function(p,d) {
			var m = new YMarker(p);
			m.addAutoExpand(d);
			return m;
		};

// process returned traffic e object
		var trafficF = function(e) {
			var _p = [];
			if (e.Data) {
			for (var a in e.Data.ITEMS) {
				var l = e.Data.ITEMS[a];
				// YLog.print(l);
				if (l.TITLE) {
				var p = new YGeoPoint(l.LATITUDE,l.LONGITUDE);
				_p.push(p);
				var m = setupMarker(p,l.TITLE);
				map.addOverlay(m);
				}
			}
			}
			//args: array of points, color, thickness, alpha
			var pl = new YPolyline(_p,'blue',4,0.5);
			map.addOverlay(pl);

};

//args: point, radius
		map.searchTraffic(cPT,2);

// listen for completion of traffic info search
		YEvent.Capture(map,EventsList.onEndTrafficSearch,trafficF);

}
	window.onload = StartYMap
</script>
</body>
</html>

Run the example above

Yahoo! Pipes RSS output information overlay

Overlay RSS output from Yahoo! Pipes on a Map

var StartYMap = function() {
	// Initialize the Map
	var ymap = new YMap('map');
	var start = new YGeoPoint(37.40630098979412 , -122.00926780700684);

// Draw the Map
	ymap.drawZoomAndCenter(start,10);

// Add the Map Controls
	ymap.addZoomShort();
	ymap.addTypeControl();

// Take a Yahoo! Pipe containing GeoRSS and Overlay the RSS output directly on a Yahoo! Map
	var pRSS = 'http://pipes.yahoo.com/pipes/pipe.run?_id=BlagERoO3BGgl_e3X0sBXw&_render=rss';
	ymap.addOverlay(new YGeoRSS(pRSS));

// optionally capture end of GeoRSS overlay
	var GeoRSSdone = function(e) {
		// Use YLog to print out the Result GeoRSS object
		YLog.print(e);
		if (e.success) {
			// success
			YLog.print(e.Data);
		}
		else {
			// no data
		}
	};

// Tell the map to call "GeoRSSdone" after Pipes sends back the RSS data
	YEvent.Capture(ymap,EventsList.onEndGeoRSS, GeoRSSdone);
};

// Call StartYMap when the page loads
window.onload = StartYMap;
</script>
</body>
</html>

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?

Create a Project