Incorporação de mapas

Este guia mostra como incorporar um mapa interativo à sua página da Web.

Como criar o URL da API Maps Embed

Confira abaixo um exemplo de URL que carrega a API Maps Embed:

https://www.google.com/maps/embed/v1/MAP_MODE?key=YOUR_API_KEY&PARAMETERS

Substitua:

  • MAP_MODE com o modo de mapa.
  • YOUR_API_KEY com sua chave de API. Para mais informações, consulte Acessar a chave de API.
  • PARAMETERS com os parâmetros obrigatórios e opcionais para o modo de mapa.

Adicionar o URL a um iframe

Para usar a API Maps Embed na sua página da Web, defina o URL criado como o valor do atributo src de um iframe. Controle o tamanho do mapa com os atributos height e width do iframe, por exemplo:

<iframe
  width="450"
  height="250"
  frameborder="0" style="border:0"
  referrerpolicy="no-referrer-when-downgrade"
  src="https://www.google.com/maps/embed/v1/MAP_MODE?key=YOUR_API_KEY&PARAMETERS"
  allowfullscreen>
</iframe>

O exemplo de iframe acima usa as propriedades adicionais:

  • A propriedade allowfullscreen para permitir que determinadas partes do mapa sejam exibidas em tela cheia.
  • As propriedades frameborder="0" e style="border:0" para remover a borda padrão do iframe ao redor do mapa.
  • A propriedade referrerpolicy="no-referrer-when-downgrade" para permitir que o navegador envie o URL completo como o cabeçalho Referer com a solicitação para que as restrições da chave de API funcionem corretamente.

Você pode redimensionar o iframe para se adequar à estrutura e ao design do seu site, mas os visitantes geralmente acham mais fácil interagir com mapas maiores. Os mapas incorporados não são aceitos com tamanhos abaixo de 200 px em nenhuma dimensão.

Restrições da chave de API

Se o site de hospedagem tiver uma metatag referrer definida como no-referrer ou same-origin, o navegador não enviará o cabeçalho Referer ao Google. Isso pode fazer com que a restrição da chave de API rejeite as solicitações. Para que a restrição funcione corretamente, adicione uma propriedade referrerpolicy ao iframe, como no exemplo acima, para permitir explicitamente que os cabeçalhos Referer sejam enviados ao Google.

Anúncios no mapa

A API Maps Embed pode incluir publicidade no mapa. O formato do anúncio e o conjunto de anúncios mostrados em qualquer mapa podem mudar sem aviso prévio.

Como escolher os modos de mapa

É possível especificar um dos seguintes modos de mapa para usar no URL da solicitação:

  • place: mostra um alfinete em um lugar ou endereço específico, como um marco, empresa, elemento geográfico ou cidade.
  • view: retorna um mapa sem marcadores nem direções.
  • directions: mostra o caminho entre dois ou mais pontos especificados no mapa, além da distância e do tempo de percurso.
  • streetview: mostra visualizações panorâmicas interativas de locais designados.
  • search: mostra os resultados de uma pesquisa na região do mapa visível.

Modo place

O URL a seguir usa o modo de mapa place para mostrar um marcador na Torre Eiffel:

https://www.google.com/maps/embed/v1/place
  ?key=YOUR_API_KEY
  &q=Eiffel+Tower,Paris+France

Use os seguintes parâmetros:

Parâmetro Tipo Descrição Valores aceitos
q Obrigatório Define a localização do marcador no mapa. Nome, endereço, Plus Code ou ID do lugar com codificação de URL. A API Maps Embed oferece suporte a + e %20 ao escapar de espaços. Por exemplo, converta "City Hall, New York, NY" em City+Hall,New+York,NY ou os códigos Plus "849VCWC8+R9" em 849VCWC8%2BR9.
center Opcional Define o centro da visualização do mapa. Aceita valores de latitude e longitude separados por vírgulas. Por exemplo: 37.4218,-122.0840.
zoom Opcional Define o nível de zoom inicial do mapa. Valores que variam de 0 (o mundo todo) a 21 (edifícios individuais). O limite máximo pode variar dependendo dos dados do mapa disponíveis no local selecionado.
maptype Opcional Define o tipo de blocos de mapa a serem carregados. roadmap (padrão) ou satellite
language Opcional Define o idioma a ser usado para elementos da interface e para a exibição de rótulos nos blocos de mapa. Por padrão, os visitantes vão ver um mapa no próprio idioma. Esse parâmetro é compatível apenas com alguns blocos de países. Se o idioma específico solicitado não for compatível com o conjunto de blocos, o idioma padrão desse conjunto será usado.
region Opcional Define as bordas e os rótulos adequados a serem exibidos com base nas sensibilidades geopolíticas. Aceita um código regional especificado como uma subtag de região Unicode de dois caracteres (não numéricos) mapeada para valores de dois caracteres de ccTLDs ("domínio de nível superior") conhecidos. Consulte os detalhes da cobertura da Plataforma Google Maps para conferir as regiões com suporte.

