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â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. 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, 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ó é 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âmetromarkers
, desde que tenham o mesmo estilo. Você pode incluir outros marcadores de estilos diferentes adicionando outros parâmetrosmarkers
. Se você fornece marcadores para um mapa, não precisa 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 usando o prefixoenc:
na declaração de localização do caminho. Você pode fornecer outros caminhos incluindo outros parâmetrospath
. Se você fornecer um caminho para um mapa, não vai precisar 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 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 argumentosfeature
eelement
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âmetrosstyle
. 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" ewidth="100px" natag 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
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 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 valormaptype
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 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â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 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 emid
são os únicos que podem exibir um parâmetroalphanumeric-character
. Os marcadorestiny
esmall
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â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 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¢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 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:}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:
- 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.
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.