Esta página foi traduzida pela API Cloud Translation.

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 o posicionamento de marcadores opcionais em locais do mapa. Além disso, é possível rotular seus marcadores usando caracteres alfanuméricos.

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

Este documento descreve o formato necessário dos URLs da API Maps Static e os parâmetros disponíveis. Ele também aponta algumas dicas e sugestões 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 aplicativo para dispositivos móveis. Ele fornece uma introdução ao uso da API e a 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 (chave de API) e as informações de uso e faturamento da API (ative 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 seu site for acessado por HTTPS, também será necessário carregar 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 do usuário:

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

Seja usando 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 ampersand (&). A lista de parâmetros e os respectivos valores são enumerados neste documento.

Importante: a discussão de parâmetros de URL usa exemplos que, para fins de esclarecimento, são fornecidos na forma pré-escape. Antes de enviar uma solicitação à API, os parâmetros dela precisam ser codificados em URL. Por exemplo, muitos parâmetros usam um caractere de barra vertical (|) como separador, que precisa ser codificado como %7C no URL final, como no exemplo rápido no topo deste documento. Para mais informações, consulte Como criar um URL válido.

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

Parâmetros de local

center (obrigatório, se os marcadores não estiverem presentes) 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, "prefeitura, 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, 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 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 por 400 pixels de altura. Os mapas menores que 180 pixels de largura 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 detalhe, 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 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 construído. Há vários valores de tipo de mapa possíveis, incluindo roadmap, satellite, hybrid e terrain. Para saber mais, consulte os tipos de mapa da API Maps Static.
language (opcional) define o idioma a ser 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 dele será usado.
region (opcional) define as bordas apropriadas para exibição, com base em sensibilidades políticas. Aceita um código de região especificado como um valor de ccTLD ("domínio de nível superior") de dois caracteres. Consulte os detalhes da cobertura da Plataforma Google Maps para ver as regiões compatíveis.

Parâmetros de recurso

map_id (opcional) define o identificador de um mapa específico. O ID do mapa o associa 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 a serem anexados à 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 tenham o mesmo estilo. É possível adicionar outros marcadores com estilos diferentes adicionando outros parâmetros markers. Se você fornecer marcadores para um mapa, não precisará especificar os parâmetros center e zoom (normalmente obrigatórios). Para mais informações, consulte Marcadores da API Maps Static.
path (opcional) define um único caminho com dois ou mais pontos conectados para sobrepor 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 usando o prefixo enc: na declaração do local do caminho. Você pode fornecer mais caminhos incluindo outros parâmetros path. Se você fornecer um caminho para um mapa, não será necessário especificar os parâmetros center e zoom (normalmente obrigatórios). Para saber mais, consulte Caminhos da API Maps Static.
visible (opcional) especifica um ou mais locais que devem permanecer visíveis no mapa, mas nenhum marcador ou outros indicadores serão exibidos. Use esse parâmetro para garantir que determinados recursos ou localizações 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 de mapas estilizados.

Parâmetros de chave e assinatura

key (obrigatório) permite monitorar o uso de APIs 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 qualquer site que gere solicitações usando sua chave de API tem autorização para isso. As solicitações sem assinatura digital podem falhar. Para mais informações, consulte Usar uma assinatura digital.

Restrição de tamanho do URL

Os URLs da API Maps Static estão restritos a 8.192 caracteres. Na prática, você provavelmente não precisará de URLs maiores do que isso, 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 com precisão os locais no mapa, tanto para focar no local correto (usando o parâmetro center) quanto para posicionar marcadores opcionais (usando o parâmetro markers) nos 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, os locais são separados pelo caractere de barra vertical (|).

Latitudes e longitudes

Latitudes e longitudes são definidas por numerais separados por vírgulas em uma string de texto 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 6 casas decimais é ignorada.

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

Greenwich, Inglaterra

Os valores de latitude e longitude precisam corresponder a um local válido na face da 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 Google Maps Static API pode fazer isso se você fornecer endereços válidos.

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

Os endereços podem refletir localizações precisas, como endereços, polilinhas, como trajetos nomeados, ou áreas poligonais, como cidades, países ou parques nacionais. Para resultados polilineares ou 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 como um endereço pode ser geocodificado, teste o endereço 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 no 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 mapa) e 21+ (até ruas e edifícios individuais) são possíveis na visualização padrão de roadmap. Os contornos de edifícios, quando disponíveis, aparecem no mapa ao redor do nível de zoom 17. Esse valor é diferente para cada região 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 subsequente dobra a precisão nas dimensões horizontal e vertical. Saiba mais sobre como fazer isso 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 em que não haja blocos de mapa, a API Maps Static retornará uma imagem em branco.