Modo view

O exemplo a seguir usa o modo view e o parâmetro opcional maptype para mostrar uma vista de satélite do mapa:

https://www.google.com/maps/embed/v1/view
  ?key=YOUR_API_KEY
  &center=-33.8569,151.2152
  &zoom=18
  &maptype=satellite

Use os seguintes parâmetros:

Parâmetro Tipo Descrição Valores aceitos
center Obrigatório Define o centro da visualização do mapa. Aceita valores de latitude e longitude separados por vírgulas. Por exemplo: 37.4218,-122.0840.
zoom Opcional Define o nível de zoom inicial do mapa. Valores que variam de 0 (o mundo todo) a 21 (edifícios individuais). O limite máximo pode variar dependendo dos dados do mapa disponíveis no local selecionado.
maptype Opcional Define o tipo de blocos de mapa a serem carregados. roadmap (padrão) ou satellite
language Opcional Define o idioma a ser usado para elementos da interface e para a exibição de rótulos nos blocos de mapa. Por padrão, os visitantes vão ver um mapa no próprio idioma. Esse parâmetro é compatível apenas com alguns blocos de países. Se o idioma específico solicitado não for compatível com o conjunto de blocos, o idioma padrão desse conjunto será usado.
region Opcional Define as bordas e os rótulos adequados a serem exibidos com base nas sensibilidades geopolíticas. Aceita um código regional especificado como uma subtag de região Unicode de dois caracteres (não numéricos) mapeada para valores de dois caracteres de ccTLDs ("domínio de nível superior") conhecidos. Consulte os detalhes da cobertura da Plataforma Google Maps para conferir as regiões com suporte.

Modo directions

O exemplo a seguir usa o modo directions para mostrar o caminho entre Oslow e Telemark, na Noruega, a distância e o tempo de viagem evitando pedágios e rodovias.

https://www.google.com/maps/embed/v1/directions
  ?key=YOUR_API_KEY
  &origin=Oslo+Norway
  &destination=Telemark+Norway
  &avoid=tolls|highways

Use os seguintes parâmetros:

