Começar

Desenvolvedores do Espaço Econômico Europeu (EEE)

Se o endereço de faturamento estiver no Espaço Econômico Europeu, a partir de 8 de julho de 2025, os Termos de Serviço da Plataforma Google Maps para o EEE valerão para o uso dos serviços. Saiba mais. Além disso, alguns conteúdos da API Maps Static não serão mais retornados. Saiba mais.

Introdução

A API Maps Static retorna uma imagem (GIF, PNG ou JPEG) em resposta a uma solicitação HTTP por um URL. Para cada solicitação, é possível 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 no mapa. Também é possível rotular os marcadores usando caracteres alfanuméricos.

Uma imagem da API Maps Static é incorporada ao atributo src de uma tag <img> ou ao 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 mostra 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 um aplicativo para dispositivos móveis. Ele apresenta uma introdução ao uso da API e material de referência sobre os parâmetros disponíveis.

Antes de começar a desenvolver com a API Maps Static, consulte os requisitos de autenticação (você precisa de uma chave de API) e as informações de uso e faturamento da API (você precisa ativar o faturamento no seu projeto).

Parâmetros de URL

O URL da API Maps Static precisa ter o seguinte formato:

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

Se o site for acessado por HTTPS, você também precisará carregar as 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 dele:

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 caractere E comercial (&). A lista de parâmetros e os possíveis valores estão enumerados neste documento.

