Serviços da API do Google Maps para Flash

Visão geral dos serviços

A API do Google Maps para Flash é estendida regularmente, adicionando funcionalidade e recursos novos que costumam ser antes lançados em maps.google.com. Esta seção aborda os recursos da API do Google Maps para Flash, que se comunica com outros serviços do Google. Dessa forma, essas comunicações são geralmente assíncronas e exigem uma manipulação especial.

Geocodificação

Geocodificação é o processo de conversão de endereços (como "1600 Amphitheatre Parkway, Mountain View, CA") em coordenadas geográficas (como latitude 37.423021 e longitude -122.083739), que você pode usar para colocar marcadores ou posicionar o mapa.

O objeto da geocodificação

A geocodificação na API do Google Maps para Flash requer uma solicitação assíncrona aos servidores do Google. Como resultado, você não pode geocodificar um endereço com uma simples chamada de função. Em vez disso, a geocodificação exige o cumprimento das seguintes etapas:

1. Criação de um objeto ClientGeocoder
2. Registro de escutas de evento nesse objeto para eventos do tipo GeocodingEvent
3. Inicialização de uma solicitação de geocódigo pelo ClientGeocoder.geocode()

A solicitação será então enviada ao serviço de geocodificação do Google. O recebimento de uma resposta irá gerar um evento no ClientGeocoder e a resposta da geocodificação poderá ser utilizada.

Eventos e respostas de geocodificação

A API do Google Maps para Flash fornece um GeocodingEvent para armazenar os dados de resposta associados a uma solicitação de geocodificação. Este objeto enumera dois eventos:

• GEOCODING_SUCCESS
• GEOCODING_FAILURE

Você deve configurar escutas de eventos para ambos os casos. Por exemplo:

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

Em cada caso, o evento retorna informações relacionadas à solicitação de geocodificação nas seguintes propriedades do próprio GeocodingEvent.

• request armazena a solicitação original de geocodificação como string de texto.
• requestType armazena o tipo da solicitação de geocodificação (atualmente, "geocodificação" é o único tipo de solicitação).
• response.name armazena a solicitação original de geocodificação como string de texto.
• response.placemarks.address armazena o endereço resolvido.
• response.placemarks.addressDetails armazena detalhes do endereço de acordo com a xAL ou eXtensible Address Language, um padrão internacional para formatação de endereços.
• response.placemarks.point armazena a LatLng do endereço geocodificado.
• status contém o status da solicitação de geocodificação e normalmente armazena informações adicionais sobre a causa da falha de uma tentativa de geocodificação, por exemplo.

A propriedade GeocodingResponse.placemarks retorna uma matriz de Marcadores KML.

Depois de configurar manipuladores apropriados para os eventos GeocodingEvent, você pode iniciar uma solicitação de geocodificação com o método ClientGeocoder.geocode(), que usa um endereço de string como seu único argumento.

No exemplo a seguir, instanciamos um ClientGeocoder, adicionamos escutas aos eventos GeocodingEvent e manipulamos geocódigos bem-sucedidos movendo o mapa para o endereço, adicionando um marcador e adicionando uma escuta de evento ao marcador que exibe o endereço quando o marcador é clicado.

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);
}

Ver exemplo (GeocodingSimple.html)

Ver código-fonte (GeocodingSimple.mxml)

Rotas de tráfego

Você pode adicionar rotas de tráfego à API do Google Maps para Flash usando o objeto Directions. O objeto Directions solicita resultados usando strings de consulta (por exemplo, "Nova York, NY para Chicago, IL") ou latitudes/longitudes textuais (por exemplo, "40.712882, -73.967257 a 41.943181,-87.770677"). Você pode solicitar rotas entre dois ou mais pontos especificando waypoints. Por exemplo, "Nova York, NY para Chicago, IL para São Francisco, CA" retornará rotas para os dois segmentos.

Como iniciar solicitações de rotas

As rotas de tráfego são solicitadas usando o método assíncrono Directions.load(). Esse método usa uma string de consulta e um conjunto de parâmetros DirectionsOptions opcionais. O objeto de rota não é preenchido imediatamente com informações de retorno, já que essas informações precisam ser solicitadas nos servidores do Google. Por esse motivo, o objeto Directions define os dois seguintes eventos DirectionsEvent, que você pode interceptar para determinar este estado: DIRECTIONS_SUCCESS e DIRECTIONS_FAILURE.

Modos de transporte

Por padrão, pressupõe-se que rotas sejam rotas de tráfego, embora você possa solicitar outros modos de transporte passando uma constante com o objeto DirectionsOptions ao chamar o método Directions.load(). São suportados os seguintes modos de transporte:

• DirectionsOptions.TRAVEL_MODE_DRIVING indica rotas de tráfego padrão usando a malha de transporte rodoviário
• DirectionsOptions.TRAVEL_MODE_WALKING solicita rotas a pé através de caminhos de pedestres e calçadas, quando disponíveis.

Observação: Às vezes, as rotas a pé podem não incluir caminhos de pedestres definidos e, como resultado, as solicitações dessas rotas exibem uma mensagem de aviso na primeira vez que as rotas são retornadas.

Como manipular as rotas informadas

Depois que as rotas são informadas com êxito, o objeto Directions armazenará internamente uma polilinha codificada representando as rotas no mapa, além de uma série de instruções textuais de rotas em campos de texto e formato HTML. Para exibir as rotas no mapa, 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());
}

Ver exemplo (DirectionsSimple.html)

Ver código-fonte (DirectionsSimple.mxml)

Rotas e etapas

Instruções textuais de rotas e instruções em formato HTML são retornadas em uma série de um ou mais objetos Route, cada um consistindo em um segmento especificado na consulta original. Cada rota, por sua vez, consiste em um ou mais objetos Step, que contêm as rotas curva-a-curva. Você pode recuperar as rotas usando o método Directions.getRoute(i:Number), em que o número passado refere-se ao segmento das rotas retornadas. As etapas de uma rota podem ser recuperadas usando o método Route.getStep(i:Number).

Os objetos Route armazenam o número de etapas (do tipo Step) da rota, seus geocódigos inicial e final e as demais informações calculadas como, por exemplo, a distância, a duração e a latitude/longitude exata do ponto final (que pode ser diferente daquelas do geocódigo final, caso este não esteja em um segmento de estrada). Todos os objetos Step também contêm a descrição do texto (por exemplo, "Pegue a junção US-101 S pela saída para San Jose"), além das informações calculadas que incluem a distância, a duração e a latitude/longitude exata.

Você pode usar as informações textuais retornadas pelo objeto Directions para exibir descrições textuais curva-a-curva em qualquer DisplayObject. No exemplo a seguir, exibimos rotas curva-a-curva em um objeto <mx:Text>. O código de exemplo abaixo mostra como extrair as informações de rotas e etapas de um objeto Directions.

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;
  }  
}

Ver exemplo (DirectionsAdvanced.html)

Ver código ActionScript (DirectionsAdvanced.mxml)

Para obter a documentação completa dos vários objetos, métodos e eventos no Pacote API de rotas, consulte a Referência da API.