Parâmetro Tipo Descrição Valores aceitos
origin Obrigatório Define o ponto de partida para mostrar as direções. Nome do lugar, endereço, código Plus, coordenadas de latitude/longitude ou ID do lugar com codificação de URL. A API Maps Embed oferece suporte a + e %20 ao escapar de espaços. Por exemplo, converta "City Hall, New York, NY" em City+Hall,New+York,NY ou os códigos Plus "849VCWC8+R9" em 849VCWC8%2BR9.
destination Obrigatório Define o ponto final das direções. Nome do lugar, endereço, código Plus, coordenadas de latitude/longitude ou ID do lugar com codificação de URL. A API Maps Embed oferece suporte a + e %20 ao escapar de espaços. Por exemplo, converta "City Hall, New York, NY" em City+Hall,New+York,NY ou os códigos Plus "849VCWC8+R9" em 849VCWC8%2BR9.
waypoints Opcional Especifica um ou mais lugares intermediários para rotear direções entre a origem e o destino. Nome, endereço ou ID do lugar. É possível especificar vários pontos de passagem usando o caractere de barra (|) para separar os lugares (por exemplo, Berlin,Germany|Paris,France). É possível especificar até 20 pontos de passagem.
mode Opcional Define o método de viagem. Se nenhum modo for especificado, a API Embed do Maps vai mostrar um ou mais dos modos mais relevantes para o trajeto especificado. driving, walking (que prefere caminhos e calçadas para pedestres, quando disponíveis), bicycling (que faz rotas por ciclovias e ruas preferenciais, quando disponíveis), transit ou flying.
avoid Opcional Especifica os recursos a serem evitados nas direções. Isso não impede rotas que incluem os recursos restritos. Em vez disso, o resultado é direcionado para rotas mais favoráveis. tolls, ferries e/ou highways. Separe vários valores com o caractere de barra (por exemplo, avoid=tolls|highways).
units Opcional Especifica o método de medição, métrica ou imperial, ao mostrar distâncias nos resultados. Se units não forem especificados, o país origin da consulta vai determinar as unidades a serem usadas. metric ou imperial
center Opcional Define o centro da visualização do mapa. Aceita valores de latitude e longitude separados por vírgulas. Por exemplo: 37.4218,-122.0840.
zoom Opcional Define o nível de zoom inicial do mapa. Valores que variam de 0 (o mundo todo) a 21 (edifícios individuais). O limite máximo pode variar dependendo dos dados do mapa disponíveis no local selecionado.
maptype Opcional Define o tipo de blocos de mapa a serem carregados. roadmap (padrão) ou satellite
language Opcional Define o idioma a ser usado para elementos da interface e para a exibição de rótulos nos blocos de mapa. Por padrão, os visitantes vão ver um mapa no próprio idioma. Esse parâmetro é compatível apenas com alguns blocos de países. Se o idioma específico solicitado não for compatível com o conjunto de blocos, o idioma padrão desse conjunto será usado.
region Opcional Define as bordas e os rótulos adequados a serem exibidos com base nas sensibilidades geopolíticas. Aceita um código regional especificado como uma subtag de região Unicode de dois caracteres (não numéricos) mapeada para valores de dois caracteres de ccTLDs ("domínio de nível superior") conhecidos. Consulte os detalhes da cobertura da Plataforma Google Maps para conferir as regiões com suporte.

Modo streetview

A API Embed do Maps permite exibir imagens do Street View como panoramas interativos de locais designados em toda a área de cobertura. As Photospheres enviadas por usuários e as coleções especiais do Street View também estão disponíveis.

Cada panorama do Street View oferece uma vista completa de 360 graus de um único local. As imagens contêm 360 graus de visualização horizontal (uma volta completa) e 180 graus de visualização vertical (de cima para baixo). O modo streetview fornece um visualizador que renderiza o panorama resultante como uma esfera com uma câmera no centro. É possível manipular a câmera para controlar o zoom e a orientação dela.

Confira o panorama do modo streetview a seguir:

https://www.google.com/maps/embed/v1/streetview
  ?key=YOUR_API_KEY
  &location=46.414382,10.013988
  &heading=210
  &pitch=10
  &fov=35

Um dos seguintes parâmetros de URL é obrigatório:

  • location aceita uma latitude e uma longitude como valores separados por vírgula (46.414382,10.013988). A API vai mostrar o panorama fotografado mais próximo a esse local. Como as imagens do Street View são atualizadas periodicamente e as fotos podem ser tiradas de posições ligeiramente diferentes a cada vez, é possível que seu local seja fixado em um panorama diferente quando as imagens forem atualizadas.

  • pano é um ID de panorama específico. Se você especificar um pano, também poderá especificar um location. O location só será usado se a API não conseguir encontrar o ID do panorama.

Os seguintes parâmetros de URL são opcionais:

Parâmetro Tipo Descrição Valores aceitos
heading Opcional Indica a direção da bússola da câmera em graus no sentido horário a partir do norte. Valor em graus de -180° a 360°
pitch Opcional especifica o ângulo, para cima ou para baixo, da câmera. Valores positivos inclinam a câmera para cima, e valores negativos inclinam a câmera para baixo. O ângulo padrão de 0° é definido com base na posição da câmera quando a imagem foi capturada. Por isso, um ângulo de 0° é muitas vezes, mas nem sempre, horizontal. Por exemplo, uma imagem tirada em uma colina provavelmente vai mostrar um ângulo padrão que não é horizontal. Valor em graus de -90° a 90°
fov Opcional determina o campo de visão horizontal da imagem. O valor padrão é 90°. Ao lidar com uma viewport de tamanho fixo, o campo de visão pode ser considerado o nível de zoom, com números menores indicando um nível mais alto de zoom. Valor em graus, com um intervalo de 10° a 100°
center Opcional Define o centro da visualização do mapa. Aceita valores de latitude e longitude separados por vírgulas. Por exemplo: 37.4218,-122.0840.
zoom Opcional Define o nível de zoom inicial do mapa. Valores que variam de 0 (o mundo todo) a 21 (edifícios individuais). O limite máximo pode variar dependendo dos dados do mapa disponíveis no local selecionado.
maptype Opcional Define o tipo de blocos de mapa a serem carregados. roadmap (padrão) ou satellite
language Opcional Define o idioma a ser usado para elementos da interface e para a exibição de rótulos nos blocos de mapa. Por padrão, os visitantes vão ver um mapa no próprio idioma. Esse parâmetro é compatível apenas com alguns blocos de países. Se o idioma específico solicitado não for compatível com o conjunto de blocos, o idioma padrão desse conjunto será usado.
region Opcional Define as bordas e os rótulos adequados a serem exibidos com base nas sensibilidades geopolíticas. Aceita um código regional especificado como uma subtag de região Unicode de dois caracteres (não numéricos) mapeada para valores de dois caracteres de ccTLDs ("domínio de nível superior") conhecidos. Consulte os detalhes da cobertura da Plataforma Google Maps para conferir as regiões com suporte.

