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âmetroscale
. 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 quescale=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ão1
e2
. 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, incluindoroadmap
,satellite
,hybrid
eterrain
. 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âmetromarkers
, desde que exibam o mesmo estilo. Você pode incluir outros marcadores de estilos diferentes adicionando outros parâmetrosmarkers
. Quando você fornece marcadores para um mapa, não é necessário especificar os parâmetroscenter
ezoom
, 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 prefixoenc:
na declaração de localização do caminho. Você pode fornecer outros caminhos adicionando outros parâmetrospath
. Se você fornecer um caminho para um mapa, não será necessário especificar os parâmetroscenter
ezoom
, 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 argumentosfeature
eelement
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âmetrosstyle
. 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:
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
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
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
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
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" ewidth="100px" na tagimg ) |
![]() |
![]() |
![]() |
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:
- Suporte a várias telas na documentação do desenvolvedor Android.
- Recomendações do Webkit.org para desenvolver sites 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 gráficos comuns da Web: GIF,
JPEG e PNG. O parâmetro format
usa um dos seguintes valores:
png8
oupng
(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 demaptype
for especificado, a API Maps Static exibirá blocosroadmap
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
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
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âmetrosize
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 emid
são os únicos que podem exibir um parâmetroalphanumeric-character
. Os marcadorestiny
esmall
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
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
Í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
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 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âmetroweight
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) eFF
(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.
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:
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:
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¢er=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 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¢er=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 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
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
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:
- Seu caso de uso e por que você precisa de imagens grandes.
- 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.
- Capturas de tela, simulações ou exemplos de como você usará imagens grandes.
- 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.