A lista a seguir mostra o nível aproximado de detalhamento esperado 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 center, mas respectivamente nos níveis de zoom 12 e 14:

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, definido 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 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" da Terra 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 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 para que um mapa com size=200x200 seja retornado como 200 pixels por 200 pixels. Em um monitor de computador LCD, que normalmente exibe cerca de 100 pixels por polegada (ppi), um mapa de 200 x 200 terá aproximadamente 2 polegadas em cada dimensão.

No entanto, os dispositivos móveis incluem cada vez mais telas de alta resolução com densidades de pixels acima de 300 ppi, 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 leitura; ou
Dimensione (aumente) 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 de alta resolução que resolvam os problemas acima. O valor scale é multiplicado por size para determinar o tamanho real 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 escala 2 retornará a mesma área de cobertura do mapa que uma solicitação sem escala especificada, mas com o dobro de pixels em cada dimensão. Isso inclui estradas e rótulos, para que possam ser lidos em telas de alta resolução e tamanho pequeno, bem como quando dimensionados pelo navegador.

150x150	150x150&scale=2

Essa imagem também terá boa performance em navegadores para computador quando for inserida em uma tag img ou div com a altura e a largura definidas usando CSS. O navegador reduzirá a imagem para o tamanho correto, sem perder qualidade.

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

A primeira é para uma imagem de 100x100 sem valor de scale especificado. Ele é exibido corretamente no computador, mas é muito pequeno para leitura em um dispositivo móvel.
A segunda dobra o tamanho do mapa. No computador, o CSS o encaixa no elemento img de 100x100 especificado, mas, ao reduzir a imagem, as vias e rótulos ficam muito pequenos. No dispositivo móvel, a imagem tem o tamanho certo, mas as vias e os rótulos estão ilegíveis.
A terceira solicitação é para um mapa de 100x100 com scale=2. A imagem é retornada com 200 pixels de detalhes. A área de trabalho reduz a escala perfeitamente para que seja indistinguível da solicitação original de 100x100, 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 (simulado)

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

Para mais informações sobre o desenvolvimento para telas de alta resolução e dispositivos móveis, recomendamos a leitura a seguir:

Suporte a várias telas na documentação para desenvolvedores Android.
Recomendações do Webkit.org para desenvolver sites da Web com alto DPI.
Suporte a telas de alta resolução na Biblioteca de desenvolvedores do iOS.

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 tem 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 o menor tamanho de imagem, mas fazem isso por meio de um método de compactação com "perda", o que pode diminuir a qualidade da imagem. gif, png8 e png32 oferecem compactação sem perdas.

A maioria das imagens JPEG é progressiva. Isso significa que elas carregam uma imagem menos abrangente e refinam a resolução conforme mais dados são recebidos. Isso permite que as imagens sejam carregadas rapidamente nas páginas da Web e é o uso mais difundido de JPEG atualmente. No entanto, alguns usos de JPEG exigem imagens não progressivas (linha de base). 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 mapa padrão, que normalmente é exibida 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 mapa de relevo físico, mostrando terreno e vegetação.
hybrid especifica uma combinação de imagens de satélite e de mapa, mostrando uma camada transparente das principais ruas e nomes de lugares na imagem de satélite.

Veja a diferença entre os tipos de roteiro e terreno 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

