Comece agora

Introdução

A API Maps Static retorna uma imagem (GIF, PNG ou JPEG) em resposta a uma solicitação HTTP via URL. Para cada solicitação, você pode especificar o local e o tamanho da imagem, o nível de zoom, o tipo de mapa e o posicionamento de marcadores opcionais em locais do mapa. Além disso, você pode rotular seus marcadores com caracteres alfanuméricos.

Uma imagem da API Maps Static é incorporada ao atributo src de uma tag <img> ou o equivalente em outras linguagens de programação.

Neste documento, descrevemos o formato necessário dos URLs da API Maps Static e os parâmetros disponíveis. Ele também apresenta algumas dicas e truques para especificar os 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 app para dispositivos móveis. Ele fornece uma introdução ao uso da API e material 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 (você precisa de uma chave de API) e as informações de uso e faturamento da API (é necessário ativar o faturamento no seu projeto).

Parâmetros de URL

O 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, carregue também as imagens da API Maps Static por HTTPS para evitar alertas de segurança do navegador. O HTTPS também é recomendado quando as solicitações incluem informações confidenciais do usuário, como a localização:

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

Seja com 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 valores possíveis estão enumerados neste documento.

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

Parâmetros de local

  • center (obrigatório se não houver marcadores) define o centro do mapa, equidistante de todas as bordas dele. Esse parâmetro usa um local como um par de {latitude,longitude} separado por vírgula (por exemplo, "40.714728,-73.998672") ou um endereço de string (por exemplo, "city hall, nova york, ny") que identifica um local exclusivo na face da Terra. 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 ampliação do mapa. Esse parâmetro usa 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 de mapa. Esse parâmetro usa uma string do formulário {horizontal_value}x{vertical_value}. Por exemplo, 500x400 define um mapa com 500 pixels de largura por 400 pixels de altura. Mapas com menos de 180 pixels exibem 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 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. 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. Há vários formatos possíveis, incluindo GIF, JPEG e PNG. O formato usado depende de como você pretende apresentar a imagem. JPEG normalmente 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 construído. Há vários valores de tipo de mapa possíveis, incluindo roadmap, satellite, hybrid e terrain. Para mais informações, consulte os Tipos de mapa da API Maps Static.
  • language (opcional) define o idioma usado para a exibição de rótulos nos blocos do mapa. Esse parâmetro só é compatível com alguns blocos de países. Se o idioma específico solicitado não for compatível com o conjunto de blocos, o idioma padrão será usado.
  • region (opcional) define as bordas apropriadas a serem exibidas, com base em particularidades geopolíticas. Aceita um código regional especificado como um valor ccTLD ("domínio de nível superior") de dois caracteres. Consulte os detalhes de cobertura da Plataforma Google Maps para saber quais são as regiões disponíveis.

Parâmetros de recurso

  • map_id (opcional) especifica o identificador de um mapa específico. Esse ID associa um mapa a um estilo ou recurso específico e precisa pertencer ao mesmo projeto que a chave de API usada para inicializar o mapa. Para mais informações, consulte Usar IDs de mapa.
  • markers (opcional) define um ou mais marcadores para anexar à imagem em locais especificados. Esse parâmetro usa uma única definição de marcador com parâmetros separados pelo caractere de barra vertical (|). Vários marcadores podem ser colocados no mesmo parâmetro markers, desde que exibam o mesmo estilo. Você pode incluir outros marcadores de estilos diferentes adicionando outros parâmetros markers. Quando você fornece marcadores para um mapa, não é necessário 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 único caminho com dois ou mais pontos conectados que serão sobrepostos na imagem nos locais especificados. Esse parâmetro usa uma string de definições de ponto separadas pelo caractere de barra vertical (|) ou uma polilinha codificada que usa o prefixo enc: na declaração de localização do caminho. Você pode fornecer outros caminhos adicionando outros parâmetros path. Se você fornecer um caminho para um mapa, não será necessário 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 precisam permanecer visíveis no mapa, embora nenhum marcador ou outros indicadores sejam exibidos. Use esse parâmetro para garantir que determinados recursos ou locais do mapa sejam exibidos na API Maps Static.
  • style (opcional) define um estilo personalizado para alterar a apresentação de um recurso específico (estradas, parques e outros elementos) do mapa. Esse parâmetro usa 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 outros parâmetros style. Para mais informações, consulte o guia sobre mapas estilizados.

