Incorporar um mapa

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

Criar o URL da API Maps Embed

Veja a seguir 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 mapa.
  • YOUR_API_KEY pela sua chave de API. Para mais informações, consulte Acessar chave de API.
  • PARAMETERS com os parâmetros obrigatórios e opcionais para o modo mapa.

Adicionar o URL a um iframe

Para usar a API Maps Embed na sua página da Web, defina o URL que você criou 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="strict-origin-when-cross-origin"
  src="https://www.google.com/maps/embed/v1/MAP_MODE?key=YOUR_API_KEY&PARAMETERS"
  allowfullscreen>
</iframe>

O exemplo de iframe acima usa as seguintes 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="strict-origin-when-cross-origin" garante que o navegador envie o domínio do seu site como o cabeçalho Referer para o Google. Isso permite que as restrições da chave de API validem a solicitação, mantendo a privacidade dos caminhos específicos da página.

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 compatíveis com tamanhos menores que 200 px em qualquer dimensão.

Informações do referenciador e restrições de chave de API

Se o site de hospedagem tiver uma metatag referrer definida como no-referrer ou same-origin, o navegador não vai 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.

  • strict-origin-when-cross-origin (recomendado): envia apenas seu domínio base (por exemplo, https://example.com/) para o Google. Isso mantém os caminhos de página específicos privados, mas permite que as restrições de chave de API funcionem.
  • no-referrer-when-downgrade (legado): envia o URL inteiro, incluindo caminhos de página específicos e parâmetros de consulta (por exemplo, https://example.com/contact?user=123).

Saiba mais sobre o cabeçalho Referrer-Policy.

Escolher os modos de mapa

Você pode especificar um dos seguintes modos mapa para usar no URL da solicitação:

  • place: mostra um alfinete do mapa em um lugar ou endereço específico, como um ponto de referência, uma empresa, uma característica geográfica ou uma cidade.
  • view: retorna um mapa sem marcadores ou rotas.
  • directions: mostra o caminho entre dois ou mais pontos especificados no mapa, além da distância e do tempo de viagem.
  • streetview: mostra vistas panorâmicas interativas de locais designados.
  • search: mostra os resultados de uma pesquisa na região visível do mapa.

Modo place

O URL a seguir usa o modo mapa place para mostrar um marcador do mapa 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 o local do marcador do mapa. Nome do lugar, endereço, Plus Code ou ID de lugar com escape de URL. A API Maps Embed aceita + e %20 ao usar caracteres de escape em espaços. Por exemplo, converta "City Hall, New York, NY" em City+Hall,New+York,NY ou Plus Codes "849VCWC8+R9" em 849VCWC8%2BR9.
center Opcional Define o centro da visualização do mapa. Aceita valores de latitude e longitude separados por vírgula. Por exemplo: 37.4218,-122.0840.
zoom Opcional Define o nível de zoom inicial do mapa. Os valores variam de 0 (o mundo inteiro) a 21 (edifícios individuais). O limite máximo pode variar de acordo com os dados do mapa disponíveis no local selecionado.
maptype Opcional Define o tipo de bloco de mapa a ser carregado. 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 em blocos de mapa. Por padrão, os visitantes verão um mapa no próprio idioma. 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 e os rótulos adequados para exibição, com base em sensibilidades geopolíticas. Aceita um código de região especificado como uma subtag de região Unicode de dois caracteres (não numéricos) que mapeia para valores de dois caracteres de ccTLD ("domínio de nível superior") familiares. Consulte os detalhes de cobertura da Plataforma Google Maps para ver as regiões com disponibilidade.

Modo view

O exemplo a seguir usa o modo view e o parâmetro opcional maptype para mostrar uma visualização 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írgula. Por exemplo: 37.4218,-122.0840.
zoom Opcional Define o nível de zoom inicial do mapa. Os valores variam de 0 (o mundo inteiro) a 21 (edifícios individuais). O limite máximo pode variar de acordo com os dados do mapa disponíveis no local selecionado.
maptype Opcional Define o tipo de bloco de mapa a ser carregado. 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 em blocos de mapa. Por padrão, os visitantes verão um mapa no próprio idioma. 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 e os rótulos adequados para exibição, com base em sensibilidades geopolíticas. Aceita um código de região especificado como uma subtag de região Unicode de dois caracteres (não numéricos) que é mapeada para valores de dois caracteres de ccTLD ("domínio de nível superior") conhecidos. Consulte os detalhes de cobertura da Plataforma Google Maps para ver as regiões com disponibilidade.

Modo directions

O exemplo a seguir usa o modo directions para mostrar o trajeto entre Oslo 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 rotas. Nome do lugar com escape de URL, endereço, Plus Code, coordenadas de latitude/longitude ou ID de lugar. A API Maps Embed aceita + e %20 ao usar caracteres de escape em espaços. Por exemplo, converta "City Hall, New York, NY" em City+Hall,New+York,NY ou Plus Codes "849VCWC8+R9" em 849VCWC8%2BR9.
destination Obrigatório Define o endpoint das rotas. Nome do lugar, endereço, Plus Code, coordenadas de latitude/longitude ou ID de lugar com escape de URL. A API Maps Embed aceita + e %20 ao usar caracteres de escape em espaços. Por exemplo, converta "City Hall, New York, NY" em City+Hall,New+York,NY ou Plus Codes "849VCWC8+R9" em 849VCWC8%2BR9.
waypoints Opcional Especifica um ou mais lugares intermediários para traçar rotas entre a origem e o destino. Nome, endereço ou ID de lugar. É possível especificar vários pontos de referência usando o caractere de barra vertical (|) para separar lugares (por exemplo, Berlin,Germany|Paris,France). Você pode especificar até 20 pontos de referência.
mode Opcional Define o meio de transporte. Se nenhum modo for especificado, a API Maps Embed vai mostrar um ou mais dos modos mais relevantes para o trajeto especificado. driving, walking (que prioriza caminhos de pedestres e calçadas, quando disponíveis), bicycling (que prioriza trajetos com ciclovias e ruas preferenciais, quando disponíveis), transit ou flying.
avoid Opcional Especifica recursos que devem ser evitados nas rotas. Isso não impede rotas que incluam os recursos restritos, mas prioriza resultados com rotas mais favoráveis. tolls, ferries e/ou highways. Separe vários valores com o caractere de barra vertical (por exemplo, avoid=tolls|highways).
units Opcional Especifica o método de medição, métrico ou imperial, ao exibir 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írgula. Por exemplo: 37.4218,-122.0840.
zoom Opcional Define o nível de zoom inicial do mapa. Os valores variam de 0 (o mundo inteiro) a 21 (edifícios individuais). O limite máximo pode variar de acordo com os dados do mapa disponíveis no local selecionado.
maptype Opcional Define o tipo de bloco de mapa a ser carregado. 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 em blocos de mapa. Por padrão, os visitantes verão um mapa no próprio idioma. 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 e os rótulos adequados para exibição, com base em sensibilidades geopolíticas. Aceita um código de região especificado como uma subtag de região Unicode de dois caracteres (não numéricos) que mapeia para valores de dois caracteres de ccTLD ("domínio de nível superior") familiares. Consulte os detalhes de cobertura da Plataforma Google Maps para ver as regiões com disponibilidade.

Modo streetview

Com a API Maps Embed, você pode mostrar imagens do Street View como panoramas interativos de locais designados em toda a área de cobertura. Photospheres enviadas por usuários e coleções especiais do Street View também estão disponíveis.

Cada panorama do Street View oferece uma visualização completa em 360 graus de um único local. As imagens contêm 360 graus de visualização horizontal (uma volta completa ao redor de um ponto) e 180 graus de visualização vertical (do ponto mais alto ao mais 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 seguinte panorama do modo streetview:

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írgulas (46.414382,10.013988). A API mostra o panorama fotografado mais próximo desse 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 ajustado para 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 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, enquanto valores negativos a inclinam para baixo. A inclinação padrão de 0° é definida com base na posição da câmera quando a imagem foi capturada. Por isso, uma inclinação de 0° é frequentemente, mas nem sempre, horizontal. Por exemplo, uma imagem capturada em uma colina provavelmente tem um valor padrão de inclinação que não é horizontal. Valor em graus de -90° a 90°
fov Opcional determina o campo de visão horizontal da imagem. O padrão é 90°. Ao lidar com uma janela de visualização de tamanho fixo, o campo de visão pode ser considerado o nível de zoom, com números menores indicando um nível de zoom maior. 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írgula. Por exemplo: 37.4218,-122.0840.
zoom Opcional Define o nível de zoom inicial do mapa. Os valores variam de 0 (o mundo inteiro) a 21 (edifícios individuais). O limite máximo pode variar de acordo com os dados do mapa disponíveis no local selecionado.
maptype Opcional Define o tipo de bloco de mapa a ser carregado. 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 em blocos de mapa. Por padrão, os visitantes verão um mapa no próprio idioma. 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 e os rótulos adequados para exibição, com base em sensibilidades geopolíticas. Aceita um código de região especificado como uma subtag de região Unicode de dois caracteres (não numéricos) que mapeia para valores de dois caracteres de ccTLD ("domínio de nível superior") familiares. Consulte os detalhes de cobertura da Plataforma Google Maps para ver as regiões com disponibilidade.

Modo search

O modo Search mostra os resultados de uma pesquisa na região visível do mapa. Recomendamos 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. Ele 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írgula. Por exemplo: 37.4218,-122.0840.
zoom Opcional Define o nível de zoom inicial do mapa. Os valores variam de 0 (o mundo inteiro) a 21 (edifícios individuais). O limite máximo pode variar de acordo com os dados do mapa disponíveis no local selecionado.
maptype Opcional Define o tipo de bloco de mapa a ser carregado. 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 em blocos de mapa. Por padrão, os visitantes verão um mapa no próprio idioma. 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 e os rótulos adequados para exibição, com base em sensibilidades geopolíticas. Aceita um código de região especificado como uma subtag de região Unicode de dois caracteres (não numéricos) que é mapeada para valores de dois caracteres de ccTLD ("domínio de nível superior") conhecidos. Consulte os detalhes de cobertura da Plataforma Google Maps para ver as regiões com disponibilidade.

Parâmetros de ID de lugar

A API Maps Embed permite usar IDs de lugar em vez de fornecer um nome ou endereço de lugar. Os IDs de lugar são uma forma estável de identificar um lugar de maneira exclusiva. Para mais informações, consulte a documentação da API Places (nova).

A API Maps Embed aceita IDs de lugar 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 a Prefeitura de Nova York como a origem de uma solicitação de rotas: 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 às fontes selecionadas. Os valores válidos são:

    • default: usa as fontes padrão do Street View, sem limitar a pesquisa a origens específicas.
    • outdoor: limita as pesquisas a coleções ao ar livre. As coleções internas não são incluídas nos resultados da pesquisa. É possível 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 são internos ou externos. Por exemplo, PhotoSpheres não são retornadas porque não se sabe se elas estão em ambientes internos ou externos.