Começar

Mantenha tudo organizado com as coleções Salve e categorize o conteúdo com base nas suas preferências.

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 colocação de marcadores opcionais em locais do mapa. Você também pode rotular seus marcadores usando caracteres alfanuméricos.

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

Este documento descreve o formato necessário dos URLs da API Maps Static e os parâmetros disponíveis. Ele também destaca algumas dicas e sugestões para especificar seus URLs.

Antes de começar

Este documento é destinado a desenvolvedores de sites e dispositivos móveis que querem incluir imagens da API Maps Static em uma página da Web ou aplicativo para dispositivos móveis. Ele fornece uma introdução ao uso da API e a materiais de referência sobre os parâmetros disponíveis.

Antes de começar a desenvolver com a API Maps Static, revise os requisitos de autenticação (você precisa de uma chave de API) e as informações de uso e faturamento da API (você precisa 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 é acessado por HTTPS, é necessário carregar imagens da API Maps Static por HTTPS para evitar alertas de segurança do navegador. O HTTPS também é recomendado quando as solicitações incluem informações confidenciais do usuário, como a localização do usuário:

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

Seja usando HTTP ou HTTPS, alguns parâmetros de URL são obrigatórios, enquanto outros são opcionais. Como é padrão em URLs, todos os parâmetros são separados usando o amper e o caractere (&). A lista de parâmetros e os possíveis valores deles 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 os marcadores não estiverem presentes) define o centro do mapa, equidistante de todas as bordas do mapa. Esse parâmetro usa uma localização como um par de {latitude,longitude} separado por vírgula (por exemplo, "40.714728,-73.998672") ou um endereço de string (por exemplo, "município, nova york, ny") que identifica um local exclusivo na face da Terra. Para mais informações, consulte Locais.
  • zoom (obrigatório se os marcadores não estiverem presentes) define o nível de zoom do mapa, que determina o nível de ampliação do mapa. Esse parâmetro usa um valor numérico correspondente ao nível de zoom da região desejada. Para mais informações, consulte Níveis de zoom.

Parâmetros do mapa

  • size (obrigatório) define as dimensões retangulares da imagem de mapa. Esse parâmetro usa uma string com o formato {horizontal_value}x{vertical_value}. Por exemplo, 500x400 define um mapa de 500 pixels de largura por 400 pixels de altura. Os mapas com menos de 180 pixels de largura exibirão um logotipo do Google de tamanho reduzido. Esse parâmetro é afetado pelo parâmetro scale. O tamanho da saída final é o produto dos valores de tamanho e escala.
  • scale (opcional) afeta o número de pixels retornados. scale=2 retorna duas vezes mais pixels que scale=1 ao mesmo tempo em que mantém a mesma área de cobertura e o mesmo nível de detalhes, ou seja, o conteúdo do mapa não muda. Isso é útil ao desenvolver para telas de alta resolução. O valor padrão é 1. Os valores aceitos são 1 e 2. Consulte Valores de escala para mais informações.
  • format (opcional) define o formato da imagem resultante. Por padrão, a API Maps Static cria imagens PNG. Existem vários formatos possíveis, incluindo GIF, JPEG e PNG. O formato usado depende de como você pretende apresentar a imagem. JPEG normalmente oferece mais compactação, enquanto GIF e PNG oferecem mais detalhes. Para mais informações, consulte Formatos de imagem.
  • maptype (opcional) define o tipo de mapa a ser construído. Há vários valores de maptype possíveis, incluindo roadmap, satellite, hybrid e terrain. Para mais informações, consulte Tipos de mapas da API Maps Static.
  • language (opcional) define o idioma a ser usado para a exibição de rótulos nos blocos de mapas. Observe que 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, a linguagem padrão para esse conjunto de blocos será usada.
  • region (opcional) define as bordas apropriadas a serem exibidas, com base nas particularidades geopolíticas. Aceita um código de região especificado como um valor de ccTLD de dois caracteres ('domínio de nível superior'). Consulte os detalhes da cobertura da Plataforma Google Maps para ver as regiões compatíveis.

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 informações, consulte Como usar IDs de mapa.
  • markers (opcional) define um ou mais marcadores a serem anexados à imagem em locais especificados. Esse parâmetro usa uma única definição de marcador com parâmetros separados pelo caractere de barra (|). Vários marcadores podem ser colocados no mesmo parâmetro markers, desde que tenham o mesmo estilo. Para adicionar mais marcadores de estilos diferentes, basta adicionar mais parâmetros markers. Se você fornecer marcadores para um mapa, não será necessário especificar os parâmetros center e zoom (normalmente obrigatórios). Para mais informações, consulte Marcadores da API Maps Static.
  • path (opcional) define um único caminho de dois ou mais pontos conectados para se sobrepor na imagem em locais especificados. Esse parâmetro usa uma string de definições de pontos separadas pelo caractere de barra vertical (|) ou uma polilinha codificada que usa o prefixo enc: na declaração de localização do caminho. Você pode fornecer mais caminhos adicionando outros parâmetros path. Se você fornecer um caminho para um mapa, não será necessário especificar os parâmetros center e zoom (normalmente obrigatórios). Para 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 no 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 recursos) do mapa. Esse parâmetro usa argumentos feature e element que identificam os recursos a serem estilizados e um conjunto de operações de estilo a serem aplicados aos recursos selecionados. Você pode fornecer vários estilos adicionando outros parâmetros style. Para mais informações, consulte o guia sobre mapas estilizados.