Importante:a discussão sobre parâmetros de URL usa exemplos que, para fins de esclarecimento, são fornecidos na forma pré-escape. Antes de enviar qualquer solicitação à API, os parâmetros precisam ser codificados em URL. Por exemplo, muitos parâmetros usam um caractere de barra vertical (|) como separador, que precisa ser codificado como %7C no URL final, como no exemplo rápido no início deste documento. Para mais informações, consulte Como criar um URL válido.

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. Esse parâmetro usa um local como um par {latitude,longitude} separado por vírgulas (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 Terra. Saiba mais em 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 de mapa

• size (obrigatório) define as dimensões retangulares da imagem do mapa. Esse parâmetro usa uma string do formato {horizontal_value}x{vertical_value}. Por exemplo, 500x400 define um mapa com 500 pixels de largura por 400 pixels de altura. Os mapas com menos de 180 pixels de largura mostram um logotipo do Google menor. Esse parâmetro é afetado pelo parâmetro scale. O tamanho final da saída é o produto dos valores de tamanho e escala.
• scale (opcional) afeta o número de pixels retornados. scale=2 retorna o dobro de pixels de scale=1, mantendo a mesma área de cobertura e nível de detalhe (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. Há vários formatos possíveis, incluindo os tipos GIF, JPEG e PNG. O formato usado depende de como você pretende apresentar a imagem. O JPEG normalmente oferece maior compactação, enquanto o GIF e o 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 possíveis para maptype, incluindo roadmap, satellite, hybrid e terrain. Para mais informações, consulte Tipos de mapa da API Maps Static.
• colorscheme (opcional) define o esquema de cores do mapa. Os valores aceitos são light (padrão) e dark. O esquema de cores escuras se aplica aos tipos de mapa roadmap e terrain. Para mais informações, consulte Saiba mais sobre modos e tipos de mapa.
• language (opcional) define o idioma que será usado para mostrar os rótulos nos blocos de mapa. Esse parâmetro é compatível apenas com alguns blocos de países. Se o idioma solicitado não for compatível com o conjunto de blocos, o idioma padrão desse conjunto será usado.
• region (opcional) define as fronteiras adequadas a serem exibidas, com base em sensibilidades geopolíticas. Aceita um código de região especificado como um valor ccTLD ("domínio de nível superior") de dois caracteres. Saiba quais são as regiões com disponibilidade acessando os detalhes de cobertura da Plataforma Google Maps.

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 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 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 (|). É possível colocar vários marcadores no mesmo parâmetro markers, desde que eles tenham o mesmo estilo. Para adicionar outros marcadores com estilos diferentes, inclua 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 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 usando o prefixo enc: na declaração de local do caminho. É possível fornecer outros caminhos adicionando mais 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 precisam permanecer visíveis no mapa, embora nenhum marcador ou outro indicador seja exibido. Use esse parâmetro para garantir que determinados recursos ou locais do mapa sejam mostrados na API Maps Static.
• style (opcional) define um estilo personalizado para alterar a apresentação de um elemento específico (vias, parques e outros) do mapa. Esse parâmetro usa argumentos feature e element que identificam os elementos a serem estilizados e um conjunto de operações de estilo a serem aplicadas aos elementos selecionados. É possível 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 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 geram solicitações de geração usando sua chave de API têm autorização para isso. As solicitações sem uma assinatura digital podem falhar. Para mais informações, consulte Usar uma assinatura digital.

Restrição de tamanho do URL

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

Uso de parâmetros

A API Maps Static é relativamente fácil de usar, já que consiste apenas em um URL parametrizado. Nesta seção, explicamos 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, tanto para focar o mapa no local correto (usando o parâmetro center) quanto para colocar marcadores de local opcionais (usando o parâmetro markers) em locais no 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) aceitam 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 usando números em uma string de texto separada por vírgulas com precisão de seis casas decimais. Por exemplo, "40.714728,-73.998672" é um valor de geocódigo válido. A precisão além das 6 casas decimais é ignorada.

Os valores de longitude são baseados na distância de Greenwich, na Inglaterra, onde fica o meridiano principal. Como Greenwich está na latitude 51.477222, podemos inserir um valor center de 51.477222,0 para centralizar o mapa em Greenwich:

Os valores de latitude e longitude precisam corresponder a um local válido na superfície da Terra. As latitudes podem assumir qualquer valor entre -90 e 90, enquanto as longitudes podem assumir qualquer valor entre -180 e 180. Se você especificar um valor de latitude ou longitude inválido, sua solicitação será rejeitada como uma solicitação inválida.

Endereços

A maioria das pessoas não fala em latitudes e longitudes, mas indica 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 você possa fornecer uma latitude/longitude, é possível especificar uma string que indique um endereço. O Google vai geocodificar o endereço e fornecer ao serviço da API Maps Static um valor de latitude/longitude para usar na inserção de marcadores ou na especificação de locais. A string precisa ser codificada em URL. Assim, endereços como "City Hall, New York, NY" precisam ser convertidos em "City+Hall,New+York,NY", por exemplo.

Os endereços podem refletir locais precisos, como endereços, polilinhas, como rotas nomeadas, 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 usando este utilitário de geocodificação.

Observação: se você optar por especificar locais usando um método que exige geocodificação, como strings de endereço legíveis por humanos ou polilinhas, a solicitação será limitada a no máximo 15 locais. Esse limite se aplica apenas a locais que exigem geocodificação. Ele não se aplica a locais especificados com coordenadas de latitude/longitude.

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

Níveis de zoom

Os mapas no Google Maps têm um "nível de zoom" inteiro que define a resolução da visualização atual. Os níveis de zoom entre 0 (o menor nível de zoom, em que o mundo inteiro pode ser visto em um mapa) e 21+ (até ruas e edifícios individuais) são possíveis na visualização padrão de roadmap. Os contornos de edifícios, quando disponíveis, aparecem no mapa em torno do nível de zoom 17. Esse valor varia de acordo com a área e pode mudar ao longo do 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. Para mais informações sobre como fazer isso, consulte a documentação da API Maps JavaScript do Google Maps.

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

Se você enviar uma solicitação para um 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 detalhamento que você pode esperar em cada nível de zoom:

• 1: Mundo
• 5: terra/continente
• 10: cidade
• 15: ruas
• 20: construções

Este exemplo solicita dois mapas de Manhattan com o mesmo valor de center, mas com níveis de zoom 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, em conjunto com center, define a área de cobertura de um mapa. Ele também define o tamanho de 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 de scale.

scale=1	scale=2
640x640	640x640 (retorna 1280 x 1280 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 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. Assim, um mapa com size=200x200 será retornado como 200 x 200 pixels. Em um monitor de computador LCD, que normalmente exibe cerca de 100 pixels por polegada (ppi), um mapa de 200 x 200 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 pixels acima de 300 ppi, que:

• Reduzir o tamanho de uma imagem de 200 x 200 pixels para apenas 0,7 polegada, tornando os rótulos e ícones pequenos demais para serem lidos; ou
• Escalonar (ampliar) a imagem para melhorar a legibilidade, o que resulta em uma imagem desfocada ou pixelada.

Muito pequeno	Distorcida demais

Ao desenvolver para dispositivos móveis, use o parâmetro scale da API para retornar imagens de mapa de alta resolução que resolvem os problemas acima. O valor de scale é multiplicado por size para determinar o tamanho real de 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 vai retornar 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 estradas e rótulos, para que sejam legíveis em telas de alta resolução e tamanho pequeno, bem como quando dimensionadas 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 vai 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. Ele é exibido corretamente no computador, mas é muito pequeno para ser lido em um dispositivo móvel.
• A segunda dobra o tamanho do mapa. No computador, o CSS o ajusta ao elemento img de 100 x 100 especificado, mas, ao reduzir a imagem, as estradas e os rótulos ficam muito pequenos. No dispositivo móvel, a imagem tem o tamanho certo, mas as estradas e os rótulos estão ilegíveis.
• A terceira solicitação é para um mapa de 100 x 100 com scale=2. A imagem é retornada com 200 px de detalhes. O computador reduz a escala perfeitamente, de modo que ela fica indistinguível da solicitação original de 100 x 100, enquanto o navegador para dispositivos móveis se beneficia da resolução adicional retornada pela API.

Solicitações de imagem
Dispositivo	100x100	200x200	100x100&scale=2
Computador (com height="100px" e width="100px" na tag img)
Alta resolução (simulada)

Dica: as plataformas para dispositivos móveis, como Android e iOS, permitem que os apps sejam compatíveis com telas de alta resolução especificando imagens separadas para cada resolução. O parâmetro de escala facilita a solicitação de uma imagem de mapa para uma tela de resolução padrão e o mapa correspondente para uma tela de alta resolução, bastando definir scale=1 e scale=2, respectivamente.

Para mais informações sobre o desenvolvimento para dispositivos móveis e telas de alta resolução, recomendamos a leitura a seguir:

• Suporte para várias telas na documentação para desenvolvedores Android.
• Recomendações do Webkit.org para o desenvolvimento de sites de alta DPI.
• Suporte a telas de alta resolução na biblioteca de desenvolvedores 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 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.

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 geralmente fornecem o menor tamanho de imagem, mas fazem isso por meio de 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 grosseira antes 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 comum do JPEG atualmente. No entanto, alguns usos de JPEG exigem imagens não progressivas (linha de base). Nesses casos, use 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 vias padrão, como é normalmente mostrada no site do Google Maps. Se nenhum valor de maptype for especificado, a API Maps Static vai exibir blocos roadmap por padrão.
• satellite especifica uma imagem de satélite.
• terrain especifica uma imagem de mapa de relevo físico, mostrando terreno e vegetação.
• hybrid especifica um híbrido da imagem de satélite e do mapa, mostrando uma camada transparente das principais ruas e nomes de lugares na imagem de satélite.

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

  

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

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 de mapa) em um conjunto de locais. Cada marcador definido em uma única declaração markers precisa ter o mesmo estilo visual. Se você quiser exibir marcadores com estilos diferentes, forneça vários parâmetros markers com informações de estilo separadas.

O parâmetro markers usa um conjunto de atribuições de valor (descritores de marcador) no seguinte formato:

markers=markerStyles|markerLocation1| markerLocation2|... etc.

O conjunto de markerStyles é declarado no início da declaração markers e consiste em zero ou mais descritores de estilo separados pelo caractere de barra vertical (|), seguido por um conjunto de um ou mais locais também separados pelo caractere de barra vertical (|).

Como as informações de estilo e as informações de localização são delimitadas pelo caractere de barra vertical, as informações de estilo precisam aparecer primeiro em qualquer descritor de marcador. Depois que o servidor de API Maps Static encontra um local no descritor de 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 a serem usados ao exibir os marcadores dentro desse 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 vai aparecer no 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 compatíveis com marcadores, mas são compatíveis com caminhos.

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

Observação: em vez de usar esses marcadores, você pode usar seu próprio ícone personalizado. Para mais informações, consulte Ícones personalizados.

Dimensionamento de marcadores

O valor de 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 em imagens é aplicado depois 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 seja reduzido para menos de 4.096 pixels após o dimensionamento. Use o dimensionamento de marcadores com o dimensionamento de mapas ao exibir mapas de alta resolução.

Locais dos marcadores

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 os locais dos marcadores usando um método que exige geocodificação, como strings de endereço legíveis por humanos 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. Isso não se aplica aos 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 que contém os marcadores fornecidos. Consulte Posicionamento implícito.

Veja 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 azul com a letra "S" em 62.107733, -145.5419, um verde pequeno em "Delta Junction, AK" e um amarelo médio com a letra "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 marcador 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 dos serviços de encurtamento 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 especificados de markers. 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

É possível usar até cinco ícones personalizados exclusivos por solicitação. Essa limitação não significa que você só pode ter cinco locais marcados no mapa. Cada ícone exclusivo pode ser usado com mais de um local de markers no mapa.

Formato do ícone:

• As imagens de ícone podem estar nos formatos PNG, JPEG ou GIF, mas o PNG é 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 do 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.

Observe que os dois pontos de trajeto são separados um do outro usando o caractere de barra vertical (|). Como as informações de estilo e de ponto são delimitadas por esse caractere, as informações de estilo precisam aparecer primeiro em qualquer descritor de trajeto. Depois que 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 valor separadas pelo caractere de barra vertical (|). Esse descritor de estilo define os atributos visuais a serem usados ao exibir o trajeto. 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 trajeto vai aparecer com a espessura padrão (5 pixels).

• color: (opcional) especifica uma cor como um 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) e FF (completamente opaco). As transparências são aceitas em caminhos, mas não em 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 "fechado". O servidor de API Maps Static une automaticamente o primeiro e o último ponto. 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 é falso, o caminho é renderizado como uma linha reta no espaço da tela. O padrão é "falso".

