Neste guia, mostramos como incorporar um mapa interativo na sua página da Web.
Criar o URL da API Maps Embed
Confira a seguir um URL de exemplo 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 sua chave de API. Para mais informações, consulte Receber chave de API.
- PARAMETERS pelos parâmetros obrigatórios e opcionais do 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
permite que determinadas partes do mapa fiquem em tela cheia. - As propriedades
frameborder="0"
estyle="border:0"
para remover a borda de iframe padrão ao redor do mapa. - A propriedade
referrerpolicy="no-referrer-when-downgrade"
permite que o navegador envie o URL completo como o cabeçalhoReferer
com a solicitação para que as restrições da chave de API funcionem corretamente.
É possível redimensionar o iframe de acordo com a estrutura e o design do seu site, mas descobrimos que os visitantes geralmente acham mais fácil interagir com mapas maiores. Os mapas incorporados não têm suporte para imagens com tamanho de 200 pixels em nenhuma das dimensões.
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 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 cabeçalhos Referer
sejam enviados 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 de mapa em um lugar ou endereço específico, como um ponto de referência, empresa, característica geográfica 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 dos 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 lugar do lugar com escape de URL.
A API Maps Embed aceita + e %20 quando há escape de espaços. Por exemplo, converta "Prefeitura, Nova York, NY" para City+Hall,New+York,NY ou os plus codes "849VCWC8+R9" para 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. | Valores que variam de 0 (o mundo inteiro) a 21 (edifícios individuais). O limite máximo varia de acordo com os 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 interface e para mostrar etiquetas nos blocos do mapa. Por padrão, os visitantes visualizam um mapa no próprio idioma. Esse parâmetro só tem suporte em 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 fronteiras e rótulos adequados a serem exibidos com base em particularidades geopolíticas. | Aceita um código regional 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 disponíveis. |
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
¢er=-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. | Valores que variam de 0 (o mundo inteiro) a 21 (edifícios individuais). O limite máximo varia de acordo com os 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 interface e para mostrar etiquetas nos blocos do mapa. Por padrão, os visitantes visualizam um mapa no próprio idioma. Esse parâmetro só tem suporte em 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 fronteiras e rótulos adequados a serem exibidos com base em particularidades geopolíticas. | Aceita um código regional 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 disponíveis. |
Modo directions
O exemplo a seguir usa o modo directions
para exibir o caminho entre Oslow e a 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 a partir do qual exibir as rotas. | Nome do lugar, endereço, Plus Code, coordenadas de latitude/longitude ou ID do lugar com escape de URL.
A API Maps Embed aceita + e %20 quando há escape de espaços. Por exemplo, converta "Prefeitura, Nova York, NY" para City+Hall,New+York,NY ou os plus codes "849VCWC8+R9" para 849VCWC8%2BR9 . |
destination |
Obrigatório | Define o ponto final das rotas. | Nome do lugar, endereço, Plus Code, coordenadas de latitude/longitude ou ID do lugar com escape de URL.
A API Maps Embed aceita + e %20 quando há escape de espaços. Por exemplo, converta "Prefeitura, Nova York, NY" para City+Hall,New+York,NY ou os plus codes "849VCWC8+R9" para 849VCWC8%2BR9 . |
waypoints |
Opcional | Especifica um ou mais lugares 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 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 dos modos mais relevantes para o trajeto especificado. | driving , walking (prefere caminhos e calçadas, quando disponível), bicycling (que usa ciclovias e ruas preferenciais, quando disponíveis), transit ou flying . |
avoid |
Opcional | Especifica elementos a serem evitados nas rotas. Isso não impede trajetos que incluam os elementos restritos, mas direciona o resultado para trajetos 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 for especificado, o
país origin da consulta 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. | Valores que variam de 0 (o mundo inteiro) a 21 (edifícios individuais). O limite máximo varia de acordo com os 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 interface e para mostrar etiquetas nos blocos do mapa. Por padrão, os visitantes visualizam um mapa no próprio idioma. Esse parâmetro só tem suporte em 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 fronteiras e rótulos adequados a serem exibidos com base em particularidades geopolíticas. | Aceita um código regional 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 disponíveis. |
Modo streetview
Com a API Maps Embed, é possível mostrar imagens do Street View como panoramas interativos de locais designados em toda a área de cobertura. Também há fotosferas enviadas pelo usuário e coleções especiais do Street View.
Cada panorama do Street View oferece uma visualização 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. Você pode manipular a câmera
para controlar o zoom e a orientação.
Veja o seguinte panorama no 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 parâmetros de URL a seguir é 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 mude para um panorama diferente quando as imagens forem atualizadas.pano
é um ID de panorama específico. Se você especificar umpano
, também poderá especificar umlocation
. Olocation
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. O inclinação 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, no intervalo de 10° - 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. | Valores que variam de 0 (o mundo inteiro) a 21 (edifícios individuais). O limite máximo varia de acordo com os 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 interface e para mostrar etiquetas nos blocos do mapa. Por padrão, os visitantes visualizam um mapa no próprio idioma. Esse parâmetro só tem suporte em 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 fronteiras e rótulos adequados a serem exibidos com base em particularidades geopolíticas. | Aceita um código regional 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 disponíveis. |
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 com a inclusão de um local no termo de pesquisa (record+stores+in+Seattle
) ou com os parâmetros center
e zoom
para vincular 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. | Valores que variam de 0 (o mundo inteiro) a 21 (edifícios individuais). O limite máximo varia de acordo com os 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 interface e para mostrar etiquetas nos blocos do mapa. Por padrão, os visitantes visualizam um mapa no próprio idioma. Esse parâmetro só tem suporte em 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 fronteiras e rótulos adequados a serem exibidos com base em particularidades geopolíticas. | Aceita um código regional 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 disponíveis. |
Parâmetros de ID do lugar
A API Maps Embed permite o uso de IDs de lugar em vez de fornecer um nome ou endereço de local. Eles são uma forma 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 a 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.source
limita as pesquisas do Street View às origens selecionadas. Os valores válidos são:default
usa as fontes padrão do Street View. As pesquisas não se limitam a fontes 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. Pode ser que não existam panoramas externos para o local especificado. A pesquisa só retorna panoramas quando é possível determinar se eles estão em um ambiente fechado ou ao ar livre. Por exemplo, PhotoSpheres não são retornados porque não se sabe se eles estão em ambientes fechados ou ao ar livre.