Parâmetros de chave e assinatura

  • key (obrigatório) permite monitorar o uso da API do seu aplicativo no Console do Google Cloud e garante que o Google possa entrar em contato com você para falar sobre o aplicativo, se necessário. Para ver mais informações, consulte Acessar uma chave e uma assinatura.
  • signature (recomendado) é uma assinatura digital usada para verificar se qualquer site que gera solicitações usando sua chave de API está autorizado a fazer isso. As solicitações sem uma assinatura digital podem falhar. Para ver mais informações, consulte Acessar uma chave e uma assinatura.

Restrição de tamanho do URL

Os URLs da API Maps Static são restritos a 8.192 caracteres. Na prática, você provavelmente não precisará de URLs mais longos do que isso, a menos que produza mapas complicados com um grande número de marcadores e caminhos.

Uso de parâmetros

A API Maps Static é relativamente fácil de usar, porque consiste apenas em um URL parametrizado. Esta seção explica como usar esses parâmetros para criar seus URLs.

Especificar localizações

A API Maps Static precisa identificar com precisão locais no mapa, tanto para enfocar o mapa no local correto (usando o parâmetro center) quanto para posicionar marcadores opcionais (usando o parâmetro markers) nos locais do mapa. A API Maps Static usa números (valores de latitude e longitude) ou strings (endereços) para especificar esses locais. Esses valores identificam um local geocodificado.

Vários parâmetros (como os de markers e path) usam vários locais. Nesses casos, os locais são separados pelo caractere de barra vertical (|).

Latitudes e longitudes

As latitudes e longitudes são definidas com números dentro de uma string de texto separada por vírgulas que tem 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 entre Greenwich, Inglaterra, lar do meridiano principal. Como Greenwich está situada na latitude 51.477222, podemos inserir um valor center de 51.477222,0 para centralizar o mapa em Greenwich:

Greenwich, Inglaterra

Os valores de latitude e longitude devem corresponder a um local válido na face da Terra. As latitudes podem assumir qualquer valor entre -90 e 90, enquanto os valores de longitude podem assumir qualquer valor entre -180 e 180. Se você especificar um valor inválido de latitude ou longitude, seu pedido será rejeitado como inválido.

Endereços

A maioria das pessoas não fala em latitudes e longitudes. Elas indicam os 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 pode realizar a geocodificação para você se você fornecer endereços válidos.

