Pronto!

Para começar a desenvolver, acesse nossa documentação do desenvolvedor.

Ativar a Google Static Maps API

Para começar, orientaremos você pelo Console do Desenvolvedor do Google para realizar algumas atividades:

  1. Criar ou selecionar um projeto
  2. Ativar a Google Static Maps API
  3. Criar chaves apropriadas
Continuar

Guia do desenvolvedor da Google Static Maps API

O Google Static Maps API permite que você integre uma imagem do Google Maps em sua página da web sem precisar de JavaScript nem qualquer tipo de carregamento dinâmico de página. Com o Google Static Maps API, você cria um mapa com base em parâmetros de URL enviados por meio de uma solicitação HTTPS padrão e retorna-o como uma imagem que pode ser exibida em sua página.

Observação: os limites de uso do Google Static Maps API mudaram. Criar uma chave de API e inclui-la em sua solicitação permite que você rastreie o uso no Google API Console e compre mais cota, se necessário.

Este documento fornece detalhes sobre o Google Static Maps API v2. Para atualizar seus URLs do v1, consulte o Guia de atualização.

Um exemplo rápido

O exemplo a seguir contém o URL de uma imagem do Google Static Maps API para o centro da cidade de Nova York, que é exibida abaixo:

https://maps.googleapis.com/maps/api/staticmap?center=Brooklyn+Bridge,New+York,NY&zoom=13&size=600x300&maptype=roadmap
&markers=color:blue%7Clabel:S%7C40.702147,-74.015794&markers=color:green%7Clabel:G%7C40.711614,-74.012318
&markers=color:red%7Clabel:C%7C40.718217,-73.998284
&key=YOUR_API_KEY

Pontos de interesse em Lower Manhattan

Observe que não é preciso fazer nada "especial" para que essa imagem seja exibida na página. Não é preciso usar JavaScript. Basta criar um URL e colocá-lo em uma tag <img>. Você pode inserir um Google Google Static Maps API em qualquer lugar da sua página que possa comportar uma imagem.

Público-alvo

Este documento é destinado a desenvolvedores de sites e dispositivos móveis que desejam incluir imagens do Google Static Maps API em uma página ou um aplicativo móvel. Ele fornece uma introdução sobre como usar a API e materiais de referência sobre os parâmetros disponíveis.

Visão geral

O Google Static Maps API retorna uma imagem (GIF, PNG ou JPEG) em resposta a uma solicitação HTTP por meio de um URL. Para cada solicitação, você pode especificar a localização do mapa, o tamanho da imagem, o nível de zoom, o tipo de mapa e a inclusão de marcadores opcionais em pontos do mapa. Também é possível rotular seus marcadores com caracteres alfanuméricos.

Uma imagem do Google Static Maps API é integrada no atributo src de uma tag <img> ou o elemento equivalente em outras linguagens de programação. Se uma imagem do Google Static Maps API for usada fora de um aplicativo web (como um navegador), será necessário incluir um link apontando para o local de exibição em um navegador ou aplicativo nativo do Google Maps. Os usuários da Google Maps APIs Premium Plan estão isentos desse requisito. Consulte a seção 10.1.1(h) dos Termos de Serviço do Google Maps/Google Earth para obter as informações completas e mais atualizadas sobre esse requisito.

Este documento descreve o formato obrigatório de URLs do Google Static Maps API e os parâmetros disponíveis. Ele também apresenta algumas dicas e truques para especificar seus URLs.

Parâmetros de URL

Um URL do Google Static Maps API deve ter o seguinte formato:

https://maps.googleapis.com/maps/api/staticmap?parameters

Se seu site for acessado por HTTPS, é preciso carregar imagens do Google Static Maps API em HTTPS para evitar alertas de segurança de navegadores. Também é recomendável o uso de HTTPS para solicitações que incluam dados confidenciais de usuários, como a localização:

https://maps.googleapis.com/maps/api/staticmap?parameters

Independentemente de usarem HTTP ou HTTPS, alguns parâmetros de URLs são obrigatórios, enquanto outros são opcionais. Como é padrão em URLs, todos os parâmetros são separados usando o caractere E comercial (&). A lista de parâmetros e os possíveis valores estão enumerados abaixo.

Importante: a discussão sobre parâmetros de URL abaixo usa exemplos que, para fins de clareza, se encontram no formato pré-escape. Antes de enviar solicitações para a API, seus parâmetros devem ser codificados para URL. Por exemplo, muitos parâmetros usam um caractere de barra vertical (|) como separador, que deve ser codificado como %7C no URL final, como no exemplo rápido exibido no topo deste documento. Para saber mais, consulte Criar um URL válido.

O Google Static Maps API define imagens de mapa usando os seguintes parâmetros de URL:

Parâmetros de localização

  • center (obrigatório se não houver marcadores presente) define o centro do mapa, equidistante de todas as bordas. Esse parâmetro comporta uma localização como um par de {latitude,longitude} separado por vírgula (por exemplo: "40.714728,-73.998672") ou uma string de endereço (por exemplo: "prefeitura, nova york, ny") que identifique uma localização singular no mundo. Para saber mais, consulte a seção Localizações abaixo.
  • zoom (obrigatório se não houver marcadores presente) define o nível de zoom do mapa, o que determina o nível de expansão do mapa. O parâmetro comporta um valor numérico que corresponde ao nível de zoom da região desejada. Para saber mais, consulte a seção Níveis de zoom abaixo.

Parâmetros de mapa

  • size (obrigatório) define as dimensões retangulares da imagem do mapa. Esse parâmetro comporta uma string no formato {horizontal_value}x{vertical_value}. Por exemplo, 500x400 define um mapa com 500 pixels de largura e 400 pixels de altura. Mapas com menos de 180 pixels exibirão um logotipo do Google de tamanho reduzido. Esse parâmetro é afetado pelo parâmetro scale descrito abaixo. O tamanho da saída final é o produto dos valores de size e scale.
  • scale (opcional) afeta o número de pixels retornados. scale=2 retorna duas vezes mais pixels que scale=1, mantendo a mesma área de cobertura e o mesmo nível de detalhes, ou seja, o conteúdo do mapa não muda. Isso é útil ao desenvolver para telas de alta resolução ou ao gerar um mapa para impressão. O valor padrão é 1. Valores aceitos são 2 e 4. (4 está disponível apenas para clientes do Google Maps APIs Premium Plan.) Consulte Valores de escala para saber mais.
  • format (opcional) define o formato da imagem resultante. Por padrão, o Google Static Maps API cria imagens PNG. Existem vários formatos possíveis, incluindo GIF, JPEG e PNG. O formato usado depende de como você pretende apresentar a imagem. JPEG geralmente oferece mais compactação, enquanto GIF e PNG oferecem mais detalhes. Para saber mais, consulte Formatos de imagem.
  • maptype (opcional) define o tipo de mapa a ser criado. Existem vários valores possíveis para esse parâmetro, incluindo roadmap, satellite, hybrid e terrain. Para saber mais, consulte a seção Tipos de mapa do Google Static Maps API abaixo.
  • language (opcional) define o idioma usado para exibir os rótulos dos títulos do mapa. Observe que esse parâmetro só é permitido em alguns blocos de países. Se o idioma específico solicitado não for permitido em um determinado bloco de país, o idioma padrão será usado.
  • region (opcional) define as bordas apropriadas a serem exibidas com base em limites geopolíticos. Esse parâmetro aceita códigos de região especificados como um valor de ccTLD ("domínio de nível superior") de dois caracteres.

Parâmetros de recursos

  • markers (opcional) define um ou mais marcadores para inserir em pontos específicos da imagem. Esse parâmetro comporta uma só definição de marcador, com parâmetros separados pelo caractere de barra vertical (|). É possível inserir vários marcadores no mesmo parâmetro markers desde que eles tenham o mesmo estilo. Para incluir marcadores de estilos diferentes, adicione mais parâmetros markers. Observe que, se você fornecer marcadores para um mapa, não será preciso especificar os parâmetros center e zoom, que normalmente são obrigatórios. Para saber mais, consulte a seção Marcadores do Google Static Maps API abaixo.
  • path (opcional) define um caminho para dois ou mais pontos conectados para sobrepor na imagem em locais especificados. Esse parâmetro comporta uma string de definições de ponto separadas pelo caractere de barra vertical (|). Você pode fornecer caminhos adicionais incluindo mais parâmetros path. Observe que, se você fornecer um caminho para um mapa, não será preciso especificar os parâmetros center e zoom, que normalmente são obrigatórios. Para saber mais, consulte a seção Caminhos do Google Static Maps API abaixo.
  • visible (opcional) especifica uma ou mais localizações que devem permanecer visíveis no mapa, mesmo que marcadores ou outros indicadores não sejam exibidos. Use esse parâmetro para garantir que certos componentes ou localizações do mapa sejam mostrados no Google Static Maps API.
  • style (opcional) define um estilo personalizado para alterar a apresentação de um componente específico (estradas, parques e outros recursos) do mapa. Esse parâmetro comporta argumentos feature e element que identifiquem os componentes a serem estilizados e um conjunto de operações de estilo a aplicar aos componentes selecionados. É possível fornecer vários estilos adicionando parâmetros style. Para obter mais informações, consulte o guia de mapas estilizados.

