Incorporação de mapas

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

Criar o URL da API Maps Embed

Este é 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 pelo modo de mapa.
  • YOUR_API_KEY pela chave de API. Para mais informações, consulte Gerar 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 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="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 permite 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" permite que o navegador envie o URL completo como o cabeçalho Referer com a solicitação. Assim, as restrições da chave de API podem funcionar corretamente.

Você pode redimensionar o iframe para se adaptar à estrutura e ao design do seu site, mas descobrimos que os visitantes geralmente acham mais fácil interagir com mapas maiores. Em qualquer uma das dimensões, não é possível incluir mapas com menos de 200 px.

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 vai enviar o cabeçalho Referer ao Google. Isso pode fazer com que sua restrição de 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 o envio dos cabeçalhos Referer ao Google.

Anúncios no mapa

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

Escolher modos de mapa

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

  • place: mostra um alfinete no mapa em um lugar ou endereço específico, como um ponto de referência, empresa, elemento geográfico ou 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 de mapa place para exibir 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 o local do marcador do mapa. Nome, endereço, Plus Code ou ID de lugar com escape de URL. A API Maps Embed aceita + e %20 ao fazer escape de espaços. Por exemplo, converta "Prefeitura, Nova York, NY" para City+Hall,New+York,NY, ou os plus codes "849VCWC8+R9" em 849VCWC8%2BR9.
center Opcional Define o centro da visualização de 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. Valores que 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 blocos de mapa a serem carregados. roadmap (padrão) ou satellite
language Opcional Define o idioma a ser usado nos elementos da interface e na exibição de rótulos nos blocos do mapa. Por padrão, os visitantes veem um mapa no próprio idioma. 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, o idioma padrão dele será usado.
region Opcional Define as fronteiras e rótulos apropriados a serem mostrados, com base em particularidades geopolíticas. Aceita um código de região especificado como um mapeamento de subtag de região Unicode de dois caracteres (não numéricos) para valores familiares de ccTLD ("domínio de nível superior") de dois caracteres. Confira os detalhes da cobertura da Plataforma Google Maps para saber quais são as regiões aceitas.

Modo view

O exemplo a seguir usa o modo view e o parâmetro maptype opcional 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 de 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. Valores que 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 blocos de mapa a serem carregados. roadmap (padrão) ou satellite
language Opcional Define o idioma a ser usado nos elementos da interface e na exibição de rótulos nos blocos do mapa. Por padrão, os visitantes veem um mapa no próprio idioma. 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, o idioma padrão dele será usado.
region Opcional Define as fronteiras e rótulos apropriados a serem mostrados, com base em particularidades geopolíticas. Aceita um código de região especificado como um mapeamento de subtag de região Unicode de dois caracteres (não numéricos) para valores familiares de ccTLD ("domínio de nível superior") de dois caracteres. Confira os detalhes da cobertura da Plataforma Google Maps para saber quais são as regiões aceitas.

Modo directions

O exemplo a seguir usa o modo directions para exibir o caminho entre Oslow e Telemark, 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 a partir do qual as rotas devem ser exibidas. Nome do lugar com escape de URL, endereço, código, coordenadas de latitude/longitude ou ID do lugar. A API Maps Embed aceita + e %20 ao fazer escape de espaços. Por exemplo, converta "Prefeitura, Nova York, NY" para City+Hall,New+York,NY, ou os plus codes "849VCWC8+R9" em 849VCWC8%2BR9.
destination Obrigatório Define o ponto final da rota. Nome do lugar com escape de URL, endereço, código, coordenadas de latitude/longitude ou ID do lugar. A API Maps Embed aceita + e %20 ao fazer escape de espaços. Por exemplo, converta "Prefeitura, Nova York, NY" para City+Hall,New+York,NY, ou os plus codes "849VCWC8+R9" em 849VCWC8%2BR9.
waypoints Opcional Especifica um ou mais locais intermediários para criar rotas entre a origem e o destino. Nome, endereço ou ID do lugar. É possível especificar vários waypoints usando a barra vertical (|) para separar lugares (por exemplo, Berlin,Germany|Paris,France). É possível especificar até 20 waypoints.
mode Opcional Define o meio de transporte. Se nenhum modo for especificado, a API Maps Embed mostrará um ou mais dos modos mais relevantes para o trajeto especificado. driving, walking (que dá preferência a vias para pedestres e calçadas, quando disponível), bicycling (que usa ciclovias e ruas preferenciais, quando disponíveis), transit ou flying.
avoid Opcional Especifica os recursos que devem ser evitados nas rotas. Isso não exclui os trajetos que incluem os elementos restritos. Isso direciona o resultado para trajetos mais favoráveis. tolls, ferries e/ou highways. Separe diversos 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 for especificado, o origin país da consulta vai determinar as unidades a serem usadas. metric ou imperial
center Opcional Define o centro da visualização de 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. Valores que 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 blocos de mapa a serem carregados. roadmap (padrão) ou satellite
language Opcional Define o idioma a ser usado nos elementos da interface e na exibição de rótulos nos blocos do mapa. Por padrão, os visitantes veem um mapa no próprio idioma. 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, o idioma padrão dele será usado.
region Opcional Define as fronteiras e rótulos apropriados a serem mostrados, com base em particularidades geopolíticas. Aceita um código de região especificado como um mapeamento de subtag de região Unicode de dois caracteres (não numéricos) para valores familiares de ccTLD ("domínio de nível superior") de dois caracteres. Confira os detalhes da cobertura da Plataforma Google Maps para saber quais são as regiões aceitas.