Em qualquer parâmetro em que seja possível fornecer uma latitude/longitude, você pode especificar uma string indicando um endereço. O Google geocodificará o endereço e fornecerá ao serviço da API Maps Static um valor de latitude/longitude para colocar marcadores ou especificar locais. A string precisa ser codificada por URL. Portanto, endereços como "City Hall, New York, NY" devem ser convertidos em "City+Hall,New+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 os resultados polilineares e poligonais, o servidor da API Maps Static usará o ponto central da linha/área como o centro de 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ático para Berkeley, CA:

https://maps.googleapis.com/maps/api/staticmap?center=Berkeley,CA&zoom=14&size=400x400&key=YOUR_API_KEY&signature=YOUR_SIGNATURE

Berkeley, CA

Níveis de zoom

Os mapas no Google Maps têm um número inteiro 'nível de zoom', que define a resolução da visualização atual. Os níveis de zoom entre 0 (o mais baixo, em que todo o mundo pode ser visto em um mapa) e 21+ (em ruas e edifícios individuais) são possíveis na visualização padrão roadmap. Os contornos de edifícios, quando disponíveis, aparecem no mapa ao redor do nível de zoom 17. Esse valor pode variar de acordo com a área e pode mudar com o tempo, à medida que os dados mudam.

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 conforme o local, já que os dados em algumas partes do globo são mais granulares do que em outros locais.

Se você enviar uma solicitação para um nível de zoom em que nenhum bloco de mapa esteja disponível, a API Maps Static retornará um mapa que mostra o nível de zoom máximo disponível naquele local.

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 nos 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

Manhattan de longe  Manhattan de perto

Tamanhos de imagem

O parâmetro size e center definem 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 scale.

scale=1 scale=2
640x640 640x640 (retorna 1280 x 1280 pixels)

Este exemplo solicita uma fração do planeta na linha do 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

Linha do Equador

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

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

Pequeno mapa do equador

Valores de escala

O parâmetro size da API Maps Static define o tamanho de um mapa em pixels, de modo que um mapa com size=200x200 seja retornado como 200 pixels por 200 pixels. Em um monitor de computador LCD, que normalmente exibe cerca de 100 pixels por polegada (ppi), um mapa de 200 x 200 tem cerca de 2 polegadas em cada dimensão.

No entanto, cada vez mais os dispositivos móveis incluem telas de alta resolução com densidade de pixels acima de 300 ppi, que:

  • reduzir o tamanho de uma imagem de 200x200 pixels para apenas 0,7 de polegada, renderizando rótulos e ícones muito pequenos para leitura; ou
  • Amplie (aumente o zoom) a imagem para melhorar a legibilidade, resultando em uma imagem difusa 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 mapas de alta resolução que resolvam os problemas acima. O valor 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 escala de 2 retornará 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 estradas e rótulos, para que sejam legíveis em telas de alta resolução e tamanhos pequenos, bem como 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 diminuirá 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 é exibida corretamente no computador, mas é muito pequena para leitura em um dispositivo móvel.
  • A segunda dobra o tamanho do mapa. Em computadores, 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. No dispositivo móvel, a imagem tem o tamanho certo, mas, novamente, as vias e os rótulos são ilegíveis.
  • A terceira solicitação é para um mapa de 100x100 com scale=2. A imagem é retornada com 200 px de detalhes. A área de trabalho reduz a escala perfeitamente para que seja indistinguível da solicitação original de 100 x 100, enquanto o navegador para dispositivos móveis se beneficia da resolução extra retornada pela API.
Solicitações de imagem
Dispositivo 100x100 200x200 100x100&scale=2
Computador
(com height="100px" e
width="100px" na tag
img)
Alta resolução
(simulada)

Para mais informações sobre o desenvolvimento para telas de dispositivos móveis e de alta resolução, recomendamos as seguintes leituras:

Formatos de imagem

As imagens podem ser retornadas em vários formatos comuns de gráficos da Web: GIF, JPEG e PNG. O parâmetro format tem um dos seguintes valores:

  • png8 ou png (padrão) especifica o formato PNG de 8 bits.
  • png32 especifica o formato PNG de 32 bits.
  • gif especifica o formato GIF.
  • jpg especifica o formato de compactação JPEG.
  • jpg-baseline especifica um formato de compactação JPEG não progressivo.