Parâmetros de chave e assinatura

  • key (obrigatório) permite que você monitore o uso da API do seu aplicativo no Console do Google Cloud e garante que o Google possa entrar em contato com você sobre o aplicativo, se necessário. Para mais informações, consulte Usar chaves de API com a API Maps Static.
  • signature (recomendado) é uma assinatura digital usada para verificar se os sites que gerarem solicitações usando sua chave de API têm 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 para URLs

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

Uso de parâmetros

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

Especificar localizações

A API Maps Static precisa identificar locais com precisão no mapa, seja para focalizar o local correto (usando o parâmetro center) e/ou para inserir marcadores opcionais (usando o parâmetro markers) em locais 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 um local geocodificado.

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

Latitudes e longitudes

Latitudes e longitudes são definidas usando numerais dentro de uma string de texto separada por vírgulas com precisão de até seis casas decimais. Por exemplo, "40.714728,-73.998672" é um valor de geocódigo válido. A precisão além das seis casas decimais é ignorada.

Os valores de longitude são baseados na distância do ponto até Greenwich, Inglaterra, onde fica o meridiano principal. Como Greenwich está localizada na latitude 51.477222, podemos inserir o valor center de 51.477222,0 para centralizar o mapa em Greenwich:

Greenwich, Inglaterra

Os valores de latitude e longitude precisam corresponder a um local válido na Terra. As latitudes podem assumir qualquer valor entre -90 e 90, enquanto os valores de longitude podem assumir qualquer valor entre -180 e 180. Se você especificar um valor de latitude ou longitude inválido, sua solicitação será rejeitada como inválida.

Endereços

A maioria das pessoas não fala em latitudes e longitudes. Elas indicam locais usando endereços. O processo de transformar um endereço em um ponto geográfico é conhecido como geocodificação, e o serviço da API Maps Static vai fazer a geocodificação se você informar endereços válidos.

Em qualquer parâmetro em que seja possível fornecer uma latitude/longitude, é possível especificar uma string indicando um endereço. O Google geocodifica o endereço e fornece ao serviço da API Maps Static um valor de latitude/longitude para inserir marcadores ou especificar locais. A string precisa ser codificada por URL. Assim, endereços como "Prefeitura, Nova York, NY" precisam ser convertidos em "City+Hall,New+York,NY", por exemplo.

Os endereços podem refletir locais precisos, como endereços, polilinhas, como trajetos nomeados, ou áreas poligonais, como cidades, países ou parques nacionais. Para resultados polilineares e poligonais, o servidor da API Maps Static usará o ponto central da linha/área como o centro do endereço. Se você tiver dúvidas sobre a geocodificação de um endereço, faça um teste usando 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 têm um "nível de zoom" inteiro que define a resolução da visualização atual. Níveis de zoom entre 0 (o mais baixo, em que todo o mundo pode ser visto em um só mapa) e 21+ (para ruas e edifícios individuais) são possíveis dentro da visualização padrão de roadmap. Os contornos de construções, quando disponíveis, aparecem no mapa próximo ao nível de zoom 17. Esse valor varia de acordo com a área e pode mudar com o tempo, conforme os dados evoluem.

O Google Maps define o nível de zoom como 0 para abranger toda a Terra. Cada nível de zoom sucessivo dobra a precisão nas dimensões horizontal e vertical. Mais informações sobre como fazer isso estão disponíveis na documentação da API Google 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 dependendo da localização, já que os dados em algumas partes do globo são mais granulares do que em outros locais.

Se você enviar uma solicitação de nível de zoom sem blocos de mapa, a API Maps Static vai retornar uma imagem em branco.

