Developer Network Home - Help

Yahoo! Maps Web Services - Flex™ API Getting Started Guide

Version 3.5 - Beta Yahoo! Maps Flex API - Getting Started Guide

Learn the fundamentals of the Yahoo! Maps Flex API for use with the Macromedia® Flex framework. For detailed descriptions of the ActionScript® classes and methods in this version of the API, check out our online Flash APIs Reference Manual. We also have Previous Version 3 documentation and Previous Version 2 documentation.

Introduction and Prerequisites

Macromedia Flex is an application server and framework that addresses the requirements of enterprise programmers who want to develop rich Internet applications. Developers can use Flex to create data-driven applications that harness the power of both XML and Flash. The Yahoo! Maps Flex API is a component that lets developers add customizable Yahoo! Maps to their Flex applications. Now the Yahoo! Maps Flex API comes with built-in geocoding.

To create and test applications using Yahoo! Flash Maps using the Flex component, you'll need Macromedia Flex 1.5 with the internal JRun4 server or Tomcat server. If you don't already have a Flex development environment, you can download the Flex Server and Flex Builder IDE for a free trial. You will also need to accept the terms and download the Yahoo! Maps SWC file that contains the Flex components. An application ID is required to use the Flex API. You can get an application ID here.

For best results, you should launch your applications from a web server. However, it's possible to run applications directly from your hard drive by double-clicking on them. If you run them from your hard drive, you may see a warning from the Flash player that your application is trying to access data from a third-party server (Yahoo!). You can remove this warning by adjusting your Flash Player settings.

Displaying a Yahoo! Map using Flex and ActionScript

Once you have downloaded the Yahoo! Maps SWC file, create a new folder for your Flex application and place the SWC file in the root folder for your Flex application. Create a new MXML (Macromedia XML) file in the root folder and add the Yahoo! Maps namespace to the mx:Application tag so that the tag looks like this:

<mx:Application xmlns:mx="http://www.macromedia.com/2003/mxml"
  xmlns:yahoo="com.yahoo.maps.api.flex.*"
  xmlns:local="*"
  xmlns:="*" >

Then create a new Yahoo! Maps tag, yahoo:YahooMap, where you would like to place the map in your application.

<?xml version="1.0"?>
<mx:Application xmlns:mx="http://www.macromedia.com/2003/mxml"
  xmlns:yahoo="com.yahoo.maps.api.flex.*" xmlns:local="*"
  xmlns:="*" >
  <yahoo:YahooMap id="myMap" width="550" height="400"
   zoomLevel="3" latitude="37.77159"  longitude="-122.401714" />
</mx:Application>

Changing the Map View Type to Satellite or Hybrid View

You can now display satellite or hybrid map views in the API. To set the view type when the application loads, add the mapViewType property tag. Available options are MapViews.SATELLITE, MapViews.HYBRID, and MapViews.MAP.

<?xml version="1.0"?>
<mx:Application xmlns:mx="http://www.macromedia.com/2003/mxml"
  xmlns:yahoo="com.yahoo.maps.api.flex.*" xmlns:local="*" xmlns="*" >
  <yahoo:YahooMap id="myMap"
    mapViewType="{com.yahoo.maps.MapViews.HYBRID}" width="550" height="400"
    zoomLevel="6" latitude="37.77159" longitude="-122.401714" />
</mx:Application>

You can also change the Map View Type at runtime by calling the setMapViewType() method.

<?xml version="1.0"?>
<mx:Application xmlns:mx="http://www.macromedia.com/2003/mxml"
  xmlns:yahoo="com.yahoo.maps.api.flex.*" xmlns:local="*" xmlns="*" >
<mx:Script>
<![CDATA[
  import com.yahoo.maps.MapViews;
  function onInitialize(eventObject) {
    // This line sets the map type to Satellite;
    //for Hybrid use MapViews.HYBRID. For a regular map, use MapViews.MAP.
    myMap.setMapViewType(MapViews.SATELLITE);
  }
  ]]>
</mx:Script>
<yahoo:YahooMap id="myMap" width="550" height="400"
  zoomLevel="6" latitude="37.77159" longitude="-122.401714"
  initialize="onInitialize(event);" />
</mx:Application>

You can also add a SatelliteControlWidget to allow your users to switch between different Map View Types.

<?xml version="1.0"?>
<mx:Application xmlns:mx="http://www.macromedia.com/2003/mxml"
xmlns:yahoo="com.yahoo.maps.api.flex.*" xmlns:local="*" xmlns="*" >
<mx:Script>
<![CDATA[
  import com.yahoo.maps.widgets.SatelliteControlWidget;
  function onInitialize(eventObject) {
    myMap.addWidget(new SatelliteControlWidget());
  }
]]>
</mx:Script>
<yahoo:YahooMap id="myMap" width="550" height="400"
  zoomLevel="6" latitude="37.77159" longitude="-122.451714"
    initialize="onInitialize(event);" />
</mx:Application>

Placing a Marker on a Yahoo! Map using Flex and ActionScript

Placing a point on a map requires three pieces of information supplied to the Map.addMarkerByAddress() or Map.addMarkerByLatLon() methods. First, specify the type of marker object you want to place on the map; you pass the class name, not an instance of the class. Second, you need to supply a specific address or lat/lon on the map. Lastly you need to make an object that will be used to initialize the marker instance.

You can create POI (Point Of Interest) markers, waypoint markers, custom image markers, or custom SWF markers. A POI marker is a special type of marker that expands when you click on it to reveal more information about the location. A waypoint marker is a simple marker that is automatically indexed when placed on the map -- you can use ActionScript to cycle through waypoint markers like an array. The code below adds a single POI marker to our map. Note that the ActionScript code is placed in a CDATA section in the MXML file.

