Gerando mapas estáticos com a API do Google Static Maps

Agora você pode gerar imagens de mapas do Google Maps sem usar JavaScript. Tudo o que você precisa é passar alguns parâmetros via URL dentro da tag <img> com o atributo src para o servidor e voilà!, temos um mapinha que pode ser carregado tanto em um website como num browser para celular.

Para utilizar esse serviço, é necessário obter uma chave de acesso do mesmo jeito que a Google Maps API. Você pode obter sua chave simplesmente passando a URL do seu site ou servidor local em http://code.google.com/apis/maps/signup.html. É bom observar que a chave obtida pode ser usada para qualquer aplicação localizada em subdiretórios e subpastars da URL, de modo que não é necessário obter mais que uma chave se você tiver várias aplicações localizadas em diretórios diferentes. Por exemplo, caso eu queira registrar uma chave para a URL http://www.geometrik.info, qualquer aplicação feita com a API em subpastas do tipo http://www.geometrik.info/mashups.php ou http://www.geometrik.info/googlemaps/static/celular/mapa.php irá funcionar perfeitamente.

Introdução

Para gerar uma imagem de um mapa, é necessário definir a localização do centro do mapa, o tamanho da imagem, nível de zoom, tipo do mapa e marcadores que podem ser diferenciados usando caracteres alfabéticos de a a z. O uso da API é restrito a 1000 requisições por dia. Requisições idênticas não são contadas como novas requisições. Caso você ultrapasse o limite de requisições dentro de um período de 24 horas ou abuse no uso da API, o serviço irá parar temporariamente. Se houver reincidência, a chave de uso pode ser permanentemente bloqueada.

Parâmetros

Com dito antes, para gerar um imagem, é necessário especificar alguns parâmetros via URL. Alguns parâmetros são necessários enquanto alguns outros são opcionais. Como é normal em solicitações via HTTP, todos os parâmetros são separadas usando o caracter (&). A URL deve ter a seguinte sintaxe:

href="http://maps.google.com/staticmap?parametros

href=http://maps.google.com/staticmap?center=40.714728,-73.998672&zoom=12&size=512×512&key=BQIAAAAzr2EBOXUKnm_jVnk0OJI7xSosDVG8KKPE1-m51RBrvYughuyMxQ-i1QfUnH94QxWIa6N4U6MouMmBA

A lista de parâmetros e seus valores possíveis são:

• center (necessário se não houver marcadores): Define o centro do mapa equidistante dos cantos do mapa. Os parâmetros que devem ser passados são a latitude e longitude em formato decimal devidamente separados por vírgula.

  Exemplo: center=-23.452544,-46,422562.

• zoom (necessário caso não houver marcadores): Define o nível de zoom do mapa que varia de 1 a 19, dependendo do lugar e do tipo de mapa.

  Exemplo: zoom=12.

• size (necessário): Define as dimensões retangulares (horizontal x vertical) da imagem em pixel. O máximo valor para esse parâmetro é 512 pixels.

  Exemplo: 512×512.

• format (opcional): Define o formato da imagem resultante da solicitação que pode ser GIF, JPG ou PNG. A escolha em usar um ou outro vai depender de qual formato você ache satisfatório para a aplicação. É bom lembrar que JPEG fornce uma boa compressão, enquanto que GIF e PNG possuem mais qualidade e maiores detalhes. Os parâmetros são
  • gif (formato padrão): Define o formato GIF;
  • jpg : Define o formato de compressão JPEG;
  • png32: Define o formato PNG de 32 bits.

Exemplo: format=jpg

• maptype (opcional): Define o tipo de mapa a ser retornado que pode ser do tipo:
  • roadmap (padrão): Define um imagem padrão de arruamentos como aquele que é mostrado na página inicial do Google Maps. Se nenhum valor for passado, a API assume roadmap como padrão.
  • mobile: Define uma imagem para ser visualizado em dispositivos móveis. A imagem é de baixa resolução.

Exemplo: maptype=mobile

• marcadores (opcional): Define um ou mais marcadores anexados à imagem com suas respectivas localizações. Para inserir mais de um marcador, é necessário separar as coordenadas pelo caracter pipe (|). Se você tiver vários marcadores, não é necessário definir a coordenada para o centro ou definir um nível de zoom porque o mapa gera automaticamente de acordo com as distribuição dos marcadores.

  Exemplo: markers=40.702147,-74.015794,blues|40.711614,-74.012318,tinygreen|40.713504,-74.005607,midyellowc& (Lembre-se que o caracter pipe é dado por % 7C, em ASCII, para codificar suas URLs. Não se usa o (|) diretamente na URL, aqui ele é usado apenas para exemplificar).

• path (opcional): Define um traçado entre dois ou mais pontos (não confunda com marcadores) ligados. Esse parâmetro tem uma seqüência de definições separadas pelo caractere pipe (|). Será visto detalhadamente mais abaixo.

