Começar

Introdução

A API Maps Static 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 da API Maps Static é incorporada no atributo src de uma tag <img> ou o elemento equivalente em outras linguagens de programação.

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

Antes de começar

Este documento é destinado a desenvolvedores de sites e dispositivos móveis que querem incluir imagens da API Maps Static em uma página da Web 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.

Antes de começar a desenvolver com a API Maps Static, consulte os requisitos de autenticação (é necessária uma chave de API) e as informações de uso e faturamento da API (é necessário ativar o faturamento no projeto).

Parâmetros de URL

Um URL da API Maps Static precisa ter o seguinte formato:

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

Se o site for acessado por HTTPS, é preciso carregar imagens da API Maps Static em HTTPS para evitar alertas de segurança de navegadores. O HTTPS também é recomendado se as solicitações incluírem informações sensíveis do usuário, como a localização:

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

Independentemente de usar HTTP ou HTTPS, alguns parâmetros de URL 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 neste documento.

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

Parâmetros de localização

  • center (obrigatório se não houver marcadores) define o centro do mapa, equidistante de todas as bordas. Esse parâmetro comporta uma localização como um par {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 mais informações, consulte Locais.
  • zoom (obrigatório se não houver marcadores) define o nível de zoom do mapa, o que determina o nível de expansão do mapa. O parâmetro aceita um valor numérico correspondente ao nível de zoom da região desejada. Para mais informações, consulte Níveis de zoom.

Parâmetros do mapa

  • size (obrigatório) define as dimensões retangulares da imagem do mapa. Esse parâmetro usa 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 de largura vão mostrar um logotipo do Google de tamanho reduzido. Esse parâmetro é afetado pelo parâmetro scale. O tamanho da saída final é o produto dos valores de tamanho e escala.
  • scale (opcional) afeta o número de pixels que são retornados. scale=2 retorna o dobro de 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. O valor padrão é 1. Os valores aceitos são 1 e 2. Consulte Valores de escala para mais informações.
  • format (opcional) define o formato da imagem resultante. Por padrão, a API Maps Static cria imagens PNG. Existem vários formatos possíveis, incluindo tipos GIF, JPEG e PNG. O formato usado depende de como você pretende apresentar a imagem. O JPEG geralmente oferece mais compactação, enquanto GIF e PNG oferecem mais detalhes. Para mais informações, consulte Formatos de imagem.
  • maptype (opcional) define o tipo de mapa a ser criado. Há vários valores de tipo de mapa possíveis, incluindo roadmap, satellite, hybrid e terrain. Para mais informações, consulte Maptypes da API Maps Static.
  • language (opcional) define o idioma usado para mostrar os rótulos nos blocos de mapa. 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. Consulte os detalhes da cobertura da Plataforma Google Maps para conferir as regiões com suporte.

Parâmetros de recursos

  • map_id (opcional) especifica o identificador de um mapa específico. O ID do mapa associa um mapa a um estilo ou recurso específico e precisa pertencer ao mesmo projeto da chave de API usada para inicializar o mapa. Para mais informações, consulte Como usar IDs de mapa.
  • markers (opcional) define um ou mais marcadores para anexar à imagem em locais especificados. Esse parâmetro aceita uma definição de marcador único 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. 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 mais informações, consulte Marcadores da API Maps Static.
  • 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 (|) ou uma polilinha codificada usando o prefixo enc: na declaração de local do caminho. Você pode fornecer caminhos adicionais adicionando parâmetros path adicionais. 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 mais informações, consulte Caminhos da API Maps Static.
  • visible (opcional) especifica um ou mais locais que devem permanecer visíveis no mapa, embora marcadores ou outros indicadores não sejam exibidos. Use esse parâmetro para garantir que determinados recursos ou localizações do mapa sejam mostrados na API Maps Static.
  • style (opcional) define um estilo personalizado para alterar a apresentação de um recurso específico (estradas, parques e outros recursos) do mapa. Esse parâmetro aceita argumentos feature e element que identificam os recursos a serem estilizados e um conjunto de operações de estilo a serem aplicadas aos recursos selecionados. Você pode fornecer vários estilos adicionando mais parâmetros style. Para mais informações, consulte o guia de mapas estilizados.

Parâmetros de chave e assinatura

  • key (obrigatório) permite monitorar o uso da API do seu aplicativo no console do Google Cloud e garante que o Google possa entrar em contato com você sobre seu aplicativo, se necessário. Para saber mais, consulte Usar chaves de API com a API Maps Static.
  • signature (recomendado) é uma assinatura digital usada para verificar se qualquer site que gera solicitações usando sua chave de API tem autorização para fazer isso. As solicitações sem uma assinatura digital podem falhar. Para mais informações, consulte Usar uma assinatura digital.

Restrição de tamanho de URL

Os URLs da API Maps Static têm um limite de 16.384 caracteres. Na prática, você provavelmente não vai precisar de URLs maiores do que isso, a não ser que produza mapas complicados com um grande número de marcadores e caminhos.

Uso de parâmetros

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

Especificar localizações

A API Maps Static precisa identificar com precisão os locais no mapa para focar o mapa no local correto (usando o parâmetro center) e/ou colocar marcadores opcionais (usando o parâmetro markers) em pontos do mapa. A API Maps Static usa números (valores de latitude e longitude) ou strings (endereços) para especificar esses locais. 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 em uma string de texto separada por vírgulas com precisão de até 6 casas decimais. Por exemplo, "40.714728,-73.998672" é um valor de geocodificação válido. A precisão além de seis casas decimais é ignorada.

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

Greenwich, Inglaterra

Valores de latitude e longitude precisam corresponder a uma localização válida no mundo. Latitudes aceitam qualquer valor entre -90 e 90, enquanto 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 addresses. O processo de transformar um endereço em um ponto geográfico é conhecido como geocodificação, e o serviço da API Maps Static pode 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 da API Maps Static um valor de latitude/longitude para inserir marcadores ou especificar localizações. A string precisa ser codificada em URL. Por exemplo, endereços como "Prefeitura, Nova York, NY" precisam ser convertidos em "Prefeitura,Nova+York,NY".

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 da API Maps Static vai 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 uma imagem de mapa estática para Berkeley, CA:

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

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 visualização roadmap padrão. 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 abranger toda a Terra. Cada nível de zoom subsequente dobra a precisão nas dimensões horizontal e vertical. Para saber mais sobre como isso é feito, consulte a documentação da API Maps JavaScript.

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 em que não há blocos de mapa, a API Maps Static vai retornar uma imagem em branco.

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

  • 1: Mundo
  • 5: terra/continente
  • 10: cidade
  • 15: ruas
  • 20: construções

Este exemplo 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&signature=YOUR_SIGNATURE
https://maps.googleapis.com/maps/api/staticmap?center=40.714728,-73.998672&zoom=14&size=400x400&key=YOUR_API_KEY&signature=YOUR_SIGNATURE

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).

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

