Primeiros passos

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 o local 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. Também é possível rotular seus marcadores usando 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 obrigatório dos URLs da API Maps Static e os parâmetros disponíveis. Ele também traz 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 app para dispositivos móveis. Ela 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, revise 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 é acessado por HTTPS, carregue imagens da API Maps Static também 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 usando HTTP ou HTTPS, determinados 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 local

• center (obrigatório se não houver marcadores) define o centro do mapa, equidistante de todas as bordas. 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, new 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, 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. Mapas com menos de 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 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 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ó é aceito em alguns blocos de países. Se o idioma específico solicitado não for aceito para o conjunto de blocos, o idioma padrão dele 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. Confira as regiões aceitas nos detalhes de cobertura da Plataforma Google Maps.

Parâmetros do recurso

• 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 que a chave de API usada para inicializar o mapa. Para mais detalhes, 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 tenham o mesmo estilo. Você pode incluir outros marcadores de estilos diferentes adicionando outros parâmetros markers. Se você fornece marcadores para um mapa, não precisa 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 usando o prefixo enc: na declaração de localização do caminho. Você pode fornecer outros caminhos incluindo outros parâmetros path. Se você fornecer um caminho para um mapa, não vai precisar 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 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 elemento 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 elementos 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 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 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 isso. Solicitações sem 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 mais longos do que isso, a menos que produza mapas complicados com um alto 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 ser capaz de identificar com precisão os locais no mapa, tanto para focar o mapa no local correto (usando o parâmetro center) quanto 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, os locais são separados 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 uma 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 de Greenwich, na Inglaterra, onde se encontra o primeiro meridiano. Como Greenwich está situada na latitude 51.477222, podemos inserir o valor center de 51.477222,0 para centralizar o mapa em Greenwich:

Os valores de latitude e longitude precisam corresponder a um local válido no planeta. 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 inválido de latitude ou longitude, 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 poderá fazer isso se você fornecer endereços válidos.

Em qualquer parâmetro em que seja possível fornecer uma latitude/longitude, é possível, em vez disso, 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. Dessa forma, endereços como "Prefeitura, Nova York, NY" precisam ser convertidos em "Cidade+Hall,Nova+York,NY", por exemplo.

Os endereços podem refletir locais exatos, 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 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

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+ (até ruas e edifícios individuais) são possíveis na visualização roadmap padrão. Os contornos de edifícios, quando disponíveis, aparecem no mapa próximo ao nível de zoom 17. Esse valor difere de uma área para outra 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. Confira mais informações 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.

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ê consegue ver 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

  

Tamanhos de imagem

O parâmetro size, combinado 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 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, 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

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

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

Valores de escala

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 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 de polegada, tornando rótulos e ícones muito pequenos para serem lidos; ou
• Dimensione ou aplique zoom para melhorar a legibilidade da imagem, resultando em uma imagem distorcida ou pixelada.

Muito pequeno	Distorcida demais

Ao desenvolver para dispositivos móveis, você pode usar o parâmetro scale da API para retornar imagens de mapa em resolução mais alta e resolver os problemas acima. O valor scale é multiplicado pelo size para determinar o tamanho da saída 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 retorna 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 vias e rótulos para que fiquem legíveis em telas pequenas e de alta resolução e quando dimensionados pelo navegador.

150x150	150x150&scale=2

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

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

• A primeira é para uma imagem de 100x100 sem valor de scale especificado. Ele é exibido corretamente no computador, mas é muito pequeno para ser lido em um dispositivo móvel.
• A segunda dobra o tamanho do mapa. Em computadores, o CSS cabe 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 certo, mas, novamente, vias e 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. A área de trabalho a dimensiona perfeitamente para que não seja distinguível da solicitação original de 100 x 100, enquanto o navegador para dispositivos móveis se beneficia da resolução extra 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 esta leitura:

• Compatibilidade com várias telas na documentação do desenvolvedor Android.
• Recomendações do Webkit.org para desenvolver sites com alto DPI.
• Compatibilidade com telas de alta resolução na biblioteca de desenvolvedores do iOS.

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 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", 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, é 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 padrão, conforme mostrado normalmente no site do Google Maps. Se nenhum valor 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 do roteiro, mostrando uma camada transparente das principais ruas e nomes de lugares na imagem de satélite.

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

  

Os mapas híbridos usam imagens de satélite e elementos de mapa em destaque para criar um mapa combinado. Os exemplos a seguir mostram os 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

  

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 (alfinetes do 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 diferentes.

O parâmetro markers usa um conjunto de atribuições de valor (descritores de marcadores) 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 uma 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, todos os outros parâmetros do marcador também são considerados locais.

Estilos de marcadores

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 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 do 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 aceitas nos marcadores, embora sejam aceitas para caminhos.

• label: (opcional) especifica um único caractere alfanumérico uppercase do conjunto {A-Z, 0-9}. O requisito de caracteres maiúsculos é novo para esta 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 são capazes de exibir um caractere alfanumérico.

Dimensionamento de marcadores

O valor scale é multiplicado pelo tamanho da imagem do marcador para produzir o tamanho de saída real dele 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 o marcador estiver definido como scale:2, ele 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 do mapa ao mostrar mapas de resolução mais alta.

Locais do marcador

Cada descritor de marcador precisa conter um conjunto de um ou mais locais que definem 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 locais de marcadores usando um método que requer geocodificação, como polilinhas ou strings de endereço legíveis, a solicitação será limitada a 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 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.

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

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" em 62.107733, -145.5419, um pequeno marcador verde em "Delta Junction, AK" e um marcador amarelo de tamanho 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

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

É possível 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 central inferior 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. Isso não significa que você está limitado a apenas cinco locais marcados no mapa. Cada ícone 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, embora PNG seja o recomendado.
• Os ícones podem ter até 4.096 pixels de tamanho máximo (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

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

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 usando o caractere de barra vertical (|). Como as informações de estilo e de 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 valor separadas pelo caractere de 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 nos caminhos, mas não nos marcadores.

• fillcolor: (opcional) indica que o caminho sai de uma área poligonal e especifica a cor de preenchimento a ser usada como sobreposição dentro dessa á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 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 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 "false", o caminho será 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 quiser usar atributos padrão, ignore a definição dos atributos do caminho. Nesse caso, o primeiro "argumento" do descritor de caminho consistirá em vez do primeiro ponto declarado (local).

Pontos do caminho

Para desenhar um caminho, o parâmetro path também precisa receber 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 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, em Nova York.

As especificidades 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 abaixo define o mesmo caminho, em vez de uma linha vermelha sólida com 100% de opacidade:

As especificidades 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, passando uma série de interseções como locais:

As especificidades 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

Definimos o 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 de localização do path.

O exemplo a seguir descreve o curso da Alaska Highway 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

Assim como nos caminhos padrão, os caminhos de polilinha codificada 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:}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

Portas de visualização

As imagens podem definir 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 construir um mapa de modo que os locais existentes 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

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ê informar os parâmetros markers, path ou visible, poderá permitir que a API Maps Static determine o centro e o nível de zoom corretos com base na avaliação da posição desses elementos.

Se você fornecer dois ou mais elementos, a API Maps Static vai determinar o centro e o 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

Tamanhos de imagem maiores

Se você precisar de imagens com tamanhos maiores que 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 amostras de como você vai usar imagens grandes.
4. Seu uso mensal estimado de imagens grandes.

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 oferecer é 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.

Quando algo dá errado, a API Maps Static pode emitir um erro ou aviso. Verifique se há avisos, principalmente se perceber que algo está faltando no mapa. Também é importante verificar se há avisos antes de iniciar um novo aplicativo. Os avisos podem não ser imediatamente aparentes porque aparecem no cabeçalho HTTP. Para mais informações, consulte o guia sobre erros e avisos.