Curso de Google Maps - Versão 0.0.3 - 07/10/2008

A API Javascript do Google Maps permite a criação de aplicações na web com mapas embutidos. Além disso, a API permite que se altere o comportamento dos mapas com a inserção de marcadores, camadas, desenhos, até mesmo, o cálculo de rotas.
O objetivo deste curso é que você aprenda, de maneira interativa a trabalhar com a API do Google Maps.
Entretanto, os conceitos aqui expostos poderão também ser adaptados a outras APIs de mapas e serviços Ajax em geral.
A melhor forma de aprendermos a trabalhar com o Google Maps é através de exemplos. Interaja!

O primeiro passo para o desenvolvedor é obter uma conta do Google.
Para usar a API você precisa de uma identificação com o Google. Será necessário que você gere uma chave.
Essa chave é única para o seu web site.
Preste atenção nas restrições de uso!
- Não há propaganda no mapa, mas, um dia poderá existir;
- Seu serviço deve ser de acesso gratuito, caso contrário, use a solução para empresas;
- Você não pode alterar os logotipos e créditos do mapa.

Após se cadastrar, você poderia usar essa chave em nosso primeiro exemplo.
Para facilitar, porém, o Google não obriga o uso da chave caso você esteja trabalhando no localhost ou com um arquivo local.

Chegamos a nosso primeiro exemplo! Clique aqui para abrí-lo em uma nova janela.
Vamos entender parte por parte deste código.

<script src="http://maps.google.com/maps?file=api&v=2&key=minha_chave" type="text/javascript"> </script>
O endereço indicado em http://maps.google.com/maps?file=api&v=2&key=minha_chave aponta para o Javascript que contém a API do Google Maps.
Você não pode copiar para seu site esse arquivo.
Não esqueça de substituir 'minha_chave' pelo valor de sua chave.

<div id="map_canvas" style="width: 500px; height: 300px"></div>

O mapa deve ser exibido em um ponto qualquer da tela.
Para isso, geralmente criamos um elemento div com uma largura e altura fixas.

Dentro da função initialize(), que é chamada quando a página carrega (evento OnLoad da janela do navegador), o primeiro passo é carregar o objeto de mapa.
Observe que o nome do elemento que estamos trabalhando é o mesmo da div criada logo abaixo.
GMap2 é o construtor do mapa e possui diversos parâmetros para alterar seu comportamento.

var map = new GMap2( document.getElementById("map_canvas") );

map.setCenter(new GLatLng(37.4419, -122.1419), 13);
Apenas com os passos anteriores, o mapa aparecerá como uma imagem em cinza.
É necessário, portanto, dizer em que local será o centro do mapa e qual será o nível de zoom.
O local é indicado através de latitudes e longitures através da classe GLatLng e o nível de zoom 0 (mais longe da rua) 19 (mais distante da rua).

<body onload="initialize()" onunload="GUnload()">

Não custa lembrar... A função initialize() só será chamada quando a página for carregada por completo (evento onload).
O evento onunload é necessário para se evitar problemas de memória quando a aplicação é fechada.

Ok! Entendido o esquema básico de trabalho com o Google Maps, vamos agora trabalhar com um conjunto de códigos para exemplificar as funcionalidades do Google Maps.
Interaja abaixo para executar esses códigos!

Primeiro, vamos centralizar o nosso mapa em Curitiba, no marco 0 da cidade.
Observe que o mapa permite movimentação via drag & drop mas não permite zoom.
Para conseguir coordenadas de outras cidades de uma maneira rápida, use a Wikipedia.

Agora, movi o centro do mapa para a localização da PUCPR.
Em Javascript posso instanciar objetos sem precisar declarar seu tipo de dado.
Assim, a palavra-chave var não é obrigatória na criação de um objeto GLatLng, mas é útil para garantir que o escopo da variável PUC seja local.

No exemplo anterior, o movimento do centro até a PUCPR foi instantâneo.
Com a função panTo nós podemos mover de um ponto a outro de uma maneira mais suave.
Isso só funciona, porém, se os pontos estiverem próximos, caso contrário, o movimento será imediato.

Uma função Javascript bastante útil para executar um comando após um certo tempo é a função window.setTimeout.
Você pode utilizá-la em conjunto com o panTo.
No exemplo vamos do Cemitério da Água Verde até a PUCPR em após 2 segundos parado no centro da cidade.
Note que usei uma função anônima (sem nome) em Javascript como parâmetro da função setTimeout.

Até agora trabalhei com coordenadas geográficas.
O Google Maps também permite que se trabalhe com a obtenção de coordenadas a partir de endereços (GEOCODING).
Infelizmente, a versão atual do Google Maps não trabalha com o processo reverso, ou seja, dada a coordenada, obter o endereço (GEOCODING REVERSO).
O processo de Geocoding é feito de diversas maneiras, tanto por um serviço REST quanto via Javascript.
Abaixo estou montando a url típica de chamada ao serviço REST e você será encaminhado a uma página XML com as informações de Geocoding da PUCPR.

Os parâmetros para a montagem da solicitação de endereço são:

q - o endereço a ser descoberta a coordenada
key - a sua chave
output - o formato de saída (xml, kml, csv, json)

O formato KML pode ser colado diretamente no Google Earth e o formato JSON representa um objeto em Javascript.
Além do serviço REST, você também pode usar um objeto GClientGeocoder para retornar uma coordenada como no código abaixo.
Importante! O código de Geocoding no localhost não funciona!

Se você achou difícil ler o código anterior, reescrevi sem usar uma função anônima.

Embora você possa controlar via programação o comportamento dos seus mapas, o Google Maps também possui controles de zoom e de troca de visualização:

GLargeMapControl / GSmallMapControl - Controle de movimento e zoom que aparece acima e à esquerda do mapa;
GSmallZoomControl - Controle de zoom usado para roteamento;
GScaleControl - Escalonamento do mapa;
GMapTypeControl - Troca de tipo de mapa;
GOverviewMapControl - Minimapa no canto da tela.

No exemplo anterior, coloquei alguns controles associados ao mapa.
Se você quiser também pode colocar os controles em outras posições ou criar controles personalizados.
Abaixo, usando a classe GControlPosition, código para colocar em posições diferentes da posição padrão com um deslocamento de 10 pixels em relação a borda.
Observe que você pode ter dois controles do mesmo tipo no seu mapa!

Se não quiser usar um controle customizado, existem funções para alterar via Javascript o tipo de mapa (setMapType), o nível de zoom (setZoom / getZoom), etc.
No código exemplo, também é ilustrado o uso da função Javascript setInterval que serve para executar uma função de tempos em tempos.
A função clearInterval interrompe a execução da função.

Diversos tipos de camadas gráficas podem ser colocadas sobre o seu mapa.
A mais simples delas é a janela de informações, chamada pelas funções openInfoWindow e openInfoWindowHTML do objeto de mapa.
Abaixo, uma janela de informações é aberta no centro da tela.
Atenção: apenas uma janela de informações pode ser exibida de cada vez!

Por sua vez, openInfoWindowHtml pode receber um string HTML como conteúdo da janela de informações.

Você pode associar eventos ao mapa, usando a função GEvent.addListener.
Tal função recebe como parâmetro:

O mapa que vai ser associado ao evento;
O tipo de evento;
A função a ser executada quando o evento for chamado.

No exemplo, quando o mapa é clicado (evento click), exibe-se um alerta.

Mais importante que saber associar o evento ao mapa é extrair as informações importantes do evento, ou seja, os seus argumentos.
Por exemplo, no caso de um evento de clique (click) ou de clique duplo (dblclick), é interessante saber o ponto que foi clicado.
Abaixo, uma janela de informações é exibida no clique duplo do mouse.

Na documentação do Google Maps você encontra os demais eventos disponíveis para o mapa, por exemplo:

singlerightclick: Botão direito
move: Chamado constantemente enquanto o mapa se move
moveend: Chamado quando pára o movimento do mapa

Não é só o mapa possui eventos. Overlays (camadas ou marcadores) também podem ser associados a eventos.

Overlays (camadas) são objetos associados a uma certa latitude/longitude e que, portanto, se movem quando o mapa é movido.
Cada tipo de overlay está associado a uma classe específica:

GMarker: Pontos no Mapa (marcadores);
GPolyline: Linhas;
GPolygon: Polígonos;
GTileLayerOverlay : Mapas personalizados;
GInfoWindow: Janela única de informação.

Abaixo, exemplo de colocação de um marcador qualquer no ponto central da tela.

Marcadores foram feitos para se interagir com eles.
Dessa forma, o GEvent também pode ser usado para associar eventos aos marcadores.
No exemplo abaixo, quando se clica no marcador, uma janela de informação do marcador é exibida.

Marcadores também podem ser arrastados de um local para outro;
É necessário, neste caso, marcá-los com o parâmetro draggable durante a sua criação;
Para tratar o drag & drop use os eventos dragstart e dragend.

Podemos utilizar mais de um marcador em um mesmo mapa.
O exemplo mostra a colocação de 5 marcadores em pontos aleatórios dentro do mapa.
As primeiras linhas são para obter os limites do mapa dentro da janela de visualização.

Muitas vezes é necessário diferenciar cada um dos marcadores.
Uma abordagem possível está no uso de closures.
Uma closure ocorre quando uma função dentro de outra referencia variáveis locais da função exterior em tempo de execução.
O exemplo mostra cada marcador sendo diferenciado por um identificador numérico.

Um uso ainda pouco comum dos marcadores é na criação de janelas de informação com mais de uma aba.

Você não está limitado a usar os marcadores padrão.
Também é possível, através da classe GIcon, associar um ícone diferente ao seu marcador.
O programador deve se preocupar tanto com o ícone do marcador quanto com o ícone de sua sombra.

O Google Maps também tem a possibilidade de carregar de maneira assíncrona, dados de uma url diferente.
Ou seja, é possível fazer chamadas a arquivos externos que possuem, por exemplo, informações sobre os marcadores ou configurações em geral.
Usamos, neste caso, o método GDownloadUrl para as chamadas e GXml para percorrer o arquivo Xml recebido.
Lembre-se: por segurança você só pode chamar arquivos que estão dentro do seu site!

Para fechar o tópico sobre marcadores, uma dica: use o utilitário MarkerManager quando trabalhar com centenas ou milhares de marcadores em um mesmo mapa.
Com esse utilitário evita-se problemas de performance.
Importante: para utilizá-lo é necessário incluir o script do Google Maps Utilities.

Uma Polyline consiste em um conjunto de segmentos de reta determinados por um conjunto de pontos.
Objetos GPolyline são usados para construir linhas.
No exemplo, é criada uma linha entre o Passeio Público e a Praça Rui Barbosa da cor verde (#00FF00) e com largura 15.
Detalhe: no Internet Explorer a linha não é exibida se você abrir o arquivo localmente!

Por padrão, as polylines não consideram a curvatura da terra.
Para que isso aconteça, use a opção {geodesic:true} quando construir a polyline.

A classe GDirections trata do trabalho com rotas.
Através desta classe podemos lidar com rotas entre duas cidades e, até mesmo, dois endereços.
Este exemplo não funciona no Internet Explorer em modo local!
Talvez seja melhor ver em uma janela em separado.

Mais um exemplo, agora com endereços.