Parâmetros de chave e assinatura

  • key (obrigatório) permite que você monitore o uso da API do aplicativo no Google API Console, permite o acesso a uma boa cota diária gratuita e garante que a Google possa contatar você para falar sobre o aplicativo, se necessário. Para saber mais, consulte Obter uma chave e uma assinatura.
  • signature (recomendado) é uma assinatura digital usada para confirmar que qualquer site que gere solicitações usando sua chave de API tenha autorização para fazê-lo. Observação: Se você ativar a cobrança, a assinatura digital é obrigatória. Se você exceder o limite diário gratuito de carregamentos de mapa, precisará pagar por carregamentos adicionais para o restante do dia. Carregamentos de mapa pagos que não têm assinatura digital não funcionam. Para saber mais, consulte Obter uma chave e uma assinatura.

Observação: clientes Google Maps APIs Premium Plan podem usar uma chave de API e uma assinatura digital ou um ID de cliente válido e uma assinatura digital nas solicitações do Static Maps. Saiba mais sobre parâmetros de autenticação para clientes Premium Plan.

Clientes com uma licença antiga do Google Maps APIs for Work devem incluir parâmetros client e signature válidos com as solicitações, em vez de key. Para obter mais informações, consulte a seção IDs de cliente e assinaturas da página "Obter uma chave e uma assinatura".

Restrição de tamanho de URLs

Os URLs da Google Static Maps API têm um limite de 8192 caracteres. Na prática, você provavelmente não precisará de URLs maiores do que isso, a não ser que produza mapas complicados com muitos marcadores e caminhos. Observe, no entanto, que alguns caracteres poderão receber codificação de URL de navegadores e/ou serviços antes de serem enviados para a API, resultando em um aumento no uso de caracteres. Para saber mais, consulte Criar um URL válido.

Uso de parâmetros

O Google Static Maps API é relativamente fácil de usar, pois ele consiste unicamente em um URL com parâmetros. Esta seção explica como usar esses parâmetros para criar seus URLs.

Especificar localizações

O Google Static Maps API deve conseguir identificar precisamente as localizações no mapa, tanto para focalizar o mapa na área correta (usando o parâmetro center) quanto para inserir marcadores opcionais (usando o parâmetro markers) em pontos do mapa. O Google Static Maps API usa números (valores de latitude e longitude) ou strings (endereços) para especificar essas localizações. Esses valores identificam uma localização geocodificada.

Vários parâmetros (como markers e path) incluem várias localizações. Nesses casos, as localizações são separadas pelo caractere de barra vertical (|).

Latitudes e longitudes

Latitudes e longitudes são definidas usando numerais separados por vírgulas em uma string de texto com precisão de até 6 casas decimais. Por exemplo, "40.714728,-73.998672" é um valor geocodificado válido. Precisão além de 6 casas decimais é ignorada.

Valores de longitude são baseados em sua distância do meridiano de Greenwich, Inglaterra. Como Greenwich está situada a uma latitude de 51.477222, podemos inserir um valor 51.477222,0 para center para centralizar o mapa em Greenwich:

Greenwich, Inglaterra

Valores de latitude e longitude devem corresponder a uma localização válida no mundo. Latitudes aceitam qualquer valor entre -90 e 90, enquanto que valores de longitude aceitam qualquer valor entre -180 e 180. Se você especificar valores inválidos para latitude ou longitude, sua solicitação será rejeitada como inválida.

Endereços

A maioria das pessoas não fala de latitudes e longitudes. Elas identificam localizações usando endereços. O processo de transformar um endereço em um ponto geográfico é conhecido como geocodificação e o serviço do Google Static Maps API poderá fazer isso se você fornecer endereços válidos.

Em qualquer parâmetro que comporte uma latitude/longitude, é possível adicionar uma string com um endereço. O Google geocodificará o endereço e fornecerá ao serviço Google Static Maps API um valor de latitude/longitude para inserir marcadores ou especificar localizações. A string deve ter escape de URL. Isso significa que endereços como "Prefeitura, Nova York, NY" devem ser convertidos em "Prefeitura,Nova+York,NY".

Observe que os endereços podem refletir localizações precisas, como nomes de ruas, polilinhas, como rotas nomeadas, ou áreas poligonais, como cidades, países ou parques nacionais. Para resultados polilineares ou poligonais, o servidor do Google Static Maps API usará o ponto central da linha/área como centro do endereço. Em caso de dúvidas sobre como um endereço seria geocodificado, teste o endereço com este utilitário de geocodificação.

O exemplo a seguir gera um Google Static Maps API para Berkeley, CA:

https://maps.googleapis.com/maps/api/staticmap?center=Berkeley,CA&zoom=14&size=400x400&key=YOUR_API_KEY

Berkeley, CA

Níveis de zoom

Os mapas do Google Maps incluem um número inteiro para "nível de zoom", que define a resolução da exibição atual. Níveis de zoom entre 0 (o nível mais baixo, com o qual é possível visualizar o mundo inteiro em um mapa) e 21+ (refinando a exibição para ruas e edifícios individuais) são possíveis na exibição roadmap. Contornos de edifícios, quando disponíveis, são exibidos no mapa aproximadamente no nível de zoom 17. Esse valor varia de acordo com a área e pode mudar ao longo do tempo com a evolução dos dados.