<?xml version="1.0"?>
<mx:Application xmlns:mx="http://www.macromedia.com/2003/mxml"
  xmlns:yahoo="com.yahoo.maps.api.flex.*"  xmlns:local="*"
  xmlns="*" >
<mx:Script>
<![CDATA[
  import com.yahoo.maps.markers.CustomPOIMarker;
  function onInitialize(eventObject) {
    var markerArgs = {
      index:"M", title:"Macromedia Inc.",
  	  description:"Macromedia Headquarters", markerColor:0xCCCCCC,
	  strokeColor:0xDFDFDF
    };
    myMap.addMarkerByAddress(CustomPOIMarker,
	  "601 Townsend St, San Francisco, CA 94103",
	    markerArgs); 
  }
]]>
</mx:Script>
<yahoo:YahooMap id="myMap" width="550" height="400"
  zoomLevel="3" latitude="37.77159" longitude="-122.401714"
  initialize="onInitialize(event);" />
</mx:Application>

Run the example above

Making the Yahoo! Map Draggable using Flex and ActionScript

<?xml version="1.0"?>
  <mx:Application xmlns:mx="http://www.macromedia.com/2003/mxml"
  xmlns:yahoo="com.yahoo.maps.api.flex.*" xmlns:local="*"
  xmlns="*" >
<mx:Script>
<![CDATA[
  import com.yahoo.maps.tools.PanTool;
  function onInitialize(eventObject) {
    myMap.addTool(new PanTool(), true);
  }
]]>
</mx:Script>
<yahoo:YahooMap id="myMap" width="550" height="400"
  zoomLevel="3"  latitude="37.77159" longitude="-122.401714"
  initialize="onInitialize(event);" />
</mx:Application>

Run the example above

Adding an Overlay to a Yahoo! Map using Flex and ActionScript

Overlays are sets of data points that are displayed on maps. You can define your own overlays or use Yahoo!'s pre-defined overlay classes. A very powerful pre-defined overlay class is LocalSearchOverlay which lets developers automatically plot the results of text searches using the territory defined by a map. To use LocalSearchOverlay, create a new LocalSearchOverlay object, then use the search method to search for a text string. Use the addOverlay method to display the results on the map.

<?xml version="1.0"?>
<mx:Application xmlns:mx="http://www.macromedia.com/2003/mxml"
  xmlns:yahoo="com.yahoo.maps.api.flex.*"
  xmlns:local="*" xmlns="*" >
<mx:Script>
<![CDATA[
  import com.yahoo.maps.overlays.LocalSearchOverlay;
  function onInitialize(eventObject) {
    var localSearch = new LocalSearchOverlay();
    myMap.addOverlay(localSearch);
    localSearch.search('sushi', myMap.getCenter(), 1, 10);
  }; 
]]>
</mx:Script>
<yahoo:YahooMap id="myMap" width="100%" height="100%"
  zoomLevel="3" latitude="37.77159"  longitude="-122.401714"
  initialize="onInitialize(event);" />
</mx:Application>

Run the example above

To use the PolylineOverlay, instantiate a PolylineOverlay object linked to an XML document, then use the addOverlay method to display it on the map.

<?xml version="1.0"?>
<mx:Application xmlns:mx="http://www.macromedia.com/2003/mxml"
  xmlns:yahoo="com.yahoo.maps.api.flex.*"
  xmlns:local="*" xmlns="*" >
  <mx:Script>
  <![CDATA[
    import com.yahoo.maps.overlays.PolylineOverlay;
    function onInitialize(eventObject) {
      var poly = new PolylineOverlay("yourPolyline.xml");
	    myMap.addOverlay(poly);
};

]]> </mx:Script> <yahoo:YahooMap id="myMap" width="100%" height="100%" zoomLevel="14" initialize="onInitialize(event);" /> </mx:Application>

Run the example above

View XML

Adding Widgets to a Yahoo! Map using Flex and ActionScript

You can easily add widgets (such as the NavigatorWidget, ToolBarWidget, or the SatelliteControlWidget to your map to help users navigate or perform other operations. In the following example, the NavigatorWidget and a SatelliteControlWidget are added to the map.

<?xml version="1.0"?>
<mx:Application xmlns:mx="http://www.macromedia.com/2003/mxml"
xmlns:yahoo="com.yahoo.maps.api.flex.*"
xmlns:local="*" xmlns="*" >
<mx:Script>
<![CDATA[
  import com.yahoo.maps.widgets.NavigatorWidget;
  import com.yahoo.maps.widgets.SatelliteControlWidget;
  function onInitialize(eventObject) {
    myMap.addWidget(new NavigatorWidget());
    myMap.addWidget(new SatelliteControlWidget());
  } 
]]>
</mx:Script>
<yahoo:YahooMap id="myMap" width="550" height="400"
zoomLevel="3" latitude="37.77159" longitude="-122.401714"
initialize="onInitialize(event);" />
</mx:Application>

Run the example above

Other Features of the Yahoo! Maps Flex API

This Getting Started Guide only scratches the surface of what is possible using the Flex API. A small sampling of other things you can do:

For detailed descriptions of all classes and methods, check out our online Flash APIs Reference Manual.

Need more help?

Join the yws-maps and yws-maps-flash group on Yahoo! Groups.

Rate Limit

The Yahoo! Maps Flash APIs are limited to 50,000 queries per IP per day. See information on rate limiting.

Terms of Use

Use Yahoo! Maps APIs is governed by 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.

Copyright © 2015 Yahoo! Inc. All rights reserved.

Privacy Policy - Terms of Service - Copyright Policy - Job Openings