A lista a seguir mostra o nível aproximado de detalhamento 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, junto com center, define a área de cobertura de um mapa. Ela 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 scale.

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

Este exemplo solicita uma "fatia" do planeta no equador, no 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 mapa pequeno, de tamanho 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&signature=YOUR_SIGNATURE

Pequeno mapa do equador

Dimensionar valores

O parâmetro size da API Maps Static define o tamanho de um mapa em pixels. Assim, um mapa com size=200x200 retorna com 200 pixels por 200 pixels. Em um monitor LCD, que normalmente exibe cerca de 100 pixels por polegada (ppi), um mapa de 200 x 200 tem 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 acima de 300 ppi, o que:

  • reduzir o tamanho de uma imagem de 200 x 200 pixels para apenas 0,7 polegada, renderizando rótulos e ícones muito pequenos para serem lidos; ou
  • Ajuste a escala (zoom) da imagem para melhorar a legibilidade, resultando em uma imagem distorcida ou pixelada.
Muito pequeno Distorcida demais

No desenvolvimento para dispositivos móveis, você pode usar o parâmetro scale da API para retornar imagens de mapa em alta resolução que resolvam os problemas acima. O valor de scale é multiplicado por size para determinar o tamanho real da saída da imagem em pixels, sem mudar a área de cobertura do mapa. O valor padrão de scale é 1. Os valores aceitos são 1 e 2.

Por exemplo, um valor de escalonamento 2 retorna a mesma área de cobertura de mapa que uma solicitação sem escala especificada, mas com o dobro de pixels em cada dimensão. Isso inclui vias e rótulos para que sejam legíveis em telas pequenas e de alta resolução, assim como quando dimensionados pelo navegador.

150x150 150x150&scale=2

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

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

  • A primeira é para uma imagem de 100x100 sem valor de scale especificado. Ele é exibido corretamente na área de trabalho, mas é muito pequeno para ser lido em um dispositivo móvel.
  • A segunda dobra o tamanho do mapa. No computador, o CSS o encaixa no elemento img de 100 x 100 especificado, mas, ao reduzir a imagem, as vias e os rótulos ficam muito pequenos. Em dispositivos móveis, a imagem tem o tamanho correto, mas, novamente, as vias e os rótulos ficam ilegíveis.
  • A terceira solicitação é para um mapa de 100 x 100 com scale=2. A imagem é retornada com 200 pixels de detalhes. O computador reduz a escala perfeitamente, de modo que seja indistinguível da solicitação original de 100 x 100, enquanto o navegador para dispositivos móveis se beneficia da 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 mais informações sobre o desenvolvimento para dispositivos móveis e telas de alta resolução, recomendamos a seguinte leitura:

Formatos de imagem

As imagens podem ser retornadas em vários formatos gráficos comuns 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 (link em inglês).
  • jpg-baseline especifica um formato de compactação JPEG não progressivo.

Estes exemplos de solicitação de 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 o menor tamanho de imagem, mas fazem isso por meio de um método de compactação com "perda", que pode degradar a imagem. gif, png8 e png32 fornecem compactação sem perdas.

A maioria das imagens JPEG é progressiva, o que significa que elas carregam uma imagem mais aproximada com antecedência e refinam a resolução à medida que mais dados chegam. Isso permite que as imagens sejam carregadas rapidamente em páginas da Web e é o uso mais difundido de JPEG no momento. No entanto, alguns usos de JPEG exigem imagens não progressivas (de referência). Nesses casos, convém 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 roteiro padrão, como normalmente aparece no site do Google Maps. Se nenhum valor de maptype for especificado, a API Maps Static exibirá blocos roadmap por padrão.
  • satellite especifica uma imagem de satélite.
  • terrain especifica uma imagem de mapa de relevo físico, mostrando terreno e vegetação.
  • hybrid especifica um híbrido da imagem de satélite e de um roteiro, mostrando uma camada transparente das principais ruas e nomes de lugares na imagem de satélite.

Neste exemplo de código, é possível ver a diferença entre os tipos de mapa e terreno.

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

