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

Veja a seguir um URL de exemplo que carrega a API incorporada do Google Maps:

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 pelos parâmetros obrigatórios e opcionais para o modo de mapa.

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

A amostra 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 em torno do mapa.
• A propriedade referrerpolicy="no-referrer-when-downgrade" para permitir que o navegador envie o URL completo como cabeçalho Referer com a solicitação para que as restrições de chave de API funcionem corretamente.

Você pode redimensionar o iframe de acordo com a estrutura e o design do seu website, mas os visitantes geralmente têm mais facilidade para interagir com mapas maiores. Os mapas incorporados não têm suporte para tamanho menor que 200 px em qualquer 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 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 que cabeçalhos Referer sejam enviados ao Google.

Anúncios no mapa

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

Como escolher modos de mapa

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

• place: exibe um alfinete de 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: exibe o caminho entre dois ou mais pontos especificados no mapa, além da distância e do tempo de viagem.
• streetview: mostra visualizações 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 de 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 a localização do marcador do mapa.	Nome, endereço, plus code ou ID do local com escape de URL. A API Maps Embed é compatível com + e %20 para escapar espaços. Por exemplo, converta "Prefeitura, Nova York, NY" para City+Hall,New+York,NY ou os códigos "849VCWC8+R9" para 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 dependendo dos dados de 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 IU 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 deles. 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 será usado.
region	Opcional	Define as bordas e os rótulos apropriados para exibição, com base nas 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érico) para valores de ccTLD ("domínio de nível superior") conhecidos. Consulte os detalhes da cobertura da Plataforma Google Maps para ver as regiões compatíveis.

Modo view

O exemplo a seguir usa o modo view e o parâmetro opcional maptype para exibir 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 dependendo dos dados de 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 IU 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 deles. 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 será usado.
region	Opcional	Define as bordas e os rótulos apropriados para exibição, com base nas 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érico) para valores de ccTLD ("domínio de nível superior") conhecidos. Consulte os detalhes da cobertura da Plataforma Google Maps para ver as regiões compatíveis.

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 serão exibidas.	Nome, endereço, código plus, coordenadas de latitude/longitude ou ID de lugar com escape de URL. A API Maps Embed é compatível com + e %20 para escapar espaços. Por exemplo, converta "Prefeitura, Nova York, NY" para City+Hall,New+York,NY ou os códigos "849VCWC8+R9" para 849VCWC8%2BR9.
destination	Obrigatório	Define o ponto de chegada da rota.	Nome, endereço, código plus, coordenadas de latitude/longitude ou ID de lugar com escape de URL. A API Maps Embed é compatível com + e %20 para escapar espaços. Por exemplo, converta "Prefeitura, Nova York, NY" para City+Hall,New+York,NY ou os códigos "849VCWC8+R9" para 849VCWC8%2BR9.
waypoints	Opcional	Especifica um ou mais lugares intermediários para rotear rotas entre a origem e o destino.	Nome, endereço ou ID do lugar. É possível especificar vários waypoints usando o caractere de barra vertical (|) para separar lugares (por exemplo, Berlin,Germany|Paris,France). É possível especificar até 20 waypoints.
mode	Opcional	Define o método de viagem. Se nenhum modo for especificado, a API Maps Embed mostrará um ou mais modos relevantes para o trajeto especificado.	driving, walking (prefere trilhas para pedestres e calçadas, quando disponíveis), bicycling (que faz o trajeto por ciclovias e ruas preferenciais, quando disponíveis), transit ou flying.
avoid	Opcional	Especifica os elementos que devem ser evitados nas rotas. Isso não exclui rotas que incluam os recursos restritos. Ele direciona o resultado para rotas mais favoráveis.	tolls, ferries e/ou highways. Separe valores com o caractere de barra vertical (por exemplo, avoid=tolls|highways).
units	Opcional	Especifica o método de medição, métrica ou imperial, ao exibir distâncias nos resultados. Se units não forem especificados, o país origin da consulta 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 dependendo dos dados de 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 IU 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 deles. 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 será usado.
region	Opcional	Define as bordas e os rótulos apropriados para exibição, com base nas 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érico) para valores de ccTLD ("domínio de nível superior") conhecidos. Consulte os detalhes da cobertura da Plataforma Google Maps para ver as regiões compatíveis.

Modo streetview

Com a API Maps Embed, você pode exibir imagens do Street View como panoramas interativos de locais designados na área de cobertura. As photo spheres 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 visualização completa em 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.

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 exibirá o panorama fotografado mais próximo desse local. Como as imagens do Street View são atualizadas periodicamente, e as fotografias podem ser tiradas de posições ligeiramente diferentes a cada vez, é possível que seu local se encaixe 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 será usado apenas 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 orientaçã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, um valor de 0° geralmente é horizontal, mas nem 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° - 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 dependendo dos dados de 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 IU 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 deles. 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 será usado.
region	Opcional	Define as bordas e os rótulos apropriados para exibição, com base nas 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érico) para valores de ccTLD ("domínio de nível superior") conhecidos. Consulte os detalhes da cobertura da Plataforma Google Maps para ver as regiões compatíveis.

Modo search

O modo Search exibe os resultados de uma pesquisa na região visível do mapa. É recomendável que um local para a pesquisa seja definido, 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 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 dependendo dos dados de 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 IU 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 deles. 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 será usado.
region	Opcional	Define as bordas e os rótulos apropriados para exibição, com base nas 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érico) para valores de ccTLD ("domínio de nível superior") conhecidos. Consulte os detalhes da cobertura da Plataforma Google Maps para ver as regiões compatíveis.

Parâmetros do ID de lugar

A API Maps Embed permite o 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 local de forma exclusiva. Para mais informações, consulte a documentação da API do 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 a origem de uma solicitação de rotas: origin=place_id:ChIJs--MqP1YwokRBwAhjXWIHn8.

• radius define um raio, especificado em metros, para procurar um panorama, centrado na latitude e longitude especificadas. 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 origens padrão do Street View. As pesquisas não estão limitadas 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. Os panoramas externos não existem para o local especificado. Observe também que a pesquisa retorna apenas panoramas em que é possível determinar se eles estão em ambientes internos ou externos. Por exemplo, o PhotoSpheres não é retornado porque não se sabe se eles estão em ambientes internos ou ao ar livre.