jpg e jpg-baseline geralmente fornecem o menor tamanho de imagem, mesmo que isso seja feito por compactação "com perda", que pode reduzir 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 aproximada antes e refinam a resolução conforme mais dados chegam. Isso permite o carregamento rápido de imagens 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 (linha de base). Nesses casos, recomendamos 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 é exibida no site do Google Maps. Se nenhum valor maptype for especificado, a API Maps Static exibirá blocos de roadmap por padrão.
  • satellite especifica uma imagem de satélite.
  • terrain especifica uma imagem de mapa de relevo físico, mostrando terreno e vegetação.
  • hybrid especifica uma combinação de imagens de satélite e de mapa, mostrando uma camada transparente das principais ruas e nomes de lugares na imagem de satélite.

Você pode ver a diferença entre os tipos de roteiro e terreno neste exemplo de código.

https://maps.googleapis.com/maps/api/staticmap?center=40.714728,-73.998672&zoom=12&size=400x400&maptype=roadmap&key=YOUR_API_KEY&signature=YOUR_SIGNATURE
https://maps.googleapis.com/maps/api/staticmap?center=40.714728,-73.998672&zoom=12&size=400x400&maptype=terrain&key=YOUR_API_KEY&signature=YOUR_SIGNATURE

Mapa normal de Manhattan  Mapa de terreno de Manhattan

Os mapas híbridos usam imagens de satélite e recursos de mapa em destaque para criar um combinado. Os exemplos a seguir mostram tipos de mapas de satélite e híbridos:

https://maps.googleapis.com/maps/api/staticmap?center=40.714728,-73.998672&zoom=12&size=400x400&maptype=satellite&key=YOUR_API_KEY&signature=YOUR_SIGNATURE
https://maps.googleapis.com/maps/api/staticmap?center=40.714728,-73.998672&zoom=12&size=400x400&maptype=hybrid&key=YOUR_API_KEY&signature=YOUR_SIGNATURE

Mapa de satélite de Manhattan  Mapa de terreno de Manhattan

Mapas estilizados

Personalize sua apresentação usando o Google Maps 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 de mapa) em um conjunto de locais. Cada marcador definido em uma única declaração markers precisa exibir o mesmo estilo visual. Se quiser exibir marcadores com estilos diferentes, será necessário fornecer vários parâmetros markers com informações de estilo separadas.

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

Estilos de marcador

O conjunto de descritores de estilo de marcador é uma série de atribuições de valor separadas pelo caractere de barra vertical (|). Esse descritor de estilo define os atributos visuais que serão usados ao exibir os marcadores nesse descritor de marcador. Esses descritores de estilo contêm as seguintes atribuições de chave-valor:

  • size: (opcional) especifica o tamanho do marcador do conjunto {tiny, mid, small}. Se nenhum parâmetro size for definido, o marcador aparecerá no tamanho padrão (normal).
  • color: (opcional) especifica uma cor de 24 bits (exemplo: color=0xFFFFCC) ou uma cor predefinida do {black, brown, green, purple, yellow, blue, gray, orange, red, white} definido.

    As transparências (especificadas usando valores de cor hexadecimal de 32 bits) não são compatíveis com marcadores, embora sejam compatíveis com caminhos.

  • label: (opcional) especifica um único caractere alfanumérico maiúsculo do conjunto {A-Z, 0-9}. O requisito de caracteres maiúsculos é novo nesta versão da API. Os marcadores de tamanho padrão e mid são os únicos que podem exibir um parâmetro alphanumeric-character. Os marcadores tiny e small não podem exibir um caractere alfanumérico.

Escalonamento de marcadores

O valor scale é multiplicado pelo tamanho da imagem do marcador, para produzir o tamanho real do marcador em pixels. O valor de escalonamento padrão é 1. Os valores aceitos são 1, 2 e 4.

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

Locais 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 endereços. Esses locais são separados usando o caractere de barra vertical (|).

