
Learn the fundamentals of the Yahoo! Maps AJAX API and get started creating your own maps. This page contains these sections:
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.
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 8 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.
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-V4S8BzM_JXye1_eSxQ22Lw--"; you cannot use this Application ID and must request one here.
<html> <head> <script type="text/javascript" src="http://api.maps.yahoo.com/ajaxymap?v=3.8&appid=YD-V4S8BzM_JXye1_eSxQ22Lw--"> </script> </head> <body> ... ... </body> </html>
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.
<html>
<head>
<script type="text/javascript"
src="http://api.maps.yahoo.com/ajaxymap?v=3.8&appid=YD-V4S8BzM_JXye1_eSxQ22Lw--">
</script>
<style type="text/css">
#map{
height: 75%;
width: 100%;
}
</style>
</head>
<body>
<div id="map"></div>
...
</body>
</html>
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.
<html>
<head>
<script type="text/javascript"
src="http://api.maps.yahoo.com/ajaxymap?v=3.8&appid=YD-V4S8BzM_JXye1_eSxQ22Lw--"></script>
<style type="text/css">
#map{
height: 75%;
width: 100%;
}
</style>
</head>
<body>
<div id="map"></div>
<script type="text/javascript">
// Create a map object
var map = new YMap(document.getElementById('map'));
// Add map type control
map.addTypeControl();
// Set map type to either of: YAHOO_MAP_SAT, YAHOO_MAP_HYB, YAHOO_MAP_REG
map.setMapType(YAHOO_MAP_REG);
// Display the map centered on a geocoded location
map.drawZoomAndCenter("San Francisco", 3);
</script>
</body>
</html>
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.
<html>
<head>
<script type="text/javascript"
src="http://api.maps.yahoo.com/ajaxymap?v=3.8&appid=YD-V4S8BzM_JXye1_eSxQ22Lw--"></script>
<style type="text/css">
#map{
height: 75%;
width: 100%;
}
</style>
</head>
<body>
<div id="map"></div>
<script type="text/javascript">
// Create a map object
var map = new YMap(document.getElementById('map'));
// Add map type control
map.addTypeControl();
// Add map zoom (long) control
map.addZoomLong();
// Add the Pan Control
map.addPanControl();
// Set map type to either of: YAHOO_MAP_SAT, YAHOO_MAP_HYB, YAHOO_MAP_REG
map.setMapType(YAHOO_MAP_SAT);
// Display the map centered on a geocoded location
map.drawZoomAndCenter("New York, NY", 4);
</script>
</body>
</html>
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.
<html>
<head>
<script type="text/javascript"
src="http://api.maps.yahoo.com/ajaxymap?v=3.8&appid=YD-V4S8BzM_JXye1_eSxQ22Lw--"></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);
}
}
window.onload = startMap;
</script>
</body>
</html>
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-V4S8BzM_JXye1_eSxQ22Lw--"></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("\nLatitude:" + _c.Lat + "\nLongitude:" + _c.Lon);
var currentGeoPoint = new YGeoPoint( _c.Lat, _c.Lon );
map.addMarker(currentGeoPoint);
}
}
window.onload = startMap;
</script>
</body>
</html>
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-V4S8BzM_JXye1_eSxQ22Lw--"></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("\nLatitude:" + _c.Lat + "\nLongitude:" + _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>
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-V4S8BzM_JXye1_eSxQ22Lw--"></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("\nLatitude:" + geoPoint.Lat + "\nLongitude:" + 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>
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-V4S8BzM_JXye1_eSxQ22Lw--"></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("\nLatitude:" + geoPoint.Lat + "\nLongitude:" + 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 = 'http://us.i1.yimg.com/us.yimg.com/i/us/map/gr/mt_ic_c.gif';
myImage.size = new YSize(20,20);
myImage.offsetSmartWindow = new YCoordPoint(0,0);
return myImage;
}
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>
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.
<html>
<head>
<script type="text/javascript"
src="http://api.maps.yahoo.com/ajaxymap?v=3.8&appid=YD-V4S8BzM_JXye1_eSxQ22Lw--"></script>
<style type="text/css">
#map{
height: 75%;
width: 100%;
}
</style>
</head>
<body>
<div id="map"></div>
<script type="text/javascript">
function StartYMap() {
var map = new YMap(document.getElementById('map'));
var cPT = new YGeoPoint(41.85,-87.65);
map.addZoomLong();
map.addTypeControl();
map.disableKeyControls();
map.drawZoomAndCenter(cPT,5);
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>
Overlay RSS output from Yahoo! Pipes on a Map
<html>
<head>
<script type="text/javascript"
src="http://api.maps.yahoo.com/ajaxymap?v=3.8&appid=YD-V4S8BzM_JXye1_eSxQ22Lw--"></script>
<style type="text/css">
#map{
height: 75%;
width: 100%;
}
</style>
</head>
<body>
<div id="map"></div>
<script type="text/javascript">
/*
Pipe being used is finding events from Upcoming that are are in the San Francisco Bay Area.
You can view the pipe here: http://pipes.yahoo.com/pipes/pipe.info?_id=BlagERoO3BGgl_e3X0sBXw
*/
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>
Overlay JSON output from Yahoo! Pipes on a Map
Search and overlay local business results within given radius of YGeoPoint
Creating your own data/map mashup can now be accomplished by simply passing valid GeoRSS format resource. More information on supported GeoRSS format.
Easily place your custom objects on the map.
Easily place your custom objects on the map.
Overlay custom line on the map using YPolyline class, this example also illustrates flexible positioning of pan and zoom control using YCoordPoint
Export your map in GeoRSS format
More complex example making use of built in features such as local search, traffic and polyline overlays
Define polyline in GeoRSS and overlay result on the map
Given distance from center of the map return best fit zoom level
Position pan / zoom controls anywhere within map container
Use the new built in features to automatically change a marker image
Using the new YMapTypeControl, the ability to position to orientation and location of map types is available.
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:
For detailed descriptions of the classes and methods in the API, check out v3.8 Reference Manual
The Yahoo! AJAX Maps API is limited to 50,000 queries per IP per day. See information on rate limiting.
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.
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.
Copyright © 2008 Yahoo! Inc. All rights reserved.
Privacy Policy - Terms of Service - Copyright Policy - Job Openings