Introdução
A API Maps Static retorna uma imagem (GIF, PNG ou JPEG) em resposta a uma solicitação HTTP por meio de um URL. Para cada solicitação, você pode especificar a localização do mapa, o tamanho da imagem, o nível de zoom, o tipo de mapa e a inclusão de marcadores opcionais em pontos do mapa. Também é possível rotular seus marcadores com caracteres alfanuméricos.
Uma imagem da API Maps Static é incorporada no atributo src
de uma tag <img>
ou o elemento equivalente em outras linguagens de programação.
Neste documento, descrevemos o formato obrigatório dos URLs da API Maps Static e os parâmetros disponíveis. Também são destacadas algumas dicas e truques para especificar seus URLs.
Antes de começar
Este documento é destinado a desenvolvedores de sites e dispositivos móveis que querem incluir imagens da API Maps Static em uma página da Web ou um aplicativo móvel. Ele fornece uma introdução sobre como usar a API e materiais de referência sobre os parâmetros disponíveis.
Antes de começar a desenvolver com a API Maps Static, confira os requisitos de autenticação, que é uma chave de API, e as informações de uso e faturamento da API, que são necessárias para ativar o faturamento no seu projeto.
Parâmetros de URL
Um URL da API Maps Static precisa ter o seguinte formato:
https://maps.googleapis.com/maps/api/staticmap?parameters
Se o site for acessado por HTTPS, 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 se as solicitações incluírem informações sensíveis do usuário, como a localização:
https://maps.googleapis.com/maps/api/staticmap?parameters
Seja com 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 comporta um local como um par {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 superfície 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. O parâmetro aceita um valor numérico correspondente ao nível de zoom da região desejada. Para mais informações, consulte Níveis de zoom.
Parâmetros do mapa
size
(obrigatório) define as dimensões retangulares da imagem do mapa. Esse parâmetro usa uma string no formato{horizontal_value}x{vertical_value}
. Por exemplo,500x400
define um mapa com 500 pixels de largura e 400 pixels de altura. Mapas com menos de 180 pixels de largura vão mostrar um logotipo do Google de tamanho reduzido. Esse parâmetro é afetado pelo parâmetroscale
. O tamanho da saída final é o produto dos valores de tamanho e escala.scale
(opcional) afeta o número de pixels que são retornados.scale=2
retorna o dobro de pixels 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. Existem vários formatos possíveis, incluindo tipos GIF, JPEG e PNG. O formato usado depende de como você pretende apresentar a imagem. O JPEG geralmente oferece mais compactação, enquanto GIF e PNG oferecem mais detalhes. Para mais informações, consulte Formatos de imagem.maptype
(opcional) define o tipo de mapa a ser criado. Há vários valores de tipo de mapa possíveis, incluindoroadmap
,satellite
,hybrid
eterrain
. Para mais informações, consulte Maptypes da API Maps Static.language
(opcional) define o idioma usado para mostrar os rótulos nos blocos de mapa. Esse parâmetro só é permitido em alguns blocos de países. Se o idioma específico solicitado não for permitido em um determinado bloco de país, o idioma padrão será usado.region
(opcional) define as bordas apropriadas a serem exibidas, com base em particularidades geopolíticas. Esse parâmetro aceita códigos de região especificados como um valor de ccTLD ('domínio de nível superior') de dois caracteres. Consulte os detalhes da cobertura da Plataforma Google Maps para conferir as regiões com suporte.
Parâmetros de recursos
map_id
(opcional) especifica o identificador de um mapa específico. O ID do mapa associa um mapa a um estilo ou recurso específico e precisa pertencer ao mesmo projeto da chave de API usada para inicializar o mapa. Para mais informações, consulte Usar IDs de mapa.markers
(opcional) define um ou mais marcadores para anexar à imagem em locais especificados. Esse parâmetro aceita uma definição de marcador único com parâmetros separados pelo caractere de barra vertical (|
). É possível inserir vários marcadores no mesmo parâmetromarkers
, desde que eles tenham o mesmo estilo. Para incluir marcadores de estilos diferentes, adicione mais parâmetrosmarkers
. Se você fornecer marcadores para um mapa, não será necessário especificar os parâmetros (normalmente obrigatórios)center
ezoom
. Para mais informações, consulte Marcadores da API Maps Static.path
(opcional) define um caminho para dois ou mais pontos conectados para sobrepor na imagem em locais especificados. Esse parâmetro 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 caminhos adicionais adicionando parâmetrospath
adicionais. Se você fornecer um caminho para um mapa, não será preciso 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 devem permanecer visíveis no mapa, embora nenhum marcador ou outros indicadores sejam exibidos. Use esse parâmetro para garantir que determinados recursos ou localizações do mapa sejam mostrados na API Maps Static.style
(opcional) define um estilo personalizado para mudar a apresentação de um elemento 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 para aplicar aos elementos selecionados. Você pode fornecer vários estilos adicionando outros parâmetrosstyle
. Para mais informações, consulte o guia de mapas estilizados.
Parâmetros de chave e assinatura
key
(obrigatório) permite monitorar o uso da API do seu aplicativo no console do Google Cloud e garante que o Google possa entrar em contato com você sobre seu aplicativo, se necessário. Para saber mais, consulte Usar chaves de API com a API Maps Static.signature
(recomendado) é uma assinatura digital usada para verificar se qualquer site que gera solicitações usando sua chave de API tem autorização para fazer isso. As solicitações sem uma assinatura digital podem falhar. Para mais informações, consulte Usar uma assinatura digital.
Restrição de tamanho de URL
Os URLs da API Maps Static têm um limite de 16.384 caracteres. Na prática, você provavelmente não vai precisar de URLs maiores do que isso, a não ser que produza mapas complicados com um grande número de marcadores e caminhos.
Uso de parâmetros
A API Maps Static é relativamente fácil de usar, porque é composta apenas de 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 para focar o mapa no local correto (usando o parâmetro center
) e/ou colocar marcadores opcionais (usando o parâmetro markers
) em pontos do mapa. A API Maps Static
usa números (valores de latitude e longitude) ou strings (endereços)
para especificar esses locais. Esses valores identificam um local geocodificado.
Vários parâmetros (como markers
e path
)
incluem várias localizações. Nesses casos, as localizações são
separadas pelo caractere de barra vertical (|
).
Latitudes e longitudes
Latitudes e longitudes são definidas usando numerais em uma string de texto separada por vírgulas com precisão de até 6 casas decimais. Por exemplo, "40.714728,-73.998672" é um valor geocodificado válido. A precisão além de seis casas decimais é ignorada.
Valores de longitude são baseados na distância de Greenwich, Inglaterra, lar
do meridiano principal. Como Greenwich está situada a uma latitude de 51,477222, podemos inserir um valor center
de 51.477222,0
para centralizar o mapa em Greenwich:
Valores de latitude e longitude devem corresponder a uma localização válida no mundo. Latitudes aceitam qualquer valor entre -90
e
90
, enquanto valores de longitude aceitam qualquer valor entre
-180
e 180
. Se você especificar valores inválidos para latitude ou
longitude, sua solicitação será rejeitada como inválida.
Endereços
A maioria das pessoas não fala de latitudes e longitudes. Elas identificam localizações usando addresses. O processo de transformar um endereço em um ponto geográfico é conhecido como geocodificação, e o serviço da API Maps Static pode realizar a geocodificação se você fornecer endereços válidos.
Em qualquer parâmetro que comporte uma latitude/longitude, é possível especificar uma string com um endereço. O Google geocodificará o endereço e fornecerá ao serviço da API Maps Static um valor de latitude/longitude para inserir marcadores ou especificar localizações. A string precisa ser codificada em URL. Por exemplo, endereços como "Prefeitura, Nova York, NY" precisam ser convertidos em "Prefeitura,Nova+York,NY".
Os endereços podem refletir localizações precisas, como nomes de ruas, polilinhas, como rotas nomeadas, ou áreas poligonais, como cidades, países ou parques nacionais. Para resultados polilineares ou poligonais, o servidor da API Maps Static vai usar o ponto central da linha/área como centro do endereço. 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 nível mais baixo, com o qual é possível visualizar o mundo inteiro em um mapa) e 21+
(refinando a exibição para ruas e edifícios individuais) são possíveis na visualização roadmap
padrão. Contornos de edifícios, quando
disponíveis, são exibidos no mapa aproximadamente no nível de zoom 17
. Esse valor
varia de acordo com a área e pode mudar ao longo do tempo com a evolução dos dados.
O Google Maps define o nível de zoom como 0
para abranger toda a Terra.
Cada nível de zoom subsequente dobra a precisão nas dimensões horizontal e vertical. 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 de acordo com a localização, pois os dados em partes do mundo podem ser mais granulares do que em outras áreas.
Se você enviar uma solicitação de nível de zoom em que não há blocos de mapa, a API Maps Static vai retornar uma imagem em branco.
A lista a seguir mostra o nível aproximado de detalhes que você pode esperar em cada nível de zoom:
- 1: Mundo
- 5: terra/continente
- 10: cidade
- 15: ruas
- 20: construções
Este exemplo solicita dois mapas de Manhattan com o mesmo valor de center
, mas com níveis de zoom 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
e center
define a área de cobertura de um mapa. Ele também define o tamanho da saída do mapa em pixels quando multiplicado pelo valor de scale
(que é 1
por padrão).
Esta tabela mostra os valores máximos permitidos para
o parâmetro size
em cada valor de scale
.
scale=1 |
scale=2 |
---|---|
640x640 |
640x640 (retorna 1280x1280 pixels) |
Este exemplo solicita uma "fatia" 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
Este exemplo solicita um pequeno mapa de 100 x 100 pixels centralizado na mesma região. Observe o logotipo menor do Google:
https://maps.googleapis.com/maps/api/staticmap?center=0,0&zoom=1&size=100x100&key=YOUR_API_KEY&signature=YOUR_SIGNATURE
Valores de escala
O parâmetro size
da API Maps Static define o tamanho de um mapa em pixels. Dessa forma, um mapa com size=200x200
será retornado como 200 x 200 pixels. Em um monitor de computador LCD, que geralmente exibe 100 pixels por polegada (ppi), um mapa de 200x200 terá cerca de 2 polegadas em cada dimensão.
No entanto, os dispositivos móveis incluem cada vez mais telas de alta resolução com densidades de pixel de mais de 300 ppi, o que:
- Reduz o tamanho de uma imagem de 200x200 pixels para somente 0,7 polegada, tornando rótulos e ícones pequenos demais para serem lidos; ou
- Aumenta (com o zoom) a imagem para melhorar a legibilidade, resultando em uma imagem distorcida ou pixelada.
Muito pequeno | Distorcida demais |
---|---|
Ao desenvolver para dispositivos móveis, use o parâmetro scale
da API
para retornar imagens de mapa com resoluções maiores que solucionem os problemas
acima. O valor de scale
é multiplicado pelo size
para determinar o tamanho real da saída da imagem em pixels, sem alterar
a área de cobertura do mapa. O valor padrão de scale
é 1. Os valores aceitos são 1 e 2.
Por exemplo, o valor de escala 2 retorna a mesma área de cobertura de mapa que uma solicitação sem especificação de escala, mas com o dobro de pixels em cada dimensão. Isso inclui estradas e rótulos, para que eles fiquem legíveis em telas pequenas de alta resolução e quando dimensionados pelo navegador.
150x150 | 150x150&scale=2 |
---|---|
Essa imagem também terá um bom desempenho em navegadores de computador quando inseridas
em uma tag img
ou div
com a altura e largura
definidas usando CSS. O navegador reduzirá a imagem para o tamanho correto,
sem perda de qualidade.
Esta tabela mostra três solicitações de imagem diferentes.
- A primeira é para uma imagem de 100x100 sem valor de scale especificado. Ela aparece corretamente no computador, mas é pequena demais para ser lida em um dispositivo móvel.
- A segunda dobra o tamanho do mapa. No computador, 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, estradas 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. Em computadores, ela é dimensionada perfeitamente, tornando-se indistinguível da solicitação original de 100x100, enquanto que usuários de dispositivos móveis se beneficiam com a resolução adicional retornada pela API.
Solicitações de imagem | |||
---|---|---|---|
Dispositivo | 100x100 |
200x200 |
100x100&scale=2 |
Computador (com height="100px" 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 o seguinte:
- Suporte a várias telas na documentação para desenvolvedores do Android.
- Recomendações do Webkit.org para o desenvolvimento de sites com alto DPI.
- Suporte a telas de alta resolução na Biblioteca do desenvolvedor 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
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.jpg-baseline
especifica um formato de compactação JPEG não progressivo.
Estes exemplos solicitam mapas nos formatos gif
e png
:
https://maps.googleapis.com/maps/api/staticmap?center=40.714728,-73.998672&format=gif&zoom=14&size=400x400&key=YOUR_API_KEY&signature=YOUR_SIGNATURE https://maps.googleapis.com/maps/api/staticmap?center=40.714728,-73.998672&format=png&&zoom=14&size=400x400&key=YOUR_API_KEY&signature=YOUR_SIGNATURE
jpg
e jpg-baseline
normalmente fornecem imagens com o
menor tamanho, embora o façam com a compactação "com perda", que pode
degradar a imagem. gif
, png8
e png32
oferecem compactação sem perdas.
A maioria das imagens JPEG é progressiva, o que significa que elas carregam uma imagem
mais difusa inicialmente e refinam a resolução conforme mais dados são recebidos. Isso permite que as imagens sejam carregadas rapidamente nas páginas da Web e é o uso mais difundido de JPEG atualmente. No entanto, alguns usos de JPEG exigem
imagens não progressivas (de linha de base). 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 de ruas padrão, que é normalmente mostrada no site do Google Maps. Se nenhum valor demaptype
for especificado, a API Maps Static vai 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 mapa de ruas, mostrando uma camada transparente com as principais ruas e pontos de referência na imagem de satélite.
Confira a diferença entre os tipos de roadmap e terrain neste exemplo de código.
https://maps.googleapis.com/maps/api/staticmap?center=40.714728,-73.998672&zoom=12&size=400x400&maptype=roadmap&key=YOUR_API_KEY&signature=YOUR_SIGNATURE https://maps.googleapis.com/maps/api/staticmap?center=40.714728,-73.998672&zoom=12&size=400x400&maptype=terrain&key=YOUR_API_KEY&signature=YOUR_SIGNATURE
Os mapas híbridos usam imagens de satélite e recursos de mapa em destaque para criar um mapa combinado. Os exemplos a seguir mostram os tipos de mapa híbrido e de satélite:
https://maps.googleapis.com/maps/api/staticmap?center=40.714728,-73.998672&zoom=12&size=400x400&maptype=satellite&key=YOUR_API_KEY&signature=YOUR_SIGNATURE https://maps.googleapis.com/maps/api/staticmap?center=40.714728,-73.998672&zoom=12&size=400x400&maptype=hybrid&key=YOUR_API_KEY&signature=YOUR_SIGNATURE
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 (pinos 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 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 de markers
e consiste em zero ou mais descritores de estilo separados pelo caractere de barra vertical (|
), seguido por um conjunto de um ou mais locais também separados pelo caractere de barra vertical (|
).
Como as informações de estilo e localização são delimitadas por caracteres de barra vertical, as informações de estilo precisam aparecer primeiro em qualquer descritor de marcador. Quando o servidor da API Maps Static encontra um local no descritor do marcador, todos os outros parâmetros dele também são considerados locais.
Estilos de marcadores
O conjunto de descritores de estilo de um marcador é uma série de atribuições de valores separadas pelo caractere de barra vertical (|
). Esse descritor de estilo
define os atributos visuais a serem usados ao exibir os marcadores no descritor de marcador. Esses descritores de estilo contêm as seguintes atribuições de chave-valor:
size:
(opcional) especifica o tamanho do marcador com base no conjunto{tiny, mid, small}
. Se nenhum parâmetrosize
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}
.Observe que transparências (especificadas usando valores de cor hexadecimais de 32 bits) não são permitidas em marcadores, apesar de serem permitidas para caminhos.
label:
(opcional) especifica um único caractere alfanumérico em maiúsculas do conjunto {A-Z, 0-9}. (O requisito para caracteres em caixa alta é uma novidade dessa versão da API.) Os marcadores de tamanho padrão emid
são os únicos que podem mostrar 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 real de saída 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 pixel nas imagens é aplicado depois da aplicação da escala. 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 seja reduzido para menos de 4.096 pixels após o redimensionamento. Ao mostrar mapas de alta resolução, use o dimensionamento dos marcadores com o escalonamento.
Localizações dos marcadores
Cada descritor de marcador precisa conter um conjunto de um ou mais locais que definam onde colocar o marcador no mapa. Esses locais podem ser especificados
como valores de latitude/longitude ou como
addresses. Elas são separadas pelo caractere de barra vertical (|
).
Observação: se você especificar os locais dos marcadores usando um método que exija geocodificação, como strings de endereço legíveis ou polilinhas, a solicitação será limitada a um máximo de 15 marcadores. Esse limite se aplica apenas aos locais de marcadores que exigem geocodificação. Ele não se aplica a locais de marcadores especificados com coordenadas de latitude/longitude.
Os parâmetros de localização definem o local do marcador no mapa. Se o local estiver fora do mapa, o 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 que contém 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 com o rótulo "S" nas coordenadas 62.107733, -145.5419, um marcador verde pequeno em "Delta Junction, AK" e um marcador amarelo de tamanho médio com o rótulo "C" em "Tok, AK". Esses marcadores são mostrados neste exemplo:
https://maps.googleapis.com/maps/api/staticmap?center=63.259591,-144.667969&zoom=6&size=400x400 &markers=color:blue%7Clabel:S%7C62.107733,-145.541936&markers=size:tiny%7Ccolor:green%7CDelta+Junction,AK &markers=size:mid%7Ccolor:0xFFFF00%7Clabel:C%7CTok,AK"&key=YOUR_API_KEY&signature=YOUR_SIGNATURE
Ícones personalizados
Em vez de usar os ícones de marcadores do Google, você pode usar seus próprios ícones personalizados. Os ícones personalizados são especificados usando o descritor icon
no parâmetro markers
. Exemplo:
markers=icon:URLofIcon|markerLocation
Especifique o icon
usando um URL (que precisa ser
codificado em URL). É possível usar
URLs criados por serviços de encurtamento de URL, como https://goo.gl
. A maioria
desses serviços oferece o benefício de codificar URLs automaticamente.
Você pode especificar um ponto de ancoragem para o ícone personalizado. O ponto de âncora define como o
ícone é colocado em relação aos locais markers
especificados. Por padrão, o
ponto de âncora de um ícone personalizado fica na parte central inferior da imagem do ícone. Você pode
especificar um ponto de ancoragem diferente usando o descritor anchor
em conjunto
com o icon
. Defina anchor
como um ponto x,y do ícone (como
10,5
) ou como um alinhamento predefinido usando um destes valores:
top
, bottom
, left
, right
,
center
, topleft
, topright
, bottomleft
ou
bottomright
. Exemplo:
markers=anchor:bottomright|icon:URLofIcon|markerLocation1|markerLocation2
É possível usar até cinco ícones personalizados diferentes por solicitação. Essa limitação não significa que você está limitado a apenas cinco locais marcados no mapa. Cada ícone exclusivo pode ser usado com mais de um local markers
no mapa.
Formato do ícone:
- As imagens do ícone podem estar nos formatos PNG, JPEG ou GIF, mas PNG é o formato recomendado.
- Os ícones podem ter até 4.096 pixels (64 x 64 para imagens quadradas).
Exemplos de ícones personalizados
O Exemplo 1 cria ícones personalizados e os posiciona usando âncoras.
https://maps.googleapis.com/maps/api/staticmap?&size=600x400&style=visibility:on &style=feature:water%7Celement:geometry%7Cvisibility:on &style=feature:landscape%7Celement:geometry%7Cvisibility:on &markers=anchor:32,10%7Cicon:https://goo.gl/5y3S82%7CCanberra+ACT &markers=anchor:topleft%7Cicon:http://tinyurl.com/jrhlvu6%7CMelbourne+VIC &markers=anchor:topright%7Cicon:https://goo.gl/1oTJ9Y%7CSydney+NSW&key=YOUR_API_KEY &signature=YOUR_SIGNATURE
O exemplo 2 cria os mesmos ícones personalizados do exemplo 1, mas não define as posições dos ícones usando âncoras, dependendo da âncora padrão de centro inferior.
https://maps.googleapis.com/maps/api/staticmap?&size=600x400&style=visibility:on &style=feature:water%7Celement:geometry%7Cvisibility:on &style=feature:landscape%7Celement:geometry%7Cvisibility:on &markers=icon:https://goo.gl/5y3S82%7CCanberra+ACT &markers=icon:http://tinyurl.com/jrhlvu6%7CMelbourne+VIC &markers=icon:https://goo.gl/1oTJ9Y%7CSydney+NSW&key=YOUR_API_KEY&signature=YOUR_SIGNATURE
Caminhos da API Maps Static
O parâmetro path
define um conjunto de um ou mais locais
conectados por um caminho para sobrepor na imagem do mapa. O parâmetro path
usa um conjunto de atribuições de valor (descritores de caminho) no seguinte formato:
path=pathStyles|pathLocation1|pathLocation2|...
etc.
Os pontos do caminho são separados pelo caractere de barra vertical (|
). Como as informações de estilo e de ponto são delimitadas por caracteres de barra vertical, as informações de estilo precisam aparecer primeiro em qualquer descritor de caminho. Quando o servidor da API Maps Static encontra uma
localização no descritor do caminho, presume-se que todos os outros parâmetros do caminho também são
localizações.
Estilos de caminho
O conjunto de descritores de estilo de um caminho é uma série de atribuições de valores
separadas pelo caractere de barra vertical (|
). Esse descritor de estilo define os atributos visuais que serão 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âmetroweight
for definido, o caminho vai aparecer com a espessura padrão (5 pixels).color:
(opcional) especifica uma cor como valor hexadecimal de 24 bits (exemplo:color=0xFFFFCC
) ou 32 bits (exemplo:color=0xFFFFCCFF
), ou do conjunto{black, brown, green, purple, yellow, blue, gray, orange, red, white}
.Quando um valor hexadecimal de 32 bits é especificado, os dois últimos caracteres especificam o valor de transparência alfa de 8 bits. Esse valor varia entre
00
(completamente transparente) eFF
(completamente opaco). Observe que transparências são permitidas em caminhos, apesar de não serem permitidas para marcadores.fillcolor:
(opcional) indica que o caminho marca uma área poligonal e especifica a cor de preenchimento a ser usada como sobreposição nessa área. O conjunto de localizações subsequente não precisa ser um loop "fechado". O servidor da API Maps Static une automaticamente o primeiro e o último pontos. No entanto, qualquer traço no exterior da área preenchida não será fechado, a menos que você forneça especificamente o mesmo local de início e fim.geodesic:
(opcional) indica que o caminho solicitado precisa ser interpretado como uma linha geodésica que segue a curvatura da Terra. Quando esse valor é false, o caminho é renderizado como uma linha reta no espaço da tela. O padrão é "false".
Confira alguns exemplos de definições de caminho:
- Linha azul fina, 50% de opacidade:
path=color:0x0000ff80|weight:1
- Linha vermelha sólida:
path=color:0xff0000ff|weight:5
- Linha branca grossa e sólida:
path=color:0xffffffff|weight:10
Esses estilos de caminho são opcionais. Se quiser usar atributos padrão, ignore a definição de atributos de caminho. Nesse caso, o primeiro "argumento" do descritor de caminho será considerado em vez do primeiro ponto declarado (localização).
Pontos de caminho
Para desenhar um caminho, o parâmetro path
também precisa receber dois ou mais pontos. A API Maps Static conectará o caminho ao longo desses pontos, na ordem especificada. Cada pathPoint é
denotado no pathDescriptor separado pelo caractere de barra vertical
|
.
O exemplo a seguir define um caminho azul com opacidade padrão de 50%, da Union Square até a Times Square, em NY.
Os detalhes do parâmetro path
são:
path=color:0x0000ff|weight:5|40.737102,-73.990318|40.749825,-73.987963|40.752946,-73.987384|40.755823,-73.986397
O exemplo abaixo define o mesmo caminho, em vez de uma linha vermelha sólida com 100% de opacidade:
Os detalhes específicos desse parâmetro path
são:
path=color:0xff0000ff|weight:5|40.737102,-73.990318|40.749825,-73.987963|40.752946,-73.987384|40.755823,-73.986397
O próximo exemplo define uma área poligonal em Manhattan, transmitindo uma série de interseções como locais:
Os detalhes específicos desse parâmetro path
são:
path=color:0x00000000|weight:5|fillcolor:0xFFFF0033|8th+Avenue+%26+34th+St,New+York,NY|\ 8th+Avenue+%26+42nd+St,New+York,NY|Park+Ave+%26+42nd+St,New+York,NY,NY|\ Park+Ave+%26+34th+St,New+York,NY,NY
O caminho em si é invisível e a área poligonal tem uma opacidade de 15%.
Polilinhas codificadas
Em vez de uma série de locais, você pode declarar um caminho como uma
polilinha codificada
usando o prefixo enc:
na declaração de local do
path
.
O exemplo a seguir descreve o percurso da Alaska Highway de Dawson Creek, BC, a Delta Junction, AK, com uma polilinha codificada:
https://maps.googleapis.com/maps/api/staticmap ?size=400x400¢er=59.900503,-135.478011&zoom=4 &path=weight:3%7Ccolor:orange%7Cenc:_fisIp~u%7CU%7D%7Ca@pytA_~b@hhCyhS~hResU%7C%7Cx@oig@rwg@amUfbjA%7Df%5BroaAynd@%7CvXxiAt%7BZwdUfbjAewYrqGchH~vXkqnAria@c_o@inc@k%7Bg@i%60%5Do%7CF%7DvXaj%5Ch%60%5Dovs@?yi_@rcAgtO%7Cj_AyaJren@nzQrst@zuYh%60%5Dv%7CGbldEuzd@%7C%7Cx@spD%7CtrAzwP%7Cd_@yiB~vXmlWhdPez%5C_%7BKm_%60@~re@ew%5ErcAeu_@zhyByjPrst@ttGren@aeNhoFemKrvdAuvVidPwbVr~j@or@f_z@ftHr%7BZlwBrvdAmtHrmT%7BrOt%7BZz%7DE%7Cc%7C@o%7CLpn~AgfRpxqBfoVz_iAocAhrVjr@rh~@jzKhjp@%60%60NrfQpcHrb%5Ek%7CDh_z@nwB%7Ckb@a%7BR%7Cyh@uyZ%7CllByuZpzw@wbd@rh~@%7C%7CFhqs@teTztrAupHhyY%7Dt%5Dhuf@e%7CFria@o%7DGfezAkdW%7C%7D%5BocMt_Neq@ren@e~Ika@pgE%7Ci%7CAfiQ%7C%60l@uoJrvdAgq@fppAsjGhg%60@%7ChQpg%7BAi_V%7C%7Cx@mkHhyYsdP%7CxeA~gF%7C%7D%5Bmv%60@t_NitSfjp@c%7DMhg%60@sbChyYq%7De@rwg@atFff%7D@ghN~zKybk@fl%7DA%7DcPftcAite@tmT__Lha@u~DrfQi%7DMhkSqyWivIumCria@ciO_tHifm@fl%7DA%7Brc@fbjAqvg@rrqAcjCf%7Ci@mqJtb%5Es%7C@fbjA%7BwDfs%60BmvEfqs@umWt_Nwn%5Epen@qiBr%60xAcvMr%7BZidg@dtjDkbM%7Cd_@ &key=YOUR_API_KEY&signature=YOUR_SIGNATURE
Da mesma forma que com caminhos padrão, caminhos de polilinhas codificadas também podem demarcar áreas poligonais
se um argumento fillcolor
for transmitido para o parâmetro path
.
O exemplo a seguir apresenta uma área poligonal em Brooklyn, NY:
https://maps.googleapis.com/maps/api/staticmap ?size=400x400¢er=40.653279,-73.959816&zoom=11 &path=fillcolor:0xAA000033%7Ccolor:0xFFFFFF00%7Cenc:%7DzswFtikbMjJzZ%7CRdPfZ%7DDxWvBjWpF~IvJnEvBrMvIvUpGtQpFhOQdKpz%40bIx%7BA%7CPfYlvApz%40bl%40tcAdTpGpVwQtX%7Di%40%7CGen%40lCeAda%40bjA%60q%40v%7D%40rfAbjA%7CEwBpbAd_%40he%40hDbu%40uIzWcWtZoTdImTdIwu%40tDaOXw_%40fc%40st%40~VgQ%7C%5BuPzNtA%60LlEvHiYyLs%5EnPhCpG%7DSzCNwHpz%40cEvXg%40bWdG%60%5DlL~MdTmEnCwJ%5BiJhOae%40nCm%5B%60Aq%5DqE_pAaNiyBuDurAuB%7D%7DAy%60%40%7CEKv_%40%3F%7C%5BqGji%40lAhYyH%60%40Xiw%40tBerAs%40q%5DjHohAYkSmW%3FaNoaAbR%7DLnPqNtMtIbRyRuDef%40eT_z%40mW_Nm%7CB~j%40zC~hAyUyJ_U%7BZ%3F%3FcPvg%40%7Ds%40sHsc%40_z%40cj%40kp%40YePoNyYyb%40_iAyb%40gBw%5EbOokArcA%7DGwJuzBre%40i%5Ctf%40sZnd%40oElb%40hStW%7B%5Dvv%40%3F%3Fkz%40~vAcj%40zKa%60Atf%40uQj_Aee%40pU_UrcA &key=YOUR_API_KEY&signature=YOUR_SIGNATURE
Janelas de visualização
As imagens podem especificar uma porta de visualização ao definir localizações visíveis usando
o parâmetro visible
. O parâmetro visible
instruí o serviço da API Maps Static a criar um mapa para que os locais
existentes permaneçam visíveis. (Esse parâmetro também pode ser combinado a marcadores ou caminhos existentes para definir uma região visível.) Definir uma porta de visualização dessa maneira implica na necessidade de especificar um nível de zoom exato.
O próximo exemplo solicita um mapa centralizado em Boston, MA, contendo o MIT e a Harvard Square em Cambridge, MA:
https://maps.googleapis.com/maps/api/staticmap?center=Boston,MA &visible=77+Massachusetts+Ave,Cambridge,MA%7CHarvard+Square,Cambridge,MA&size=512x512&key=YOUR_API_KEY&signature=YOUR_SIGNATURE
Posicionamento implícito do mapa
Normalmente, é preciso especificar os parâmetros de URL center
e zoom
para definir a localização e o nível de zoom do mapa gerado.
No entanto, se você fornecer parâmetros markers
, path
ou
visible
, será possível permitir que a API Maps Static
determine o centro e o nível de zoom corretos de forma implícita com base em uma avaliação da
posição desses elementos.
Se você fornecer dois ou mais elementos, a API Maps Static 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
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 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 amostras de como você vai usar imagens grandes.
- Seu uso mensal estimado de imagens grandes.
Vamos analisar sua solicitação com base nas informações enviadas e determinar se o caso de uso está em conformidade com os Termos de Serviço da Plataforma Google Maps.
O tamanho máximo que podemos fornecer é de 2048 x 2048 pixels.
Solução de problemas e suporte
Para mais informações sobre como usar a API Maps Static, consulte a página de suporte.
A API Maps Static pode emitir um erro ou aviso quando algo dá errado. Verifique a presença de avisos se perceber que falta algo no mapa. Também é recomendável verificar a presença de avisos antes de lançar um novo aplicativo. Os avisos podem não estar imediatamente aparentes, porque eles são exibidos no cabeçalho HTTP. Para mais informações, consulte o guia de erros e avisos.