Modo streetview

A API Maps Embed permite mostrar imagens do Street View como panoramas interativos de locais designados em toda a área de cobertura. Fotosferas contribuídas 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 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.

Veja 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írgula (46.414382,10.013988). A API exibe o panorama fotografado mais próximo desse local. Como as imagens do Street View são atualizadas periodicamente e as fotografias podem ter sido tiradas em posições ligeiramente diferentes a cada vez, é possível que seu local passe para outro panorama 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ó é usado se a API não consegue 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 vertical da câmera. Valores positivos inclinam a câmera para cima, enquanto valores negativos a inclinam para baixo. O valor padrão de 0° é definido com base na posição da câmera quando a imagem foi capturada. Por isso, uma inclinação de 0° costuma ser horizontal, mas não sempre. Por exemplo, uma imagem capturada em uma colina provavelmente terá um valor padrão de inclinação 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 trabalhar 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 maior de zoom. Valor em graus, com um intervalo de 10° a 100°
center Opcional Define o centro da visualização de 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. Valores que 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 blocos de mapa a serem carregados. roadmap (padrão) ou satellite
language Opcional Define o idioma a ser usado nos elementos da interface e na exibição de rótulos nos blocos do mapa. Por padrão, os visitantes veem um mapa no próprio idioma. 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, o idioma padrão dele será usado.
region Opcional Define as fronteiras e rótulos apropriados a serem mostrados, com base em particularidades geopolíticas. Aceita um código de região especificado como um mapeamento de subtag de região Unicode de dois caracteres (não numéricos) para valores familiares de ccTLD ("domínio de nível superior") de dois caracteres. Confira os detalhes da cobertura da Plataforma Google Maps para saber quais são as regiões aceitas.

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 incluindo-o 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. Isso pode incluir uma restrição geográfica, como in+Seattle ou near+98033.
center Opcional Define o centro da visualização de 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. Valores que 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 blocos de mapa a serem carregados. roadmap (padrão) ou satellite
language Opcional Define o idioma a ser usado nos elementos da interface e na exibição de rótulos nos blocos do mapa. Por padrão, os visitantes veem um mapa no próprio idioma. 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, o idioma padrão dele será usado.
region Opcional Define as fronteiras e rótulos apropriados a serem mostrados, com base em particularidades geopolíticas. Aceita um código de região especificado como um mapeamento de subtag de região Unicode de dois caracteres (não numéricos) para valores familiares de ccTLD ("domínio de nível superior") de dois caracteres. Confira os detalhes da cobertura da Plataforma Google Maps para saber quais são as regiões aceitas.

Parâmetros de ID do lugar

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

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 origem de uma solicitação de rotas: origin=place_id:ChIJs--MqP1YwokRBwAhjXWIHn8.

  • radius define um raio, especificado em metros, para pesquisar um panorama, centralizado na latitude e longitude indicadas. Os valores válidos são números inteiros não negativos. O valor padrão é 50.

  • O source limita as pesquisas do Street View às origens selecionadas. Os valores válidos são:

    • default usa as origens padrão do Street View. As pesquisas não se limitam a origens específicas.
    • outdoor: limita as pesquisas a coleções ao ar livre. Coleções internas não são incluídas nos resultados da pesquisa. e podem não existir panoramas externos para o local especificado. A pesquisa só retorna panoramas quando é possível determinar se eles estão em ambientes internos ou externos. Por exemplo, PhotoSpheres não são retornados porque não se sabe se estão em ambientes internos ou externos.