O Google Maps define o nível de zoom como 0 para englobar todo o planeta. Cada nível de zoom subsequente dobra a precisão nas dimensões vertical e horizontal. Para saber mais sobre como isso é feito, consulte a documentação da Google Maps JavaScript API.

Observação: nem todos os níveis de zoom estão disponíveis para todas as localizações. Os níveis de zoom variam de acordo com a localização, pois os dados em partes do mundo podem ser mais granulares do que em outras áreas.

Se você enviar uma solicitação de nível de zoom para o qual nenhum bloco de mapa esteja disponível, o Google Static Maps API retornará um mapa mostrando o nível de zoom máximo disponível na área em questão.

A lista a seguir mostra o nível aproximado de detalhes que você consegue ver em cada nível de zoom:

  • 1: Mundo
  • 5: Terra/continente
  • 10: Cidade
  • 15: Ruas
  • 20: Prédios

O exemplo abaixo solicita dois mapas de Manhattan com o mesmo valor de center, mas com níveis de zoom de 12 e 14, respectivamente:

https://maps.googleapis.com/maps/api/staticmap?center=40.714728,-73.998672&zoom=12&size=400x400&key=YOUR_API_KEY
https://maps.googleapis.com/maps/api/staticmap?center=40.714728,-73.998672&zoom=14&size=400x400&key=YOUR_API_KEY

Manhattan de longe  Manhattan de perto

Tamanhos de imagem

O parâmetro size, em conjunto com center, define a área de cobertura de um mapa. Ele também define o tamanho da saída do mapa em pixels quando multiplicado pelo valor de scale (que é 1, por padrão).

A tabela abaixo mostra os valores máximos permitidos para o parâmetro size em cada valor de scale.

API scale=1 scale=2 scale=4
Livre 640x640 640x640 (retorna 1280x1280 pixels) Não disponível.
Google Maps APIs Premium Plan 2048x2048 1024x1024 (retorna 2048x2048 pixels) 512x512 (retorna 2048x2048 pixels)

O exemplo abaixo solicita uma "fatia" do planeta no equador com o nível de zoom 1:

https://maps.googleapis.com/maps/api/staticmap?center=0,0&zoom=1&size=400x50&key=YOUR_API_KEY

Equador

O exemplo abaixo solicita um pequeno mapa de 100 x 100 pixels centralizado na mesma região. Observe o logotipo do Google menor:

https://maps.googleapis.com/maps/api/staticmap?center=0,0&zoom=1&size=100x100&key=YOUR_API_KEY

Pequeno mapa do equador

Valores de escala

O parâmetro size do Google Static Maps API define o tamanho de um mapa em pixels. Dessa forma, um mapa com o valor size=200x200 será retornado com 200 pixels por 200 pixels. Em um monitor LCD de computador, que geralmente exibe 100 pixels por polegada (ppi), um mapa de 200x200 terá cerca de 2 polegadas em cada dimensão.

Entretanto, dispositivos móveis incluem telas com resoluções cada vez melhores, com densidades de pixel de mais de 300 ppi, o que:

  • Reduz o tamanho de uma imagem de 200x200 pixels para somente 0,7 polegada, tornando rótulos e ícones pequenos demais para serem lidos; ou
  • Aumenta (com o zoom) a imagem para melhorar a legibilidade, resultando em uma imagem distorcida ou pixelada.
Pequena demais Distorcida demais

Ao desenvolver para dispositivos móveis, use o parâmetro scale da API para retornar imagens de mapa com resoluções maiores que solucionem os problemas acima. O valor de scale é multiplicado pelo size para determinar o tamanho real da saída da imagem em pixels, sem alterar a área de cobertura do mapa. O valor padrão de scale é 1. São aceitos valores de 1, 2 e (somente para clientes da Google Maps APIs Premium Plan) 4.

Por exemplo, o valor de scale de 2 retorna a mesma área de cobertura de mapa que uma solicitação sem especificação de scale, mas com duas vezes mais pixels em cada dimensão. Isso inclui estradas e rótulos, para que eles fiquem legíveis em telas pequenas de alta resolução e quando dimensionados pelo navegador.

150x150 150x150&scale=2

Essa imagem também terá um bom desempenho em navegadores de computador quando inseridas em tags img ou div, com a altura e largura definidas usando CSS. O navegador reduzirá a imagem para o tamanho correto sem perder qualidade.

A tabela abaixo mostra três solicitações de imagem diferentes.

  • A primeira é para uma imagem de 100x100 sem valor de scale especificado. Ela é exibida corretamente em computadores, mas é pequena demais para ser lida em dispositivos móveis.
  • A segunda dobra o tamanho do mapa. Em computadores, o CSS a encaixa no elemento img de 100x100 especificado, mas, ao reduzir a imagem, estradas e rótulos ficam muito pequenos. Em dispositivos móveis, a imagem tem o tamanho certo, mas, novamente, estradas e rótulos ficam ilegíveis.
  • A terceira solicitação é para um mapa de 100x100 com scale=2. A imagem é retornada com 200 pixels de detalhes. Em computadores, ela é dimensionada perfeitamente, tornando-se indistinguível da solicitação original de 100x100, enquanto que usuários de dispositivos móveis se beneficiam com a resolução adicional retornada pela API.