Os mapas híbridos usam imagens de satélite e recursos de roteiro em destaque para criar um mapa combinado. Os exemplos a seguir mostram os tipos de mapa de satélite e híbridos:

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 sobre mapas estilizados.

Marcadores

O parâmetro markers define um conjunto de um ou mais marcadores (fixos no mapa) em um conjunto de locais. Cada marcador definido em uma única declaração markers precisa exibir o mesmo estilo visual. Para exibir marcadores com estilos diferentes, forneça vários parâmetros markers com informações de estilo separadas.

O parâmetro markers usa 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 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 de localização são delimitadas por um caractere de barra vertical, elas precisam aparecer primeiro em qualquer descritor de marcador. Quando o servidor da API Maps Static encontra um local no descritor do marcador, todos os outros parâmetros dele também são considerados locais.

Estilos de marcadores

O conjunto de descritores de estilo de marcador é uma série de atribuições de valores separadas pelo caractere de barra vertical (|). Ele define os atributos visuais que serão usados ao mostrar os marcadores nesse descritor. Esses descritores de estilo contêm as seguintes atribuições de chave-valor:

  • size: (opcional) especifica o tamanho do marcador com base no conjunto {tiny, mid, small}. Se nenhum parâmetro size for definido, o marcador será mostrado com 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}.

    As transparências (especificadas usando valores de cor hexadecimais de 32 bits) não são permitidas em marcadores, embora sejam permitidas para caminhos.

  • label: (opcional) especifica um único caractere alfanumérico maiúsculo do conjunto {A-Z, 0-9}. O requisito de caracteres em caixa alta é novo nesta versão da API. Os marcadores com tamanho padrão e mid são os únicos que podem exibir um parâmetro alphanumeric-character. Os marcadores tiny e small não exibem um caractere alfanumérico.

Dimensionamento do marcador

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

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

Locais dos marcadores

Cada descritor de marcador precisa conter um conjunto de um ou mais locais que definem onde o marcador será posicionado no mapa. Esses locais podem ser especificados como valores de latitude/longitude ou como endereços. Esses locais são separados usando o caractere de barra vertical (|).

Observação: se você especificar localizações de marcadores usando um método que exija geocodificação, como polilinhas ou strings de endereço legíveis, a solicitação ficará limitada a 15 marcadores. Esse limite se aplica apenas a 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 o local estiver fora do mapa, esse marcador não vai aparecer na imagem construída, 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 com os marcadores fornecidos. Consulte Posicionamento implícito.

Um exemplo de declaração de marcador é mostrado aqui. Observe que definimos um conjunto de estilos e três locais:

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 rotulado como "S" em 62.107733, -145.5419, um pequeno marcador verde em "Delta Junction, AK" e um marcador amarelo médio rotulado como "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 para URL). É possível usar URLs criados por serviços de redução de URL, como https://goo.gl. A maioria dos serviços de redução de URL tem a vantagem de codificar URLs automaticamente.

Você pode especificar um ponto de fixação para o ícone personalizado. O ponto de fixação define como o ícone é posicionado em relação aos locais markers especificados. Por padrão, o ponto de fixação de um ícone personalizado é a parte inferior central da imagem do ícone. Você pode especificar um ponto de fixação diferente usando o descritor anchor com o icon. Defina o anchor como um ponto x,y do ícone (por exemplo, 10,5) ou como um alinhamento predefinido usando um dos seguintes valores: top, bottom, left, right, center, topleft, topright, bottomleft ou bottomright. Exemplo:

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

Você pode usar até cinco ícones personalizados exclusivos por solicitação. Essa limitação não significa que o app pode ter apenas cinco locais marcados no mapa. Cada ícone exclusivo pode ser usado com mais de um local markers no seu mapa.