scale=1 scale=2
640x640 640x640 (retorna 1280x1280 pixels)

Este exemplo 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&signature=YOUR_SIGNATURE

Linha do Equador

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

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

Pequeno mapa do equador

Valores de escala

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

No entanto, os dispositivos móveis incluem cada vez mais telas de alta resolução 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.
Muito pequeno 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. Os valores aceitos são 1 e 2.

Por exemplo, o valor de escala 2 retorna a mesma área de cobertura de mapa que uma solicitação sem especificação de escala, mas com o dobro de 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 uma tag img ou div com a altura e largura definidas usando CSS. O navegador vai reduzir a imagem para o tamanho correto, sem perder qualidade.

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

  • A primeira é para uma imagem de 100x100 sem valor de scale especificado. Ela aparece corretamente no computador, mas é pequena demais para ser lida em um dispositivo móvel.
  • 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.
Solicitações de imagem
Dispositivo 100x100 200x200 100x100&scale=2
Computador
(com height="100px" e
width="100px" na tag
img)
Alta resolução
(simulação)

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

As imagens podem ser retornadas em vários formatos comuns de gráficos da Web: GIF, JPEG e PNG. O parâmetro format usa 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.

Estes exemplos solicitam mapas nos formatos gif e png:

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

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

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 recebidos. Isso permite que as imagens sejam carregadas rapidamente em páginas da Web e é o uso mais difundido do JPEG atualmente. No entanto, alguns usos de JPEG 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