Dispositivo 100x100 200x200 100x100&scale=2
Computador
(com height="100px" e
width="100px" na tag
img)
Alta resolução
(simulação)

Dica: plataformas móveis, como Android e iOS, permitem que aplicativos ofereçam suporte a telas de alta resolução especificando imagens separadas para cada resolução. O parâmetro scale facilita a solicitação de uma imagem de mapa para uma tela de resolução padrão e de um mapa correspondente para uma tela de alta resolução. Basta definir scale=1 e scale=2, respectivamente.

Para saber mais sobre como desenvolver para dispositivos móveis e telas de alta resolução, recomendamos a leitura dos seguintes itens:

Formatos de imagem

Imagens podem ser retornadas em diversos formatos comuns de gráficos da web: GIF, JPEG e PNG. O parâmetro format comporta um dos seguintes valores:

  • png8 ou png (padrão) especifica o formato PNG de 8 bits.
  • png32 especifica o formato PNG de 32 bits.
  • gif especifica o formato GIF.
  • jpg especifica o formato de compactação JPEG.
  • jpg-baseline especifica um formato de compactação JPEG não progressivo.

jpg e jpg-baseline normalmente fornecem imagens com o menor tamanho utilizando a compactação "com perda", o que pode degradar a imagem. gif, png8 e png32 fornecem compactação sem perda.

A maioria das imagens JPEG é progressiva, o que significa que elas carregam uma imagem mais difusa inicialmente e refinam a resolução conforme mais dados são obtidos. Isso permite que as imagens sejam carregadas rapidamente em páginas da web e, atualmente, é o uso mais difundido do formato JPEG. Entretanto, alguns usos de JPEG (especialmente para impressão) exigem imagens não progressivas (de linha de base). Nesses casos, pode ser recomendável usar o formato jpg-baseline, que não é progressivo.

Tipos de mapa

O Google Static Maps API cria mapas de diversos formatos, que são listados abaixo:

  • roadmap (padrão) especifica uma imagem de mapa de ruas padrão, que é normalmente mostrada no site do Google Maps. Caso não seja especificado um valor para maptype, o Google Static Maps API fornece blocos de roadmap por padrão.
  • satellite especifica uma imagem de satélite.
  • terrain especifica uma imagem de um mapa físico, mostrando o terreno e a vegetação.
  • hybrid especifica um híbrido da imagem de satélite e de um mapa de estradas, mostrando uma camada transparente com as principais ruas e pontos de referência na imagem de satélite.

Veja a diferença entre os tipos roadmap e terrain no exemplo de código abaixo.

https://maps.googleapis.com/maps/api/staticmap?center=40.714728,-73.998672&zoom=12&size=400x400&maptype=roadmap&key=YOUR_API_KEY
https://maps.googleapis.com/maps/api/staticmap?center=40.714728,-73.998672&zoom=12&size=400x400&maptype=terrain&key=YOUR_API_KEY

Mapa normal de Manhattan  Mapa de terreno de Manhattan

Mapas híbridos usam imagens de satélite e os componentes proeminentes de mapas de ruas para criar um mapa combinado. Os exemplos a seguir mostram mapas do tipo hybrid e satellite:

https://maps.googleapis.com/maps/api/staticmap?center=40.714728,-73.998672&zoom=12&size=400x400&maptype=satellite&key=YOUR_API_KEY
https://maps.googleapis.com/maps/api/staticmap?center=40.714728,-73.998672&zoom=12&size=400x400&maptype=hybrid&key=YOUR_API_KEY

Mapa de satélite de Manhattan  Mapa de terreno de Manhattan

Mapas estilizados

Consulte o guia de mapas estilizados.

Marcadores

O parâmetro markers define um conjunto de um ou mais marcadores em um conjunto de localizações. Cada marcador definido em uma declaração de markers deve ter o mesmo estilo visual. Se quiser exibir marcadores com estilos diferentes, é necessário fornecer parâmetros markers adicionais com informações de estilo separadas.

O parâmetro markers comporta um conjunto de atribuições de valores (descritores de marcadores) no seguinte formato:

markers=markerStyles|markerLocation1| markerLocation2|... etc.

O conjunto de markerStyles é declarado no início da declaração de markers e consiste em zero ou mais descritores separados pelo caractere de barra vertical (|), seguido de um conjunto de uma ou mais localizações separadas pelo caractere de barra vertical (|).