• hl (opcional): Define um idioma de exibição de nomes para as features do mapa como arruamentos, praças, bairros, etc. Este parâmetro só funciona para alguns idiomas. Se o idioma não for definido, é adotado o idioma padrão que geralmente é detectado pela API.

• key (necessária): Também chamada de chave de identificação e, como o nome diz, idenfica a API para o dominio ou URL requisitado. Não é possível usar o serviço sem ter uma chave. Para obter a chave, acesse http://code.google.com/apis/maps/signup.html

Coordenadas

As coordenadas são representadas usando valores numéricos decimais para latitude e longitude separados por vírgula. Longitudes é a distância, em graus, entre o ponto e o meridiano de Greenwich na projeção de Mercartor. A latitude também é definida como a distância, em graus, entre o equador e o ponto. A Latitude varia entre -90° e 90° e  a Longitude, -180° a 180°. Latitude e Longitude aceitam até 6 casas decimais.

Latitude e Longitude definem a localização de uma marcador no mapa. Caso a posição de um ou mais marcadores não forem definidas ou estiverem fora da área de cobertura do mapa, eles não aparecerão na imagem se que você definiu um centro para o mapa.

Geocodificação

Geodocodificação não mais é que relacionar um endereço a um par de coordenadas. É por isso que quando você digita um nome ou localidade no Google Maps, ele te retorna essa localicade no mapa. O que ele faz é pegar qual nome está relacionado com aquela coordenada e em seguida usar o valor das coordenadas para inserir a coordenada no mapa.

Você pode obter as coordenadas de um endereço usando o Google Maps simplesmente digitando o endereço e clicando no link Obter link para esta página que está localizado no canto superior direito da página principal do serviço. Ao clicar sobre este link, aparecerá uma janela com a URL do mapa e seus respectivos parâmetros de localização como as coordenadas, nível de zoom e a diferença (spn), em graus, entre a máxima e mínima latitude da janela de visualização, bem como a Longitude.

http://maps.google.com/maps?f=q&hl=pt-BR&geocode=&q=guarulhos-sp,+brasil&ie=UTF8&ll=-23.452223,-46.551819&spn=0.212599,0.299377&z=12

Onde:

• Latitude : -23.452223
• Longitude -46.551819
• Diferença entre a máxima e a mínima latitude da janela de visualização do mapa: 0.212599
• Diferença entre a máxima e a mínima longitude da janela de visualização do mapa: 0.299377
• zoom: 12

Zoom

O zoom permite definir qual o nível de resolução da visualização. Os níveis de zoom variam entre 0 a 19 (dependendo do lugar, o máximo valor de zoom pode ser de apenas 15). A cada nível de zoom sucessivo, a precisão dos detalhes é duplicada, tanto na vertical como na horizontal.

O exemplo abaixo mostra a requisição de dois mapas da cidade de guarulhos com a mesma coordenada de centro, mas com níveis de zoom entre 12 e 14, respectivamente:

Tamanho das imagens

O máximo valor de uma imagem que se pode obter é de 512×512 pixels. O parâmetro deve ser separado pelo caracter x. É bom observar que o parâmetro center, combinado com o size implica na definição da área de cobertura da imagem do mapa. 

Exemplo 1: Mapa com zoom igual a 14, tamanho 512×150 para a cidade de Guarulhos:

Exemplo 2: Mapa com zoom igual a 9, tamanho 512×120 para a cidade de Guarulhos:

Exemplo 3: Mapa com zoom igual a 2, tamanho 512×80 para a cidade de Guarulhos:

Formato de imagens

Como dito no item Introdução, as imagens para os mapas podem ser retornadas nos três tipos mais comuns para Web: GIF, JPEG e PNG. O formato JPG fornece o menor tamanho de imagem, no entanto a sua "super" compressão causa degradação na imagem.

GIF e PNG32 fornecem compressão sem perdas, mas o tamanho são maiores se comparado com um imagem JPEG. PNG32 também oferece um nível de transparência alfa e permite que você defina opacidades diferentes para traçados (paths) que veremos mais abaixo.

Tipos de mapas

Como dito antes, há dois tipos de mapas que podem ser criados conforme o uso: roadmap e mobile. Você ver abaixo a diferença entre esses dois tipos:

Marcadores

Os parâmetros para definir marcadores definem um conjunto de um ou mais marcadores "sobrepostos" à imagem. Esses marcadores são separados pelo caracter (|) ou %7C em ASCII se você codificar em URL. Os parâmetros podem assumir as seguintes atribuições:

markers=markerDescriptor1|markerDescriptor2|markerDescriptor3|… etc.

Identificador de marcadores

Os marcadores podem ser identificados através de uma string que define a sua localização e o visual (cor e etiqueta). Cada string contém as seguintes variáveis:

• latitude (necessário): Define o valor latitudinal com precisão de 6 casas decimais.
• longitude (necessário): Especifica um valor longitudinal com precisão de 6 casas decimais.
• color (opcional): Especifica uma cor de um conjunto de cores disponíveis (red,blue e green).
• alpha-character (opcional): Define um único caracater alfabético minúsculo de a a z.

A cor e o caracter definem a aparência visual do marcador. Se não forem definidos cor e etiqueta, então o marcador assume o padrão do Google Maps, aquele vermelho que parece uma lágrima ao contrário:

Os marcadores se diferenciam pela cor (preto, marrom, verde, roxo, vermelho, amarelo, azul, cinza, laranja e branco), tamanho (normal, mid, small e tiny) e por um caracter de identificação (A,B,C,D,E,F e G) que é restrito aos tamanhos normal e mid.

No exemplo abaixo, a declarção define dois marcadores, separados pelo caracter (|), um com a etiqueta "S" nas coordenadas -23.463052,-46.54145 e uma verde com coordenadas -23.464052,-46.54445 com a etiqueta G. Repare que os parêmetros para cor e caracter não são separados por vírgula.

markers=-23.463052,-46.54145,blues|-23.464052,-46.54445,greeng&key=MAPS_API_KEY

Posicionamento condicional

Normalmente é necessário definir os parâmetros center e zoom para a localização e o nível de zoom, respectivamente, para gerar o mapa. Entretando, se esses parâmetros forem suprimidos, a API determina o centro e o zoom automaticamente baseados na distribuição dos marcadores. Obviamente que quanto mais distantes forem os marcadores, menor será o nível de zoom.

Se você suprimir dois ou mais marcadores, a API determinará um nível de zoom e centro apropriado. O exemplo abaixo contém as mesmas marcas do exemplo anterior, mas sem os parâmetros de centro e nível de zoom forneceido anteriormente.

Caminhos

O  parâmetro path define um conjunto de dois ou mais pontos interligados por linhas e que são sobrepostos ao mapa. Os atributos desse parâmetros são:

path = cor: pathColorValue, espessura: pathWeight | pathPonto1 | pathPonto2 | pathPonto3 |…

ou seja:

http://maps.google.com/staticmap?path=rgb:0×0000ff,weight:3%7C-23.464052,-46.54445%7C-23.463052,-46.54145

É necessário separar cada traçado com o caractere pipe (|). Lembre-se que o caracter pipe é dado por % 7C, em ASCII, para codificar suas URLs. Não se usa o (|), aqui ele é usado apenas para exemplificar.

Atributos

O Path pode ser inicializado com um atributo opcional de cor e um valor para esse tipo separados por dois pontos (ex:rgb:0×0000ff). Se a cor não for definida, ele toma a cor azul como padrão. Há dois tipos possíveis para cor que é definida pelo atribute pathColorTypes:

• rgb : especifica um esquema de cores RGB padrão de 24 bits usando um valor de cor hexadecimal 0xffffff como o pathColorValue. A opacidade padrão para o rgb é de 50%.
• rgba: especifica um valor hexadecimal de 32 bits para a cor na forma 0xffffffff para o atributo pathColorValue, onde o quarto byte (os dois últimos caracteres) especifica um canal de transparência alfa. O uso do rgba permite que você possa variar a transparência para qualquer path que criar.

Em adição a este parâmetro, é possível usar o peso (weight) que define a espessura do traçado em pixels.

Exemplos:

• Linha azul fina com 50% de opacidade: caminho = rgb: 0×0000ff, weight: 1
• Linha vermelha sólida: rgba: 0xff0000ff, weight: 5
• Linha preta espessa: rgba: 0xffffffff, weight: 10 
   

Pontos

Para se ter um caminho, parâmetro path deve conter e passar obrigatoriamente por dois ou mais pontos. O Google Maps API Estático irá então ligar o percurso ao longo desses pontos, pela ordem especificada. Cada ponto deve ser inserido no path e separado pelo caracter pipe (|). Tal como acontece com marcadores, o Google Maps API Static tentará determinar o centro e o zoom de mapa de acordo com o posicionamento dos caminhos definidos. Há um limite de 50 pontos para qualquer path.

Exemplo 1: Linha azul, 50% de opacidade, weight igual a 5 e mapa do tipo roadmap

Exemplo 2: Linha azul, 50% de opacidade, weight igual a 3 e mapa do tipo mobile

Exemplo 3: Linha vermelha, 100% de opacidade, weight igual a 5 e mapa do tipo roadmap

Exemplo 4: Linha azul, 100% de opacidade, weight igual a 3 e mapa do tipo mobile

Wizard

Você pode gerar seus mapas estáticos usando uma interface desenvolvida pelo time da Google Maps Static API. O endereço é http://gmaps-samples.googlecode.com/svn/trunk/simplewizard/makestaticmap.html.

Você pode criar polígnos, polilinhas e marcadores personalizados.