Observação: se você escolher especificar locais de marcadores usando um método que exija geocodificação, como strings de endereços legíveis ou polilinhas, a solicitação será limitada a um máximo de 15 marcadores. Esse limite se aplica apenas a locais de marcadores que exigem geocodificação. e não 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 será exibido 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 criará uma imagem automaticamente com os marcadores fornecidos. Consulte Posicionamento implícito.

Este é um exemplo de declaração de marcador. Definimos um conjunto de estilos e três locais:

https://maps.googleapis.com/maps/api/staticmap?center=Williamsburg,Brooklyn,NY&zoom=13&size=400x400&
markers=color:blue%7Clabel:S%7C11211%7C11206%7C11222&key=YOUR_API_KEY&signature=YOUR_SIGNATURE

Três códigos postais do Brooklyn

Para definir marcadores com estilos diferentes, precisamos fornecer vários parâmetros markers. Esse conjunto de parâmetros markers define três marcadores: um marcador azul chamado "quot;S" em 62.107733, -145.5419, um pequeno marcador verde em "Delta Junction, AK" e um marcador amarelo de tamanho médio rotulado como "quot;C" em "Tok. Esses marcadores são exibidos neste exemplo:

https://maps.googleapis.com/maps/api/staticmap?center=63.259591,-144.667969&zoom=6&size=400x400
&markers=color:blue%7Clabel:S%7C62.107733,-145.541936&markers=size:tiny%7Ccolor:green%7CDelta+Junction,AK
&markers=size:mid%7Ccolor:0xFFFF00%7Clabel:C%7CTok,AK"&key=YOUR_API_KEY&signature=YOUR_SIGNATURE

Três cidades do Alaska, diferentes marcadores

Ícones personalizados

Em vez de usar os ícones de 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 encurtamento 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 é o centro inferior da imagem do ícone. É possível especificar um ponto de fixação diferente usando o descritor anchor em conjunto com o icon. Defina o anchor como um ponto x,y do ícone (como 10,5) ou como um alinhamento predefinido usando um dos seguintes valores: top, bottom, left, right, center, topleft, topright, bottomleft ou bottomright. Exemplo:

markers=anchor:bottomright|icon:URLofIcon|markerLocation1|markerLocation2

Você pode usar até cinco ícones personalizados exclusivos por solicitação. Essa limitação não significa que o limite é de 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 do ícone podem estar nos formatos PNG, JPEG ou GIF, embora seja recomendável usar a imagem 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 as âncoras.

http://maps.googleapis.com/maps/api/staticmap?&size=600x400&style=visibility:on
&style=feature:water%7Celement:geometry%7Cvisibility:on
&style=feature:landscape%7Celement:geometry%7Cvisibility:on
&markers=anchor:32,10%7Cicon:https://goo.gl/5y3S82%7CCanberra+ACT
&markers=anchor:topleft%7Cicon:http://tinyurl.com/jrhlvu6%7CMelbourne+VIC
&markers=anchor:topright%7Cicon:https://goo.gl/1oTJ9Y%7CSydney+NSW&key=YOUR_API_KEY
&signature=YOUR_SIGNATURE

Três cidades australianas, diferentes ícones personalizados posicionados com âncoras.

O exemplo 2 cria os mesmos ícones personalizados do exemplo 1, mas não define as posições do ícone usando âncoras, dependendo da âncora padrão da parte inferior central.

http://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

Três cidades australianas, diferentes ícones personalizados com posicionamento padrão.

Caminhos da API Maps Static

O parâmetro path define um conjunto de um ou mais locais conectados por um caminho para se sobrepor à imagem do mapa. O parâmetro path usa um conjunto de atribuições de valor (descritores de caminho) com o seguinte formato:

path=pathStyles|pathLocation1|pathLocation2|... etc.