Como as informações de estilo e localização são delimitadas por caracteres de barra vertical, as informações de estilo devem aparecer primeiro em qualquer descritor de marcador. Quando o servidor do Google Static Maps API encontra uma localização no descritor do marcador, presume-se que todos os demais parâmetros do marcador também são localizações.

Estilos de marcadores

O conjunto de descritores de estilo de um marcador é uma série de atribuições de valores separadas pelo caractere de barra vertical (|). Esse descritor de estilo define os atributos visuais a serem usados ao exibir os marcadores no descritor do marcador. Os descritores de estilo contêm as seguintes atribuições de chave/valor:

  • size: (opcional) especifica o tamanho do marcador a partir do conjunto {tiny, mid, small}. Se nenhum parâmetro size for definido, o marcador assumirá o tamanho padrão (normal).
  • color: (opcional) especifica uma cor de 24 bits (exemplo: color=0xFFFFCC) ou uma cor predefinida do conjunto {black, brown, green, purple, yellow, blue, gray, orange, red, white}.

    Observe que transparências (especificadas usando valores de cor hexadecimais de 32 bits) não são permitidas em marcadores, apesar de serem permitidas para caminhos.

  • label: (opcional) especifica um caractere alfanumérico em caixa alta a partir do conjunto {A-Z, 0-9}. (O requisito para caracteres em caixa alta é uma novidade dessa versão da API.) Observe que marcadores de tamanho padrão e mid são os únicos capazes de exibir um parâmetro alphanumeric-character. Marcadores tiny e small não podem exibir um alphanumeric-character.

Observação: em vez de usar esses marcadores, é recomendável usar um ícone personalizado. (Para saber mais, consulte a seção Ícones personalizados abaixo.)

Localizações dos marcadores

Cada descritor de marcador deve conter um conjunto de uma ou mais localizações, definindo em que ponto do mapa inserir o marcador. Essas localizações podem ser especificadas como valores de latitude/longitude ou como endereços. Elas são separadas pelo caractere de barra vertical (|).

Os parâmetros de localização definem em que ponto do mapa inserir o marcador. Se a localização estiver fora do mapa, o marcador não será exibido na imagem criada, desde que os parâmetros center e zoom sejam fornecidos. Entretanto, se esses parâmetros não forem fornecidos, o servidor Google Static Maps API criará automaticamente uma imagem que contenha os marcadores fornecidos. (Consulte a seção Posicionamento implícito abaixo.)

Veja abaixo um exemplo de declaração de marcador. Observe que definimos um conjunto de estilos e três localizações:

https://maps.googleapis.com/maps/api/staticmap?center=Williamsburg,Brooklyn,NY&zoom=13&size=400x400&
markers=color:blue%7Clabel:S%7C11211%7C11206%7C11222&key=YOUR_API_KEY

Três códigos postais do Brooklyn

Para definir marcadores com estilos diferentes, precisamos fornecer parâmetros markers adicionais. Esse conjunto de parâmetros markers define três marcadores: um marcador azul com o rótulo "S" nas coordenadas 62.107733, -145.5419, um pequeno marcador verde em "Delta Junction, AK" e um marcador de tamanho médio com o rótulo "C" em "Tok, AK". Esses marcadores são mostrados no exemplo abaixo:

https://maps.googleapis.com/maps/api/staticmap?center=63.259591,-144.667969&zoom=6&size=400x400\
&markers=color:blue%7Clabel:S%7C62.107733,-145.541936&markers=size:tiny%7Ccolor:green%7CDelta+Junction,AK\
&markers=size:mid%7Ccolor:0xFFFF00%7Clabel:C%7CTok,AK"&key=YOUR_API_KEY

Três cidades do Alaska, diferentes marcadores

Ícones personalizados

Em vez de usar os ícones de marcadores do Google, você pode usar seus ícones personalizados. Ícones personalizados são especificados usando o seguinte descritor no parâmetro markers:

  • icon especifica um URL a ser usado como ícone personalizado do marcador. As imagens podem estar nos formatos PNG, JPEG ou GIF, mas PNG é o formato recomendado.

O parâmetro icon deve ser especificado por um URL (que deve ter codificação de URL). É possível usar URLs criados por serviços de encurtamento de URL como https://goo.gl. A maioria desses serviços oferecem o benefício de codificar URLs automaticamente. Ícones são limitados a tamanhos de 4096 pixels (64x64 para imagens quadradas) e o serviço do Google Static Maps API permite até cinco ícones personalizados distintos por solicitação. Observe que cada ícone pode ser usado diversas vezes no Google Static Maps API.

O ponto de âncora de um ícone personalizado está na parte central inferior da imagem.

O exemplo a seguir usa a Chart API do Google para criar marcadores personalizados, mostrando diversos cafés na cidade de Nova York:

https://maps.googleapis.com/maps/api/staticmap?size=480x480&markers=
icon:https://chart.apis.google.com/chart?chst=d_map_pin_icon%26chld=cafe%257C996600%7C
224+West+20th+Street+NY%7C75+9th+Ave+NY%7C700+E+9th+St+NY&key=YOUR_API_KEY