Formato do ícone:

  • As imagens de ícone podem estar nos formatos PNG, JPEG ou GIF, mas é recomendável usar PNG.
  • Os ícones podem ter até 4.096 pixels de tamanho (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 com ícones personalizados diferentes posicionados com âncoras.

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

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 a serem sobrepostos na imagem do mapa. O parâmetro path usa um conjunto de atribuições de valor (descritores de caminho) no seguinte formato:

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

Os dois pontos do caminho são separados um do outro usando o caractere de barra vertical (|). Como as informações de estilo e ponto são delimitadas por essa barra, as informações de estilo precisam aparecer primeiro em qualquer descritor de caminho. Quando o servidor da API Maps Static encontra um local no descritor do caminho, todos os outros parâmetros de caminho também são considerados locais.

Estilos de caminho

O conjunto de descritores de estilo de caminho é uma série de atribuições de valores separadas por uma barra vertical (|). Esse descritor de estilo define os atributos visuais a serem usados ao mostrar 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 aparecerá com a espessura padrão (5 pixels).

  • color: (opcional) especifica uma cor como um valor hexadecimal de 24 bits (exemplo: color=0xFFFFCC) ou de 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 definem o valor de transparência alfa de 8 bits. Esse valor varia entre 00 (completamente transparente) e FF (completamente opaco). As transparências são aceitas em caminhos, embora não sejam permitidas para marcadores.

  • fillcolor: (opcional) indica que o caminho marca uma área poligonal e especifica a cor de preenchimento a ser usada como uma sobreposição nessa área. O conjunto de locais a seguir não precisa ser um loop "fechado". O servidor da API Maps Static vai unir automaticamente o primeiro e o último ponto. No entanto, nenhum traço na parte externa da área preenchida será fechado, a menos que você forneça especificamente o mesmo local de início e término.
  • geodesic: (opcional) indica que o caminho solicitado deve ser interpretado como uma linha geodésica que segue a curvatura da Terra. Quando esse valor é falso, o caminho é renderizado como uma linha reta no espaço da tela. O padrão é "false".

Alguns exemplos de definições de caminho:

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

Esses estilos de caminho são opcionais. Se você quiser usar atributos padrão, poderá pular a definição de atributos de caminho. Nesse caso, o primeiro "argumento" do descritor de caminho consistirá no primeiro ponto declarado (localização).

Pontos do caminho

Para desenhar um caminho, o parâmetro path também precisa receber dois ou mais pontos. A API Maps Static conectará o caminho ao longo desses pontos na ordem especificada. Cada pathPoint é indicado no pathDescriptor separado pelo caractere de barra vertical |.

O exemplo a seguir define um caminho azul com opacidade padrão de 50%, da Union Square até a Times Square, NY.

Caminho da Union Square até a Times Square

Veja abaixo as especificidades 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 as especificidades 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 próximo exemplo 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 as especificidades 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

Definimos o próprio caminho como invisível e a área poligonal com 15% de opacidade.

Polilinhas codificadas

Em vez de uma série de locais, é possível declarar um caminho como uma polilinha codificada usando o prefixo enc: na declaração de localização da path.

O exemplo a seguir descreve o curso da Rodovia Alasca de Dawson Creek, BC, até 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}%7Ca@pytA_~b@hhCyhS~hResU%7C%7Cx@oig@rwg@amUfbjA}f[roaAynd@%7CvXxiAt{ZwdUfbjAewYrqGchH~vXkqnAria@c_o@inc@k{g@i`]o%7CF}vXaj\h`]ovs@?yi_@rcAgtO%7Cj_AyaJren@nzQrst@zuYh`]v%7CGbldEuzd@%7C%7Cx@spD%7CtrAzwP%7Cd_@yiB~vXmlWhdPez\_{Km_`@~re@ew^rcAeu_@zhyByjPrst@ttGren@aeNhoFemKrvdAuvVidPwbVr~j@or@f_z@ftHr{ZlwBrvdAmtHrmT{rOt{Zz}E%7Cc%7C@o%7CLpn~AgfRpxqBfoVz_iAocAhrVjr@rh~@jzKhjp@``NrfQpcHrb^k%7CDh_z@nwB%7Ckb@a{R%7Cyh@uyZ%7CllByuZpzw@wbd@rh~@%7C%7CFhqs@teTztrAupHhyY}t]huf@e%7CFria@o}GfezAkdW%7C}[ocMt_Neq@ren@e~Ika@pgE%7Ci%7CAfiQ%7C`l@uoJrvdAgq@fppAsjGhg`@%7ChQpg{Ai_V%7C%7Cx@mkHhyYsdP%7CxeA~gF%7C}[mv`@t_NitSfjp@c}Mhg`@sbChyYq}e@rwg@atFff}@ghN~zKybk@fl}A}cPftcAite@tmT__Lha@u~DrfQi}MhkSqyWivIumCria@ciO_tHifm@fl}A{rc@fbjAqvg@rrqAcjCf%7Ci@mqJtb^s%7C@fbjA{wDfs`BmvEfqs@umWt_Nwn^pen@qiBr`xAcvMr{Zidg@dtjDkbM%7Cd_@
&key=YOUR_API_KEY&signature=YOUR_SIGNATURE

Alaska Highway

Assim como nos caminhos padrão, os caminhos de polilinha codificada também poderão 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:}zswFtikbMjJzZ%7CRdPfZ}DxWvBjWpF~IvJnEvBrMvIvUpGtQpFhOQdKpz@bIx{A%7CPfYlvApz@bl@tcAdTpGpVwQtX}i@%7CGen@lCeAda@bjA%60q@v}@rfAbjA%7CEwBpbAd_@he@hDbu@uIzWcWtZoTdImTdIwu@tDaOXw_@fc@st@~VgQ%7C[uPzNtA%60LlEvHiYyLs^nPhCpG}SzCNwHpz@cEvXg@bWdG%60]lL~MdTmEnCwJ[iJhOae@nCm[%60Aq]qE_pAaNiyBuDurAuB }}Ay%60@%7CEKv_@?%7C[qGji@lAhYyH%60@Xiw@tBerAs@q]jHohAYkSmW?aNoaAbR}LnPqNtMtIbRyRuDef@eT_z@mW_Nm%7CB~j@zC~hAyUyJ_U{Z??cPvg@}s@sHsc@_z@cj@kp@YePoNyYyb@_iAyb@gBw^bOokArcA}GwJuzBre@i\tf@sZnd@oElb@hStW{]vv@??kz@~vAcj@zKa%60Atf@uQj_Aee@pU_UrcA
&key=YOUR_API_KEY&signature=YOUR_SIGNATURE