Os mapas híbridos usam imagens de satélite e recursos de mapa em destaque para criar um combinado. Os exemplos a seguir mostram tipos de mapas 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 (pins de 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, é necessário fornecer 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 barra (|), seguidos por um conjunto de um ou mais locais também separados pelo caractere barra (|).

Como as informações de estilo e de localização são delimitadas pelo caractere 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 também são locais.

Estilos de marcador

O conjunto de descritores de estilo de marcador é uma série de atribuições de valor separadas pelo caractere de barra vertical (|). Esse descritor de estilo define os atributos visuais a serem usados ao exibir os marcadores dentro desse 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á exibido 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 aceitas nos marcadores, mas são compatíveis com caminhos.
label: (opcional) especifica um único caractere alfanumérico maiúscula a partir do conjunto {A-Z, 0-9}. O requisito de caracteres em letra maiúscula é novo nesta versão da API. Os marcadores com tamanho padrão e mid são os únicos marcadores capazes de exibir um parâmetro alphanumeric-character. Os marcadores tiny e small não podem exibir um caractere alfanumérico.

Escalonamento de marcadores

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

O limite de tamanho de pixel nas imagens é aplicado após o dimensionamento ser aplicado. Por exemplo, se o marcador for definido como scale:2, ele poderá ser maior do que o tamanho máximo de 4.096 pixels, desde que ele seja reduzido para menos de 4.096 pixels após o dimensionamento. Use o escalonamento de marcadores com o dimensionamento de mapas ao exibir mapas de alta resolução.

Locais dos marcadores

Cada descritor de marcador precisa conter um conjunto de um ou mais locais. Para isso, defina onde colocar o marcador 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 os locais dos marcadores usando um método que exija geocodificação, como strings de endereços legíveis ou polilinhas, a solicitação estará limitada a um máximo de 15 marcadores. Esse limite se aplica apenas aos locais de marcadores que exigem geocodificação. Ela 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 aparecerá na imagem construída, desde que os parâmetros center e zoom sejam fornecidos. No entanto, quando esses parâmetros não são fornecidos, o servidor da API Maps Static cria automaticamente uma imagem com os marcadores fornecidos. Consulte Posicionamento implícito.

Um exemplo de declaração do 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 de tamanho médio com o rótulo "C" em "Tok, AK". Os 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 marcador 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 icon usando um URL que precisa ser codificado por 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 fica na parte de baixo da imagem do ícone. Você pode especificar um ponto de fixação diferente usando o descritor anchor em conjunto com o icon. Defina o anchor como um ponto x,y do ícone (como 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

É possível usar até cinco ícones personalizados exclusivos por solicitação. Essa limitação não significa que você está limitado a apenas cinco locais marcados no seu 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, embora PNG seja 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 fixos.

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, diferentes ícones personalizados posicionados com âncoras.

O exemplo 2 cria os mesmos ícones personalizados que o exemplo 1, mas não define as posições dos ícones 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

Caminhos da API Maps Static

O parâmetro path define um conjunto de um ou mais locais conectados por um caminho a ser sobreposto 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 do ponto são delimitadas por meio do caractere de barra vertical, 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 de caminho, presume-se que todos os outros parâmetros de caminho também são locais.

Estilos de caminho

O conjunto de descritores de estilo de caminho é uma série de atribuições de valor 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 um 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). As transparências são aceitas nos caminhos, mas não nos marcadores.
fillcolor: (opcional) indica que o caminho marca uma área poligonal e especifica a cor de preenchimento a ser usada como uma sobreposição dentro dessa área. O conjunto de locais a seguir não precisa ser um loop "fechado". O servidor da API Maps Static associará automaticamente o primeiro e o último pontos. 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 de término.
geodesic: (opcional) indica que o caminho solicitado precisa ser interpretado como uma linha geodésica que segue a curvatura da Terra. Quando definido como falso, o caminho é renderizado como uma linha reta no espaço da tela. O padrão é "false".

Veja 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 espessa e sólida: path=color:0xffffffff|weight:10

Esses estilos de caminho são opcionais. Se você quiser usar atributos padrão, poderá deixar de definir os atributos do caminho. Nesse caso, o primeiro "argumento" do descritor do caminho consistirá no primeiro ponto declarado (local).

Pontos do caminho

Para desenhar um caminho, o parâmetro path também precisa ser transmitido dois ou mais pontos. A API Maps Static vai conectar o caminho ao longo desses pontos na ordem especificada. Cada pathPoint é indicado no pathDescriptor separado pela | (barra vertical).

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

Caminho da Union Square até a Times Square

Veja os detalhes 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, em vez de uma linha vermelha sólida com 100% de opacidade:

Caminho da Union Square até a Times Square

Veja os detalhes específicos desse 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, transmitindo uma série de interseções como locais:

Caminho da Union Square até a Times Square

Veja os detalhes específicos desse 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, declare um caminho como uma polilinha codificada usando o prefixo enc: na declaração do local do path.

O exemplo a seguir descreve o percurso da Rodovia Alaska 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}%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 especificando locais visíveis usando o parâmetro visible. O parâmetro visible instrui o serviço da API Maps Static a criar um mapa para 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. Definir uma janela de visualização dessa maneira elimina 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

O 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, será possível deixar a API Maps Static determinar o centro e o nível de zoom corretos implicitamente, com base na avaliação da posição desses elementos.

Se você fornecer dois ou mais elementos, a API Maps Static determinará um centro e um nível de zoom adequados, fornecendo margens generosas para os elementos contidos no mapa. Este exemplo mostra um mapa com 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

Imagens 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:

Seu caso de uso e por que você precisa de imagens de tamanho grande.
Considere 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.
Capturas de tela, simulações ou amostras de como você usará imagens de tamanho grande.
Seu uso mensal estimado para imagens grandes.

Analisaremos sua solicitação com base nas informações fornecidas e determinaremos 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 é 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 deu errado. Você precisará verificar os avisos principalmente se perceber que falta algo no mapa. Também é importante verificar se há avisos antes de lançar um novo aplicativo. Os avisos podem não ser aparentes imediatamente porque aparecem no cabeçalho HTTP. Para mais informações, consulte o guia sobre erros e avisos.