Modo search

O modo Search mostra os resultados de uma pesquisa na região visível do mapa. É recomendável definir um local para a pesquisa, seja incluindo um local no termo de pesquisa (record+stores+in+Seattle) ou incluindo um parâmetro center e zoom para limitar a pesquisa.

https://www.google.com/maps/embed/v1/search
  ?key=YOUR_API_KEY
  &q=record+stores+in+Seattle

Use os seguintes parâmetros:

Parâmetro Tipo Descrição Valores aceitos
q Obrigatório Define o termo de pesquisa. Ela pode incluir uma restrição geográfica, como in+Seattle ou near+98033.
center Opcional Define o centro da visualização do mapa. Aceita valores de latitude e longitude separados por vírgulas. Por exemplo: 37.4218,-122.0840.
zoom Opcional Define o nível de zoom inicial do mapa. Valores que variam de 0 (o mundo todo) a 21 (edifícios individuais). O limite máximo pode variar dependendo dos dados do mapa disponíveis no local selecionado.
maptype Opcional Define o tipo de blocos de mapa a serem carregados. roadmap (padrão) ou satellite
language Opcional Define o idioma a ser usado para elementos da interface e para a exibição de rótulos nos blocos de mapa. Por padrão, os visitantes vão ver um mapa no próprio idioma. Esse parâmetro é compatível apenas com alguns blocos de países. Se o idioma específico solicitado não for compatível com o conjunto de blocos, o idioma padrão desse conjunto será usado.
region Opcional Define as bordas e os rótulos adequados a serem exibidos com base nas sensibilidades geopolíticas. Aceita um código regional especificado como uma subtag de região Unicode de dois caracteres (não numéricos) mapeada para valores de dois caracteres de ccTLDs ("domínio de nível superior") conhecidos. Consulte os detalhes da cobertura da Plataforma Google Maps para conferir as regiões com suporte.

Parâmetros do ID do lugar

A API Maps Embed oferece suporte ao uso de IDs de lugar em vez de fornecer um nome ou endereço de lugar. Os IDs de lugares são uma maneira estável de identificar um lugar de forma exclusiva. Para saber mais, consulte a documentação da API Google Places.

A API Maps Embed aceita IDs de lugares para os seguintes parâmetros de URL:

  • q
  • origin
  • destination
  • waypoints

Para usar um ID de lugar, primeiro adicione o prefixo place_id:. O código a seguir especifica o New York City Hall como a origem de uma solicitação de direções: origin=place_id:ChIJs--MqP1YwokRBwAhjXWIHn8.

  • radius: define um raio, em metros, para procurar um panorama, com o centro na latitude e longitude fornecidas. Os valores válidos são números inteiros não negativos. O valor padrão é 50.

  • source: limita as pesquisas do Street View a fontes selecionadas. Os valores válidos são:

    • default: usa as fontes padrão do Street View. As pesquisas não são limitadas a origens específicas.
    • outdoor: limita as pesquisas a coleções ao ar livre. As coleções em ambientes fechados não são incluídas nos resultados da pesquisa. e pode ser que não existam panoramas externos para o local especificado. Além disso, a pesquisa só retorna panoramas em que é possível determinar se eles estão em ambientes internos ou externos. Por exemplo, as PhotoSpheres não são retornadas porque não se sabe se elas estão em ambientes internos ou externos.