Observe que os dois pontos do caminho são separados um do outro usando o caractere de barra vertical (|). Como as informações de estilo e de pontos são delimitadas por meio do caractere de barra vertical, as informações de estilo precisam aparecer primeiro em qualquer descritor de caminho. Quando o servidor da API Maps Static encontra um local no descritor de caminho, 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 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âmetro weight for definido, o caminho será exibido com a espessura padrão (5 pixels).
  • color: (opcional) especifica uma cor, como valor de 24 bits (exemplo: color=0xFFFFCC) ou hexadecimal 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 especificam o valor de transparência Alfa de 8 bits. Esse valor varia entre 00 (completamente transparente) e FF (completamente opaco). As transparências são aceitas nos caminhos, mas não os marcadores.

  • fillcolor: (opcional) indica que o caminho marca uma área poligonal e especifica a cor de preenchimento a ser usada como uma sobreposição dentro dessa área. O conjunto de locais a seguir não precisa ser um loop "closed". O servidor da API Maps Static associará automaticamente o primeiro e o último pontos. No entanto, nenhum traço na parte preenchida 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 o valor é "false", 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 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. Caso queira usar os atributos padrão, você pode ignorar a definição dos atributos do caminho. Nesse caso, o primeiro argumento "argument" do descritor de caminho vai consistir em vez do primeiro ponto (local) declarado.

Pontos de caminho

Para desenhar um caminho, o parâmetro path também precisa ser transmitido em 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 | (barra vertical).

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

Caminho da Union Square até a Times Square

Estas são 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, em vez de uma linha vermelha sólida, com 100% de opacidade:

Caminho da Union Square até a Times Square

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

Caminho da Union Square até a Times Square

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 próprio caminho como invisível e a área poligonal para ter 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 localização de 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&center=59.900503,-135.478011&zoom=4
&path=weight:3%7Ccolor:orange%7Cenc:_fisIp~u%7CU}%7Ca@pytA_~b@hhCyhS~hResU%7C%7Cx@oig@rwg@amUfbjA}f[roaAynd@%7CvXxiAt{ZwdUfbjAewYrqGchH~vXkqnAria@c_o@inc@k{g@i`]o%7CF}vXaj\h`]ovs@?yi_@rcAgtO%7Cj_AyaJren@nzQrst@zuYh`]v%7CGbldEuzd@%7C%7Cx@spD%7CtrAzwP%7Cd_@yiB~vXmlWhdPez\_{Km_`@~re@ew^rcAeu_@zhyByjPrst@ttGren@aeNhoFemKrvdAuvVidPwbVr~j@or@f_z@ftHr{ZlwBrvdAmtHrmT{rOt{Zz}E%7Cc%7C@o%7CLpn~AgfRpxqBfoVz_iAocAhrVjr@rh~@jzKhjp@``NrfQpcHrb^k%7CDh_z@nwB%7Ckb@a{R%7Cyh@uyZ%7CllByuZpzw@wbd@rh~@%7C%7CFhqs@teTztrAupHhyY}t]huf@e%7CFria@o}GfezAkdW%7C}[ocMt_Neq@ren@e~Ika@pgE%7Ci%7CAfiQ%7C`l@uoJrvdAgq@fppAsjGhg`@%7ChQpg{Ai_V%7C%7Cx@mkHhyYsdP%7CxeA~gF%7C}[mv`@t_NitSfjp@c}Mhg`@sbChyYq}e@rwg@atFff}@ghN~zKybk@fl}A}cPftcAite@tmT__Lha@u~DrfQi}MhkSqyWivIumCria@ciO_tHifm@fl}A{rc@fbjAqvg@rrqAcjCf%7Ci@mqJtb^s%7C@fbjA{wDfs`BmvEfqs@umWt_Nwn^pen@qiBr`xAcvMr{Zidg@dtjDkbM%7Cd_@
&key=YOUR_API_KEY&signature=YOUR_SIGNATURE

Alaska Highway

Assim como nos caminhos padrão, os caminhos de polilinha codificada também poderão demarcar áreas poligonais se um argumento fillcolor for transmitido para o parâmetro path.

O exemplo a seguir apresenta uma área poligonal em Brooklyn, NY:

https://maps.googleapis.com/maps/api/staticmap
?size=400x400&center=40.653279,-73.959816&zoom=11
&path=fillcolor:0xAA000033%7Ccolor:0xFFFFFF00%7Cenc:}zswFtikbMjJzZ%7CRdPfZ}DxWvBjWpF~IvJnEvBrMvIvUpGtQpFhOQdKpz@bIx{A%7CPfYlvApz@bl@tcAdTpGpVwQtX}i@%7CGen@lCeAda@bjA%60q@v}@rfAbjA%7CEwBpbAd_@he@hDbu@uIzWcWtZoTdImTdIwu@tDaOXw_@fc@st@~VgQ%7C[uPzNtA%60LlEvHiYyLs^nPhCpG}SzCNwHpz@cEvXg@bWdG%60]lL~MdTmEnCwJ[iJhOae@nCm[%60Aq]qE_pAaNiyBuDurAuB }}Ay%60@%7CEKv_@?%7C[qGji@lAhYyH%60@Xiw@tBerAs@q]jHohAYkSmW?aNoaAbR}LnPqNtMtIbRyRuDef@eT_z@mW_Nm%7CB~j@zC~hAyUyJ_U{Z??cPvg@}s@sHsc@_z@cj@kp@YePoNyYyb@_iAyb@gBw^bOokArcA}GwJuzBre@i\tf@sZnd@oElb@hStW{]vv@??kz@~vAcj@zKa%60Atf@uQj_Aee@pU_UrcA
&key=YOUR_API_KEY&signature=YOUR_SIGNATURE