Cafés em Manhattan

Observação: Os diversos níveis de escape acima podem ser confusos. A Google Chart API usa o caractere de barra vertical (|) para delimitar strings em seus parâmetros de URL. Como este caractere não é legal em um URL (consulte a observação acima, ao criar um URL de gráfico válido, ele é convertido em %7C. Agora, o resultado é incorporado como uma string em uma especificação icon, mas contém um caractere % (de %7C), que não pode ser incluído diretamente em um URL e deve ser convertido para %25. O resultado é que o URL contém %257C, representando dois níveis de codificação. Da mesma forma, o URL do gráfico contém um caractere &, que não pode ser incluído diretamente sem ser confundido como separador de parâmetros de URL do Google Static Maps API, também deve ser codificado.

Veja as etapas para criar o URL do Google Static Maps API:

# Intended chld parameter:
chld=cafe|996600

# Embedded in a fully valid chart URL:
https://chart.apis.google.com/chart?chst=d_map_pin_icon&chld=cafe%7C996600

# Intended icon parameter, containing a fully valid URL:
markers=icon:https://chart.apis.google.com/chart?chst=d_map_pin_icon&chld=cafe%7C996600

# Embedded in a valid and unambiguous Google Static Maps API URL:
...&markers=icon:https://chart.apis.google.com/chart?chst=d_map_pin_icon%26chld=cafe%257C996600

Caminhos do Google Static Maps API

O parâmetro path define um conjunto de uma ou mais localizações conectadas por um caminho para sobrepor na imagem do mapa. O parâmetro path comporta um conjunto de atribuições de valor (descritores de caminho) no seguinte formato:

path=pathStyles|pathLocation1|pathLocation2|... etc.

Observe que os pontos do caminho são separados pelo caractere de barra vertical (|). Como as informações de estilo e ponto são delimitadas por caracteres de barra vertical, as informações de estilo devem aparecer primeiro em qualquer descritor de caminho. Quando o servidor do Google Static Maps API encontra uma localização no descritor do caminho, presume-se que todos os demais parâmetros do caminho também são localizações.

Estilos de caminho

O conjunto de descritores de estilo de um caminho é uma série de atribuições de valores separadas pelo caractere de barra vertical (|). Esse descritor de estilo define os atributos visuais a serem usados ao exibir o caminho. Os descritores de estilo contêm as seguintes atribuições de chave/valor:

  • weight: (opcional) especifica a espessura do caminho em pixels. Se nenhum parâmetro weight for definido, o caminho será exibido com a espessura padrão (5 pixels).
  • color: (opcional) especifica uma cor como valor hexadecimal de 24 bits (exemplo: color=0xFFFFCC) ou 32 bits (exemplo: color=0xFFFFCCFF), ou a partir do conjunto {black, brown, green, purple, yellow, blue, gray, orange, red, white}.

    Quando um valor hexadecimal de 32 bits é especificado, os dois últimos caracteres especificam o valor de transparência alfa de 8 bits. Esse valor varia entre 00 (totalmente transparente) e FF (totalmente opaco). Observe que transparências são permitidas em caminhos, apesar de não serem permitidas para marcadores.

  • fillcolor: (opcional) indica que o caminho marca uma área poligonal e especifica uma cor de preenchimento a ser usada como sobreposição nessa área. O conjunto de localizações subsequente não precisa ser um loop "fechado". O servidor do Google Static Maps API automaticamente une o primeiro e o último pontos. Observe, entretanto, que traçados no exterior da área preenchida não serão fechados, a não ser que você especificamente forneça o mesmo local de início e fim.
  • geodesic: (opcional) indica que o caminho solicitado deve ser interpretado como uma linha geodésica que segue a curvatura do planeta. Quando esse valor é false, o caminho é renderizado como uma linha reta no espaço da tela. O padrão é false.

Veja alguns exemplos de definições de caminhos:

  • Linha azul fina, 50% de opacidade: path=color:0x0000ff80|weight:1
  • Linha vermelha sólida: path=color:0xff0000ff|weight:5
  • Linha branca espessa e sólida: path=color:0xffffffff|weight:10

Esses estilos de caminho são opcionais. Se desejar usar atributos padrão, ignore a definição de atributos de caminho. Nesse caso, o primeiro "argumento" do descritor de caminho será considerado em vez do primeiro ponto declarado (localização).

Pontos de caminho

Para desenhar um caminho, o parâmetro path deve ser passado com dois ou mais pontos. Com isso, o Google Static Maps API conectará o caminho ao longo desses pontos na ordem especificada. Cada pathPoint é denotado no pathDescriptor e separado pelo caractere de barra vertical |.

O exemplo a seguir define um caminho azul com opacidade de 50% da Union Square até a Times Square, em Nova York.

Caminho da Union Square até a Times Square

Veja abaixo os detalhes específicos do parâmetro path:

path=color:0x0000ff|weight:5|40.737102,-73.990318|40.749825,-73.987963|40.752946,-73.987384|40.755823,-73.986397

O exemplo a seguir define o mesmo caminho com uma linha vermelha sólida com 100% de opacidade:

Caminho da Union Square até a Times Square

Veja abaixo os detalhes específicos do parâmetro path:

path=color:0xff0000ff|weight:5|40.737102,-73.990318|40.749825,-73.987963|40.752946,-73.987384|40.755823,-73.986397

O exemplo a seguir define uma área poligonal em Manhattan, passando uma série de interseções como localizações:

Caminho da Union Square até a Times Square

Veja abaixo os detalhes específicos do parâmetro path:

path=color:0x00000000|weight:5|fillcolor:0xFFFF0033|8th+Avenue+%26+34th+St,New+York,NY|\
8th+Avenue+%26+42nd+St,New+York,NY|Park+Ave+%26+42nd+St,New+York,NY,NY|\
Park+Ave+%26+34th+St,New+York,NY,NY

Observe que o caminho em si é invisível e a área poligonal tem uma opacidade de 15%.

Polilinhas codificadas

Em vez de uma série de localizações, você pode declarar um caminho como uma polilinha codificada usando o prefixo enc: na declaração de localização do path. Observe que, se você fornecer um caminho de polilinha codificada para um mapa, não é preciso especificar os parâmetros center e zoom, que normalmente são obrigatórios.

O exemplo a seguir apresenta o caminho da Alaska Highway de Dawson Creek, BC, a Delta Junction, AK, com uma polilinha codificada:

https://maps.googleapis.com/maps/api/staticmap?size=400x400&path=weight:3%7Ccolor:orange%7Cenc:polyline_data&key=YOUR_API_KEY

Alaska Highway

Da mesma forma que com caminhos padrão, caminhos de polilinhas codificadas também podem demarcar áreas poligonais se um argumento fillcolor for passado para o parâmetro path.

O exemplo a seguir apresenta uma área poligonal em Brooklyn, NY:

https://maps.googleapis.com/maps/api/staticmap?size=400x400&path=fillcolor:0xAA000033%7Ccolor:0xFFFFFF00%7C
enc:encoded_data&key=YOUR_API_KEY

Polilinha codificada no Brooklyn

Portas de visualização

Imagens podem especificar uma porta de visualização ao definir localizações visíveis com o parâmetro visible. O parâmetro visible instrui o serviço do Google Static Maps API a criar um mapa mantendo as localizações existentes visíveis. (Esse parâmetro também pode ser combinado a marcadores ou caminhos existentes para definir uma região visível.) Definir uma porta de visualização dessa maneira implica na necessidade de especificar um nível de zoom exato.

O exemplo a seguir solicita um mapa centralizado em Boston, MA, contendo o MIT e a Harvard Square em Cambridge, MA:

https://maps.googleapis.com/maps/api/staticmap?center=Boston,MA
&visible=77+Massachusetts+Ave,Cambridge,MA%7CHarvard+Square,Cambridge,MA&size=512x512&key=YOUR_API_KEY

Mapa de Cambridge

Posicionamento implícito do mapa

Normalmente, é preciso especificar os parâmetros de URL center e zoom para definir a localização e o nível de zoom do mapa gerado. No entanto, se você fornecer parâmetros markers, path ou visible, será possível permitir que o Google Static Maps API determine o centro e o nível de zoom corretos de forma implícita com base em uma avaliação da posição desses elementos.

Se você fornecer dois ou mais elementos, o Google Static Maps API determinará um centro e um nível de zoom apropriados, fornecendo margens generosas para os elementos contidos no mapa. O exemplo a seguir mostra um mapa contendo São Francisco, Oakland e San Jose, CA:

https://maps.googleapis.com/maps/api/staticmap?size=512x512&maptype=roadmap\
&markers=size:mid%7Ccolor:red%7CSan+Francisco,CA%7COakland,CA%7CSan+Jose,CA&key=YOUR_API_KEY

Solução de problemas e suporte

Para saber mais sobre como usar a Google Static Maps API, consulte a página de suporte.

Se algo der errado, a Google Static Maps API poderá emitir um erro ou aviso. Verifique a presença de avisos se perceber que falta algo no mapa. Também é recomendável verificar a presença de avisos antes de lançar um novo aplicativo. Observe que os avisos podem não estar imediatamente aparentes, pois eles são exibidos no cabeçalho HTTP. Para saber mais, consulte o guia de erros e avisos.

A Google Static Maps API anteriormente exigia a inclusão do parâmetro sensor para indicar se o aplicativo usou um sensor para determinar a localização do usuário. Esse parâmetro não é mais obrigatório.

Enviar comentários sobre…

Google Static Maps API
Precisa de ajuda? Acesse nossa página de suporte.