Google Maps API for Flash Services

Services Overview

The Google Maps API for Flash will be regularly extended, adding new functionality and features that are often released on maps.google.com first. This section covers Google Maps API for Flash features which communicate with other Google services. As such, these communications are usually asynchronous and require special handling.

Geocoding

Geocoding is the process of converting addresses (like "1600 Amphitheatre Parkway, Mountain View, CA") into geographic coordinates (like latitude 37.423021 and longitude -122.083739), which you can use to place markers or position the map.

The Google Maps API for Flash provides a client geocoder for geocoding addresses dynamically from user input. If instead, you wish to geocode static, known addresses, see the Geocoding Service documentation.

The Geocoding Object

Geocoding within the Google Maps API for Flash requires an asynchronous request to Google's servers. As a result, you cannot geocode an address through a simple function call. Instead, geocoding requires the following steps:

1. Creation of a ClientGeocoder object
2. Registration of event listeners on that object for events of type GeocodingEvent
3. Initiation of a geocode request via the ClientGeocoder.geocode()

The request will then be sent to Google's geocoding service. Receipt of a response will then generate an event on the ClientGeocoder, and the geocoding response can be utilized.

Geocoding Events and Responses

The Google Maps API for Flash provides a GeocodingEvent for holding the response data associated with a geocoding request. This object enumerates two events:

• GEOCODING_SUCCESS
• GEOCODING_FAILURE

You should set up event listeners for both cases. For example:

var geocoder:ClientGeocoder = new ClientGeocoder();
geocoder.addEventListener(GeocodingEvent.GEOCODING_SUCCESS, handleGeocodingSuccess);
geocoder.addEventListener(GeocodingEvent.GEOCODING_FAILURE, handleGeocodingFailure);

In each case, the event returns information related to the geocoding request in the following properties of the GeocodingEvent itself:

• request stores the original geocoding request as a text string.
• requestType stores the type of geocoding request (currently "geocoding" is the only request type).
• response.name stores the original geocoding request as a text string.
• response.placemarks.address stores the resolved address.
• response.placemarks.addressDetails stores address details conforming to xAL, or eXtensible Address Language , an international standard for address formatting.
• response.placemarks.point stores the LatLng of the geocoded address.
• status contains the status of the geocoding request and generally holds additional information for why a geocoding attempt has failed, for example.

(Note that the GeocodingResponse.placemarks property returns an array of KML Placemarks.)

Once you have set up proper handlers for the GeocodingEvent events, you can initiate a geocode request with the ClientGeocoder.geocode() method, which takes a string address as its sole argument.

In the following example, we instantiate a ClientGeocoder, add event listeners to the GeocodingEvent events, and handle successful geocodes by moving the map to the address, adding a marker, and adding an event listener to the marker that displays the address if the marker is clicked.

private function doGeocode(event:GeocodingEvent):void {
  var geocoder:ClientGeocoder = new ClientGeocoder();
  geocoder.addEventListener(GeocodingEvent.GEOCODING_SUCCESS,
      function(event:GeocodingEvent):void {
        var placemarks:Array = event.response.placemarks;
        if (placemarks.length > 0) {
          map.setCenter(placemarks[0].point);
          var marker:Marker = new Marker(placemarks[0].point);
          map.addOverlay(marker);
          marker.addEventListener(MapEvent.CLICK,
              function(event:MapEvent):void {
                marker.openInfoWindow(new InfoWindowOptions({
                  title: "Geocoded Result",
                  content: placemarks[0[]].address
                }));
              });
        }
      });
  geocoder.addEventListener(GeocodingEvent.GEOCODING_FAILURE,
        function(event:GeocodingEvent):void {
          trace("Geocoding failed");
        });
  geocoder.geocode(address.text);
}

View example (GeocodingSimple.html)

View Source (GeocodingSimple.mxml)

Driving Directions

You can add driving directions using the Google Maps API for Flash by using the Directions object. The Directions object requests results using either query strings (e.g. "New York, NY to Chicago, IL") or provided textual lat/lons (e.g. "40.712882, -73.967257 to 41.943181,-87.770677"). You may request directions between two or more points by specifying waypoints. For example, "New York, NY to Chicago, IL to San Francisco, CA" will result in directions being returned for both segments.

Initiating Directions Requests

Driving directions are requested using the asynchronous Directions.load() method. This method takes a query string and a set of optional DirectionsOptions parameters. Note that the directions object is not populated with return information immediately, as this information needs to be requested from Google's servers. For this reason, the Directions object defines the following two DirectionsEvent events which you can intercept to determine this state: DIRECTIONS_SUCCESS and DIRECTIONS_FAILURE.

Travel Modes

By default, directions are assumed to be driving directions though you may request other modes of travel by passing a constant within the DirectionsOptions object when calling the Directions.load() method. The following travel modes are supported:

• DirectionsOptions.TRAVEL_MODE_DRIVING indicates standard driving directions using the road network
• DirectionsOptions.TRAVEL_MODE_WALKING requests walking directions via pedestrian paths & sidewalks (where available.)

Note: Walking directions may sometimes not include clear pedestrian paths; as a result, requesting walking directions will initially display a warning message box the first time such directions are retrieved.

Handling Returned Directions

Once directions are successfully returned, the Directions object will internally store an encoded polyline representing the directions on the map, and a series of textual directions within textual and HTML-formatted fields. To display the directions on the map use Directions.createPolyline().

private function onMapReady(event:Event):void {
 
  // Create a directions object
  var dir:Directions = new Directions();
  dir.addEventListener(DirectionsEvent.DIRECTIONS_SUCCESS, onDirLoad);
  dir.addEventListener(DirectionsEvent.DIRECTIONS_FAILURE, onDirFail);
  dir.load("77 Massachusetts Avenue, Cambridge, MA to 4 Yawkey Way, Boston, MA 02215 (Fenway Park)");
}

private function onDirFail(event:DirectionsEvent):void {
  // Process failure, perhaps by showing an alert
}

private function onDirLoad(event:DirectionsEvent):void {
  var dir:Directions = event.directions;
                
  map.clearOverlays();
  map.addOverlay(dir.createPolyline());
}

View example (DirectionsSimple.html)

View Source (DirectionsSimple.mxml)

Routes and Steps

Textual and HTML-formatted directions are returned within a series of one or more Route objects, each consisting of a segment specified in the original query. Each route in turn consists of one or more Step objects, which contain the turn-by-turn directions. You can retrieve the routes using the Directions.getRoute(i:Number) method, where the passed number refers to the segment of the returned directions. Steps within a route can be retrieved using the Route.getStep(i:Number) method.

Route objects store the number of steps (of type Step) for that route, the starting and ending geocode for that route, and other computed information such as distance, duration, and exact lat/lon of the endpoint (which may be different than the ending geocode if the geocode does not lie on a road segment). Each Step object as well contains the description for that text (e.g. "Merge onto US-101 S via the ramp to San Jose") plus computed information including the distance, duration, and exact lat/lon.

You may use the textual information returned by the Directions object to display turn-by-turn textual descriptions within any DisplayObject. In the following example, we display turn-by-turn directions within an <mx:Text> object. The sample code below shows how to extract route and step information from a Directions object.

private var map:Map;
private var dir:Directions;
private var turnCounter:uint = 0;

private function onMapReady(event:MapEvent):void {
  map.setCenter(new LatLng(41.651505,-72.094455), 8, MapType.NORMAL_MAP_TYPE);
  dir = new Directions();
  dir.addEventListener(DirectionsEvent.DIRECTIONS_SUCCESS, onDirLoad);
  dir.addEventListener(DirectionsEvent.DIRECTIONS_FAILURE, onDirFail);
}

private function onDirFail(event:DirectionsEvent):void {
  Alert.show("Status: " + event.directions.status);
  step.htmlText = "";
}

private function onDirLoad(event:DirectionsEvent):void {
  var dir:Directions = event.directions;       
  var startMarker:Marker;
  var endMarker:Marker;
        
  map.clearOverlays();
  map.addOverlay(dir.createPolyline());
  map.setZoom(map.getBoundsZoomLevel(dir.bounds));
  map.setCenter(dir.bounds.getCenter());
  
  startMarker = new Marker(dir.getRoute(0).startGeocode.point, new MarkerOptions({fillStyle: {color:Color.GREEN}}));
  endMarker = new Marker(dir.getRoute(0).endGeocode.point, new MarkerOptions({fillStyle: {color:Color.BLUE}}));
  map.addOverlay(startMarker);
  map.addOverlay(endMarker);
}

private function processTurnByTurn():void  {
  
  var stepText:String;
  var stepMarker:Marker;
  turnCounter++;
  
  if (turnCounter <= dir.getRoute(0).numSteps) {
    stepText = dir.getRoute(0).getStep(turnCounter-1).descriptionHtml;
    stepMarker = new Marker(dir.getRoute(0).getStep(turnCounter-1).latLng, new MarkerOptions({label: turnCounter.toString()}));
    map.addOverlay(stepMarker);
    step.htmlText = "Step " + turnCounter + ": " + stepText;  
  } else {
    getTurnByTurnDirections.enabled = false;
    step.htmlText = "Arrive at " + to.text + " : " + dir.getRoute(0).summaryHtml;
  }  
}

View example (DirectionsAdvanced.html)

View ActionScript code (DirectionsAdvanced.mxml)

For full documentation of the various objects, methods and events in the Directions API package, consult the API Reference.