Polilinha codificada no Brooklyn com assinatura

Portas de visualização

As imagens podem especificar uma janela de visualização especificando os locais visíveis usando 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 evita a necessidade de especificar um nível de zoom exato.

O próximo exemplo solicita um mapa centralizado em Boston, Massachusetts, que contém o MIT e a Harvard Square em Cambridge, MA:

https://maps.googleapis.com/maps/api/staticmap?center=Boston,MA
&visible=77+Massachusetts+Ave,Cambridge,MA%7CHarvard+Square,Cambridge,MA&size=512x512&key=YOUR_API_KEY&signature=YOUR_SIGNATURE

Mapa de Cambridge

Posicionamento implícito do mapa

Normalmente, é necessário 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 os parâmetros markers, path ou visible, poderá deixar a API Maps Static determinar o centro e o nível de zoom corretos implicitamente, com base na avaliação da posição desses elementos.

Se você fornecer dois ou mais elementos, a API Maps Static determinará o centro e o nível de zoom adequados, fornecendo margens generosas para os elementos contidos. Este exemplo mostra um mapa que contém São Francisco, Oakland e São José, CA:

https://maps.googleapis.com/maps/api/staticmap?size=512x512&maptype=roadmap\
&markers=size:mid%7Ccolor:red%7CSan+Francisco,CA%7COakland,CA%7CSan+Jose,CA&key=YOUR_API_KEY&signature=YOUR_SIGNATURE

Roteiro

Tamanhos de imagem maiores

Se você precisar de imagens com tamanhos maiores que 640 x 640 pixels (ou 1.280 x 1.280 pixels com valor de escala de 2), entre em contato com a equipe de suporte e forneça as seguintes informações:

  1. Seu caso de uso e por que você precisa de imagens grandes.
  2. Considere usar outras APIs da Plataforma Google Maps (API Maps JavaScript, API Maps Embed, SDK do Maps para Android ou SDK do Maps para iOS) e por que elas não atendem às suas necessidades.
  3. Capturas de tela, simulações ou exemplos de como você usará imagens de tamanho grande
  4. Seu uso mensal estimado para imagens de tamanho grande.

Vamos analisar sua solicitação com base nas informações fornecidas 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 é 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 um aviso quando algo der errado. Você deve verificar se há algum aviso em particular se perceber que falta algo no mapa. Também é uma boa ideia verificar os avisos antes de lançar um novo aplicativo. Os avisos podem não ser aparentes imediatamente porque aparecem no cabeçalho HTTP. Para mais informações, consulte o guia sobre erros e avisos.