Polilinha codificada do Brooklyn com assinatura

Portas de visualização

As imagens podem especificar uma janela de visualização ao especificar locais visíveis com o parâmetro visible. O parâmetro visible instrui o serviço da API Maps Static a criar um mapa de modo que os locais atuais permaneçam visíveis. Esse parâmetro também pode ser combinado com marcadores ou caminhos existentes para definir uma região visível. Dessa forma, a definição de uma janela de visualização evita a 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, é necessário especificar os parâmetros de URL center e zoom para definir o local e o nível de zoom do mapa gerado. No entanto, se você fornecer os parâmetros markers, path ou visible, poderá deixar que a API Maps Static determine o centro e o nível de zoom corretos de forma implícita, com base na 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 adequados, fornecendo margens generosas para os elementos contidos. 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

Mapa de vias

Tamanhos de imagem maiores

Se você precisar de imagens com tamanhos acima de 640 x 640 pixels (ou 1280 x 1280 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, simulações ou exemplos de como você usará imagens grandes.
  4. Seu uso mensal estimado para imagens grandes em tamanho.

Analisaremos sua solicitação com base nas informações fornecidas e determinaremos se seu caso de uso obedece aos 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, confira a página de suporte.

A API Maps Static pode emitir um erro ou aviso quando algo dá errado. Verifique se há avisos, principalmente se perceber que falta algo no mapa. Também é importante conferir se há avisos antes de lançar um novo aplicativo. Os avisos podem não estar imediatamente aparentes porque aparecem no cabeçalho HTTP. Para ver mais informações, consulte o guia sobre erros e avisos.