Alguns exemplos de definições de caminho:

• Linha azul fina, 50% de opacidade: path=color:0x0000ff80|weight:1
• Linha vermelha contínua: path=color:0xff0000ff|weight:5
• Linha branca grossa e sólida: path=color:0xffffffff|weight:10

Esses estilos de caminho são opcionais. Se você quiser usar os atributos padrão, pule a definição dos atributos de caminho. Nesse caso, o primeiro "argumento" do descritor de caminho vai consistir no 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 | (barra vertical).

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

As especificações 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 a seguir define o mesmo caminho, mas com uma linha vermelha sólida com 100% de opacidade:

As especificações 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:

As especificações 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

Observe que definimos o caminho como invisível e a área poligonal como tendo 15% de opacidade.

Polilinhas codificadas

Em vez de uma série de locais, é possível declarar um caminho como uma polilinha codificada usando o prefixo enc: na declaração de local do path.

O exemplo a seguir mostra o trajeto da Alaska Highway de Dawson Creek, BC, até Delta Junction, AK, com uma polilinha codificada:

https://maps.googleapis.com/maps/api/staticmap
?size=400x400&center=59.900503,-135.478011&zoom=4
&path=weight:3%7Ccolor:orange%7Cenc:_fisIp~u%7CU%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

Assim como os caminhos padrão, os caminhos de polilinha codificada também podem demarcar áreas poligonais se um argumento fillcolor for transmitido ao 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:%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 janela de visualização definindo locais visíveis com o parâmetro visible. O parâmetro visible instrui o serviço da API Maps Static a criar um mapa em que os locais existentes permaneçam visíveis. Esse parâmetro também pode ser combinado com marcadores ou caminhos atuais 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, EUA, que contém o MIT e a Harvard Square em Cambridge, MA, EUA:

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

Posicionamento implícito do mapa

Normalmente, é necessário especificar os parâmetros de URL center e zoom para definir o local e o nível de zoom do mapa gerado. No entanto, se você fornecer os parâmetros markers, path ou visible, poderá permitir que a API Maps Static determine o centro e o nível de zoom corretos de forma implícita, com base na avaliação da posição desses elementos.

Se você fornecer dois ou mais elementos, a API Maps Static vai determinar um centro e um nível de zoom adequados, oferecendo margens generosas para os elementos contidos. Este exemplo mostra um mapa com San Francisco, Oakland e San Jose, CA:

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

Tamanhos de imagem maiores

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

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

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 é 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 der errado. Verifique se há avisos, principalmente se você notar que algo está faltando no mapa. Também é uma boa ideia 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.