A API Maps Static cria mapas em vários formatos, listados abaixo:

  • roadmap (padrão) especifica uma imagem de mapa de ruas padrão, que é normalmente mostrada no site do Google Maps. Se nenhum valor de maptype for especificado, a API Maps Static vai exibir blocos 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 ruas, mostrando uma camada transparente com as principais ruas e pontos de referência na imagem de satélite.

Confira a diferença entre os tipos de roadmap e terrain neste exemplo de código.

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

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 os tipos de mapa híbrido e de satélite:

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

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

Mapas estilizados

Personalize a apresentação do mapa padrão do Google aplicando seus próprios estilos. Consulte o guia de mapas estilizados.

Marcadores

O parâmetro markers define um conjunto de um ou mais marcadores (pinos do mapa) em um conjunto de localizações. Cada marcador definido em uma declaração de markers precisa ter o mesmo estilo visual. Se quiser exibir marcadores com estilos diferentes, forneça vários parâmetros markers com informações de estilo separadas.

O parâmetro markers comporta um conjunto de atribuições de valor (descritores de marcador) 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 de estilo separados pelo caractere de barra vertical (|), seguido por um conjunto de um ou mais locais também separados 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 precisam aparecer primeiro em qualquer descritor de marcador. Quando o servidor da API Maps Static encontra um local no descritor do marcador, presume-se que todos os outros parâmetros do marcador também são locais.

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 de marcador. Esses descritores de estilo contêm as seguintes atribuições de chave/valor:

  • size: (opcional) especifica o tamanho do marcador do conjunto {tiny, mid, small}. Se nenhum parâmetro size for definido, o marcador vai aparecer no tamanho padrão (normal).

  • color: (opcional) especifica uma cor de 24 bits (por 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 único caractere alfanumérico em maiúsculas do conjunto {A-Z, 0-9}. (O requisito para caracteres em caixa alta é uma novidade dessa versão da API.) Os marcadores de tamanho padrão e mid são os únicos que podem mostrar um parâmetro alphanumeric-character. Os marcadores tiny e small não podem mostrar um caractere alfanumérico.

Dimensionamento do marcador

O valor scale é multiplicado pelo tamanho da imagem do marcador para produzir o tamanho real da saída do marcador em pixels. O valor padrão da escala é 1. Os valores aceitos são 1, 2 e 4.

O limite de tamanho de pixel em imagens é aplicado depois da aplicação da escala. Por exemplo, se o marcador for definido como scale:2, ele poderá ser maior que o tamanho máximo de 4.096 pixels, desde que seja reduzido para menos de 4.096 pixels após a escala. Use a escala de marcadores com a escala do mapa ao mostrar mapas de resolução mais alta.

Localizações dos marcadores

Cada descritor de marcador precisa conter um conjunto de uma ou mais localizações que definem onde colocar o marcador no mapa. Esses locais podem ser especificados como valores de latitude/longitude ou como addresses. Elas são separadas pelo caractere de barra vertical (|).

Observação: se você especificar os locais dos marcadores usando um método que exija geocodificação, como strings de endereço legíveis ou polilinhas, a solicitação será limitada a um máximo de 15 marcadores. Esse limite se aplica apenas aos locais de marcadores que exigem geocodificação. Ele não se aplica a locais de marcadores especificados com coordenadas de latitude/longitude.

Os parâmetros de localização definem o local do marcador no mapa. 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. No entanto, se esses parâmetros não forem fornecidos, o servidor da API Maps Static vai criar automaticamente uma imagem que contém os marcadores fornecidos. Consulte Posicionamento implícito.

Confira um exemplo de declaração de marcador. 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&signature=YOUR_SIGNATURE

Três códigos postais do Brooklyn

Para definir marcadores com estilos diferentes, precisamos fornecer vários parâmetros markers. 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 marcador verde pequeno em "Delta Junction, AK" e um marcador amarelo de tamanho médio com o rótulo "C" em "Tok, AK". Esses marcadores são mostrados neste exemplo:

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&signature=YOUR_SIGNATURE

Três cidades do Alaska, diferentes marcadores

Ícones personalizados

Em vez de usar os ícones de marcadores do Google, você pode usar seus próprios ícones personalizados. Os ícones personalizados são especificados usando o descritor icon no parâmetro markers. Exemplo:

markers=icon:URLofIcon|markerLocation

Especifique o icon usando um URL (que precisa ser codificado em URL). É possível usar URLs criados por serviços de encurtamento de URL, como https://goo.gl. A maioria desses serviços oferece o benefício de codificar URLs automaticamente.

Você pode especificar um ponto de ancoragem para o ícone personalizado. O ponto de âncora define como o ícone é colocado em relação aos locais markers especificados. Por padrão, o ponto de âncora de um ícone personalizado é o centro inferior da imagem do ícone. É possível especificar um ponto de ancoragem diferente usando o descritor anchor em conjunto com o icon. Defina anchor como um ponto x,y do ícone (como 10,5) ou como um alinhamento predefinido usando um destes valores: top, bottom, left, right, center, topleft, topright, bottomleft ou bottomright. Exemplo:

markers=anchor:bottomright|icon:URLofIcon|markerLocation1|markerLocation2

É possível usar até cinco ícones personalizados diferentes por solicitação. Essa limitação não significa que você está limitado a apenas cinco locais marcados no mapa. Cada ícone exclusivo pode ser usado com mais de um local markers no mapa.

Formato do ícone:

  • As imagens de ícones podem estar nos formatos PNG, JPEG ou GIF, mas PNG é o formato recomendado.
  • Os ícones podem ter até 4.096 pixels (64 x 64 para imagens quadradas).
Exemplos de ícones personalizados

O Exemplo 1 cria ícones personalizados e os posiciona usando âncoras.

https://maps.googleapis.com/maps/api/staticmap?&size=600x400&style=visibility:on
&style=feature:water%7Celement:geometry%7Cvisibility:on
&style=feature:landscape%7Celement:geometry%7Cvisibility:on
&markers=anchor:32,10%7Cicon:https://goo.gl/5y3S82%7CCanberra+ACT
&markers=anchor:topleft%7Cicon:http://tinyurl.com/jrhlvu6%7CMelbourne+VIC
&markers=anchor:topright%7Cicon:https://goo.gl/1oTJ9Y%7CSydney+NSW&key=YOUR_API_KEY
&signature=YOUR_SIGNATURE

Três cidades australianas, ícones personalizados diferentes posicionados com âncoras.

O exemplo 2 cria os mesmos ícones personalizados do exemplo 1, mas não define as posições dos ícones usando âncoras, dependendo da âncora padrão de centro inferior.

https://maps.googleapis.com/maps/api/staticmap?&size=600x400&style=visibility:on
&style=feature:water%7Celement:geometry%7Cvisibility:on
&style=feature:landscape%7Celement:geometry%7Cvisibility:on
&markers=icon:https://goo.gl/5y3S82%7CCanberra+ACT
&markers=icon:http://tinyurl.com/jrhlvu6%7CMelbourne+VIC
&markers=icon:https://goo.gl/1oTJ9Y%7CSydney+NSW&key=YOUR_API_KEY&signature=YOUR_SIGNATURE

Três cidades australianas, ícones personalizados diferentes com posicionamento padrão.

Caminhos da API Maps Static

O parâmetro path define um conjunto de um ou mais locais conectados 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.

Os pontos do caminho são separados pelo caractere de barra vertical (|). Como as informações de estilo e de ponto são delimitadas por caracteres de barra vertical, as informações de estilo precisam aparecer primeiro em qualquer descritor de caminho. Quando o servidor da API Maps Static encontra uma localização no descritor do caminho, presume-se que todos os outros 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. Esses 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 vai aparecer 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 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 (completamente transparente) e FF (completamente 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 a 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 da API Maps Static une automaticamente o primeiro e o último pontos. No entanto, qualquer traço no exterior da área preenchida não será fechado, a menos que você forneça especificamente o mesmo local de início e fim.
  • geodesic: (opcional) indica que o caminho solicitado precisa ser interpretado como uma linha geodésica que segue a curvatura da Terra. Quando esse valor é false, o caminho é renderizado como uma linha reta no espaço da tela. O padrão é "false".

Confira alguns exemplos de definições de caminho:

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

Esses estilos de caminho são opcionais. Se quiser 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 também precisa ser transmitido com dois ou mais pontos. A API Maps Static vai conectar o caminho ao longo desses pontos na ordem especificada. Cada pathPoint é denotado no pathDescriptor 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

Os detalhes do parâmetro path são:

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

Os detalhes específicos desse parâmetro path são:

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

O próximo exemplo define uma área poligonal em Manhattan, transmitindo uma série de interseções como locais:

Caminho da Union Square até a Times Square

Os detalhes específicos desse parâmetro path são:

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

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

Polilinhas codificadas

Em vez de uma série de locais, você pode declarar um caminho como uma polilinha codificada usando o prefixo enc: na declaração de local do path.

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

https://maps.googleapis.com/maps/api/staticmap
?size=400x400&center=59.900503,-135.478011&zoom=4
&path=weight:3%7Ccolor:orange%7Cenc:_fisIp~u%7CU%7D%7Ca@pytA_~b@hhCyhS~hResU%7C%7Cx@oig@rwg@amUfbjA%7Df%5BroaAynd@%7CvXxiAt%7BZwdUfbjAewYrqGchH~vXkqnAria@c_o@inc@k%7Bg@i%60%5Do%7CF%7DvXaj%5Ch%60%5Dovs@?yi_@rcAgtO%7Cj_AyaJren@nzQrst@zuYh%60%5Dv%7CGbldEuzd@%7C%7Cx@spD%7CtrAzwP%7Cd_@yiB~vXmlWhdPez%5C_%7BKm_%60@~re@ew%5ErcAeu_@zhyByjPrst@ttGren@aeNhoFemKrvdAuvVidPwbVr~j@or@f_z@ftHr%7BZlwBrvdAmtHrmT%7BrOt%7BZz%7DE%7Cc%7C@o%7CLpn~AgfRpxqBfoVz_iAocAhrVjr@rh~@jzKhjp@%60%60NrfQpcHrb%5Ek%7CDh_z@nwB%7Ckb@a%7BR%7Cyh@uyZ%7CllByuZpzw@wbd@rh~@%7C%7CFhqs@teTztrAupHhyY%7Dt%5Dhuf@e%7CFria@o%7DGfezAkdW%7C%7D%5BocMt_Neq@ren@e~Ika@pgE%7Ci%7CAfiQ%7C%60l@uoJrvdAgq@fppAsjGhg%60@%7ChQpg%7BAi_V%7C%7Cx@mkHhyYsdP%7CxeA~gF%7C%7D%5Bmv%60@t_NitSfjp@c%7DMhg%60@sbChyYq%7De@rwg@atFff%7D@ghN~zKybk@fl%7DA%7DcPftcAite@tmT__Lha@u~DrfQi%7DMhkSqyWivIumCria@ciO_tHifm@fl%7DA%7Brc@fbjAqvg@rrqAcjCf%7Ci@mqJtb%5Es%7C@fbjA%7BwDfs%60BmvEfqs@umWt_Nwn%5Epen@qiBr%60xAcvMr%7BZidg@dtjDkbM%7Cd_@
&key=YOUR_API_KEY&signature=YOUR_SIGNATURE

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 transmitido 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&center=40.653279,-73.959816&zoom=11
&path=fillcolor:0xAA000033%7Ccolor:0xFFFFFF00%7Cenc:%7DzswFtikbMjJzZ%7CRdPfZ%7DDxWvBjWpF~IvJnEvBrMvIvUpGtQpFhOQdKpz%40bIx%7BA%7CPfYlvApz%40bl%40tcAdTpGpVwQtX%7Di%40%7CGen%40lCeAda%40bjA%60q%40v%7D%40rfAbjA%7CEwBpbAd_%40he%40hDbu%40uIzWcWtZoTdImTdIwu%40tDaOXw_%40fc%40st%40~VgQ%7C%5BuPzNtA%60LlEvHiYyLs%5EnPhCpG%7DSzCNwHpz%40cEvXg%40bWdG%60%5DlL~MdTmEnCwJ%5BiJhOae%40nCm%5B%60Aq%5DqE_pAaNiyBuDurAuB%7D%7DAy%60%40%7CEKv_%40%3F%7C%5BqGji%40lAhYyH%60%40Xiw%40tBerAs%40q%5DjHohAYkSmW%3FaNoaAbR%7DLnPqNtMtIbRyRuDef%40eT_z%40mW_Nm%7CB~j%40zC~hAyUyJ_U%7BZ%3F%3FcPvg%40%7Ds%40sHsc%40_z%40cj%40kp%40YePoNyYyb%40_iAyb%40gBw%5EbOokArcA%7DGwJuzBre%40i%5Ctf%40sZnd%40oElb%40hStW%7B%5Dvv%40%3F%3Fkz%40~vAcj%40zKa%60Atf%40uQj_Aee%40pU_UrcA
&key=YOUR_API_KEY&signature=YOUR_SIGNATURE

Polilinha codificada no Brooklyn com assinatura

Janelas de visualização

As imagens podem especificar uma porta de visualização ao definir localizações visíveis usando o parâmetro visible. O parâmetro visible instruí o serviço da API Maps Static a criar um mapa para que os locais existentes permaneçam 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 próximo exemplo 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&signature=YOUR_SIGNATURE

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 a API Maps Static 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, a API Maps Static vai determinar um centro e um nível de zoom apropriados, fornecendo margens generosas para os elementos contidos no mapa. Este exemplo 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&signature=YOUR_SIGNATURE

Roteiro

Tamanhos de imagem maiores

Se você precisar de imagens com tamanhos maiores que 640 x 640 pixels (ou 1.280 x 1.280 pixels com um valor de escala de 2), entre em contato com a equipe de suporte e forneça as seguintes informações:

  1. Seu caso de uso e por que você precisa de imagens grandes.
  2. Se você considerou usar outras APIs da Plataforma Google Maps (API Maps JavaScript, API Maps Embed, SDK do Maps para Android ou SDK do Maps para iOS) e por que elas não atendem às suas necessidades.
  3. Capturas de tela, modelos ou amostras de como você vai usar imagens de tamanho grande.
  4. Seu uso mensal estimado de imagens grandes.

Vamos analisar sua solicitação com base nas informações fornecidas e determinar se o caso de uso está em conformidade com os Termos de Serviço da Plataforma Google Maps.

O tamanho máximo que podemos fornecer é de 2048 x 2048 pixels.

Solução de problemas e suporte

Para mais informações sobre como usar a API Maps Static, consulte a página de suporte.

A API Maps Static pode emitir um erro ou aviso quando algo dá errado. 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. Os avisos podem não estar imediatamente aparentes, porque eles são exibidos no cabeçalho HTTP. Para mais informações, consulte o guia de erros e avisos.