Adicionar um mapa do Google com um marcador usando JavaScript

Introdução

Neste tutorial, mostramos como adicionar um mapa do Google simples com um marcador a uma página da Web. Ele foi desenvolvido para pessoas com conhecimento básico ou intermediário de HTML e CSS e que sabem um pouco de JavaScript.

Ao longo deste tutorial, você vai criar o mapa abaixo. O marcador está posicionado em Uluru (também conhecido como Ayers Rock), no Parque Nacional Uluru-Kata Tjuta.

Como começar

Estas são as três etapas para criar um mapa do Google com um marcador na sua página da Web:

  1. Gerar uma chave de API
  2. Criar uma página HTML
  3. Adicionar um mapa com um marcador

Você vai precisar de um navegador da Web. Escolha uma opção conhecida na lista de navegadores compatíveis, como Google Chrome (recomendado), Firefox, Safari ou Edge, dependendo da sua plataforma.

Etapa 1: gerar uma chave de API

Nesta seção, explicamos como autenticar o app na API Maps JavaScript usando sua própria chave de API.

Siga estas etapas para gerar uma chave:

  1. Acesse o console do Google Cloud.

  2. Crie ou selecione um projeto.

  3. Clique em Continuar para ativar a API e os serviços relacionados.

  4. Na página Credenciais, gere uma chave de API e defina as restrições dela. Observação: você vai poder usar uma chave irrestrita ou com restrições a navegadores, se tiver uma.

  5. Para evitar roubo de cota e proteger sua chave, consulte Usar chaves de API.

  6. Ative o faturamento. Consulte Utilização e faturamento para mais informações.

  7. Após obter a chave de API, clique em "YOUR_API_KEY" para adicioná-la a este snippet. Copie e cole a tag do script do carregador de inicialização para uso na sua própria página da Web.

    <script>
  (g=>{var h,a,k,p="The Google Maps JavaScript API",c="google",l="importLibrary",q="__ib__",m=document,b=window;b=b[c]||(b[c]={});var d=b.maps||(b.maps={}),r=new Set,e=new URLSearchParams,u=()=>h||(h=new Promise(async(f,n)=>{await (a=m.createElement("script"));e.set("libraries",[...r]+"");for(k in g)e.set(k.replace(/[A-Z]/g,t=>"_"+t[0].toLowerCase()),g[k]);e.set("callback",c+".maps."+q);a.src=`https://maps.${c}apis.com/maps/api/js?`+e;d[q]=f;a.onerror=()=>h=n(Error(p+" could not load."));a.nonce=m.querySelector("script[nonce]")?.nonce||"";m.head.append(a)}));d[l]?console.warn(p+" only loads once. Ignoring:",g):d[l]=(f,...n)=>r.add(f)&&u().then(()=>d[l](f,...n))})({
    key: "YOUR_API_KEY",
    v: "weekly",
    // Use the 'v' parameter to indicate the version to use (weekly, beta, alpha, etc.).
    // Add other bootstrap parameters as needed, using camel case.
  });
</script>

Etapa 2: criar uma página HTML

Este é o código de uma página HTML básica da Web:

<!doctype html>
<!--
 @license
 Copyright 2019 Google LLC. All Rights Reserved.
 SPDX-License-Identifier: Apache-2.0
-->
<html>
  <head>
    <title>Add Map</title>

    <link rel="stylesheet" type="text/css" href="./style.css" />
    <script type="module" src="./index.js"></script>
  </head>
  <body>
    <h3>My Google Maps Demo</h3>
    <!--The div element for the map -->
    <div id="map"></div>

    <!-- prettier-ignore -->
    <script>(g=>{var h,a,k,p="The Google Maps JavaScript API",c="google",l="importLibrary",q="__ib__",m=document,b=window;b=b[c]||(b[c]={});var d=b.maps||(b.maps={}),r=new Set,e=new URLSearchParams,u=()=>h||(h=new Promise(async(f,n)=>{await (a=m.createElement("script"));e.set("libraries",[...r]+"");for(k in g)e.set(k.replace(/[A-Z]/g,t=>"_"+t[0].toLowerCase()),g[k]);e.set("callback",c+".maps."+q);a.src=`https://maps.${c}apis.com/maps/api/js?`+e;d[q]=f;a.onerror=()=>h=n(Error(p+" could not load."));a.nonce=m.querySelector("script[nonce]")?.nonce||"";m.head.append(a)}));d[l]?console.warn(p+" only loads once. Ignoring:",g):d[l]=(f,...n)=>r.add(f)&&u().then(()=>d[l](f,...n))})
        ({key: "AIzaSyB41DRUbKWJHPxaFjMAwdrzWzbVKartNGg", v: "weekly"});</script>
  </body>
</html>

index.html

Essa página é bem básica, com um cabeçalho de três níveis (h3) e um único elemento div. Você pode adicionar o conteúdo que quiser à página da Web.

Entender o código

Nesta fase do exemplo, temos:

  • Declaramos o aplicativo como HTML5 usando a declaração !DOCTYPE html.
  • Criou um elemento div chamado "map" para conter o mapa.
  • Carregue a API Maps JavaScript usando o carregador bootstrap.

Declarar o aplicativo como HTML5

Recomendamos que você declare um DOCTYPE verdadeiro dentro de seu aplicativo da Web. Nestes exemplos, declaramos nossos aplicativos como HTML5 usando o DOCTYPE HTML5 simples, como mostrado abaixo:

<!DOCTYPE html>

A maioria dos navegadores atuais renderiza o conteúdo declarado com este DOCTYPE no "modo padrão", o que significa que seu aplicativo precisa ter mais compatibilidade entre navegadores. O DOCTYPE também foi criado para ficar defasado. Os navegadores que não o entendem, o ignoram e usam o "modo quirks" para mostrar o conteúdo.

Alguns CSS que funcionam no modo quirks não são válidos no modo padrão. Especificamente, todos os tamanhos baseados em porcentagem precisam herdar elementos de bloco pai e, se um dos ancestrais não especificar um tamanho, supõe-se que o tamanho seja 0 x 0 pixels. Por esse motivo, incluímos a declaração style a seguir:

<style>
  #map {
    height: 100%;
  }
  html, body {
    height: 100%;
    margin: 0;
    padding: 0;
  }
</style>

Criar um elemento div

Para que o mapa apareça em uma página da Web, precisamos reservar um lugar para ele. Normalmente, fazemos isso criando um elemento div nomeado e obtendo uma referência a ele no modelo de objetos do documento (DOM) do navegador.

Ele define uma área da página para seu mapa do Google.

<!--The div element for the map -->
<div id="map"></div>

Neste estágio do tutorial, div aparece como um bloco cinza, porque você ainda não adicionou um mapa. O código abaixo descreve o CSS que define o tamanho e a cor de div.

/* Set the size of the div element that contains the map */
#map {
    height: 400px; /* The height is 400 pixels */
    width: 100%; /* The width is the width of the web page */
}

Acima, o elemento style configura o tamanho de div. Para que o mapa fique visível, a largura e a altura de div têm que ser maiores do que zero. Neste caso, div é configurado com uma altura de 400 pixels e uma largura de 100%, que ocupa toda a página da Web. Os divs normalmente herdam a largura do elemento contêiner. Divs vazios normalmente têm a altura 0. Por esse motivo, sempre defina explicitamente uma altura no div.

Carregar a API Maps JavaScript

O carregador bootstrap prepara a API Maps JavaScript para o carregamento (nenhuma biblioteca é carregada até que importLibrary() seja chamado).

<script>
  (g=>{var h,a,k,p="The Google Maps JavaScript API",c="google",l="importLibrary",q="__ib__",m=document,b=window;b=b[c]||(b[c]={});var d=b.maps||(b.maps={}),r=new Set,e=new URLSearchParams,u=()=>h||(h=new Promise(async(f,n)=>{await (a=m.createElement("script"));e.set("libraries",[...r]+"");for(k in g)e.set(k.replace(/[A-Z]/g,t=>"_"+t[0].toLowerCase()),g[k]);e.set("callback",c+".maps."+q);a.src=`https://maps.${c}apis.com/maps/api/js?`+e;d[q]=f;a.onerror=()=>h=n(Error(p+" could not load."));a.nonce=m.querySelector("script[nonce]")?.nonce||"";m.head.append(a)}));d[l]?console.warn(p+" only loads once. Ignoring:",g):d[l]=(f,...n)=>r.add(f)&&u().then(()=>d[l](f,...n))})({
    key: "YOUR_API_KEY",
    v: "weekly",
    // Use the 'v' parameter to indicate the version to use (weekly, beta, alpha, etc.).
    // Add other bootstrap parameters as needed, using camel case.
  });
</script>

Consulte a Etapa 3: gerar uma chave de API para saber como ter sua própria chave de API.

Etapa 3: adicionar um mapa com um marcador

Nesta seção, mostramos como carregar a API Maps JavaScript na sua página da Web e escrever seu próprio JavaScript que usa a API para adicionar um mapa com um marcador.

TypeScript

// Initialize and add the map
let map;
async function initMap(): Promise<void> {
  // The location of Uluru
  const position = { lat: -25.344, lng: 131.031 };

  // Request needed libraries.
  //@ts-ignore
  const { Map } = await google.maps.importLibrary("maps") as google.maps.MapsLibrary;
  const { AdvancedMarkerElement } = await google.maps.importLibrary("marker") as google.maps.MarkerLibrary;

  // The map, centered at Uluru
  map = new Map(
    document.getElementById('map') as HTMLElement,
    {
      zoom: 4,
      center: position,
      mapId: 'DEMO_MAP_ID',
    }
  );

  // The marker, positioned at Uluru
  const marker = new AdvancedMarkerElement({
    map: map,
    position: position,
    title: 'Uluru'
  });
}

initMap();
index.ts

JavaScript

// Initialize and add the map
let map;

async function initMap() {
  // The location of Uluru
  const position = { lat: -25.344, lng: 131.031 };
  // Request needed libraries.
  //@ts-ignore
  const { Map } = await google.maps.importLibrary("maps");
  const { AdvancedMarkerElement } = await google.maps.importLibrary("marker");

  // The map, centered at Uluru
  map = new Map(document.getElementById("map"), {
    zoom: 4,
    center: position,
    mapId: "DEMO_MAP_ID",
  });

  // The marker, positioned at Uluru
  const marker = new AdvancedMarkerElement({
    map: map,
    position: position,
    title: "Uluru",
  });
}

initMap();
index.js

No código acima, as bibliotecas Map e AdvancedMarkerElement são carregadas quando a função initMap() é chamada.

Entender o código

Neste estágio do tutorial, temos:

  • Definiu uma função JavaScript que cria um mapa no div.
  • Crie um AdvancedMarkerElement para adicionar um marcador ao mapa.

Adicionar um mapa

O código abaixo cria um objeto no mapa do Google e adiciona propriedades a ele, incluindo o centro e o nível de zoom. Consulte a documentação para conhecer outras opções de propriedades.

TypeScript

// The location of Uluru
const position = { lat: -25.344, lng: 131.031 };

// Request needed libraries.
//@ts-ignore
const { Map } = await google.maps.importLibrary("maps") as google.maps.MapsLibrary;
const { AdvancedMarkerElement } = await google.maps.importLibrary("marker") as google.maps.MarkerLibrary;

// The map, centered at Uluru
map = new Map(
  document.getElementById('map') as HTMLElement,
  {
    zoom: 4,
    center: position,
    mapId: 'DEMO_MAP_ID',
  }
);
index.ts

JavaScript

// The location of Uluru
const position = { lat: -25.344, lng: 131.031 };
// Request needed libraries.
//@ts-ignore
const { Map } = await google.maps.importLibrary("maps");
const { AdvancedMarkerElement } = await google.maps.importLibrary("marker");

// The map, centered at Uluru
map = new Map(document.getElementById("map"), {
  zoom: 4,
  center: position,
  mapId: "DEMO_MAP_ID",
});

index.js

Há duas opções obrigatórias para cada mapa: center e zoom. No código acima, new Map() cria um novo objeto do Google Maps. A propriedade center informa à API onde centralizar o mapa.

A propriedade zoom especifica o nível de zoom do mapa. Zero é o nível mais baixo e mostra toda a Terra. Defina o valor mais alto para aumentar o zoom em resoluções mais altas.

A disponibilização de um mapa de todo o planeta como uma única imagem exigiria um mapa imenso ou um mapa pequeno com resolução muito baixa. Como resultado, as imagens de mapa no Google Maps e na API Maps JavaScript são divididas em "blocos" e "níveis de zoom". Em níveis baixos de zoom, um pequeno conjunto de blocos de mapa cobre uma grande área. Em níveis de zoom mais altos, os blocos têm maior resolução e cobrem uma área menor. A lista a seguir mostra o nível aproximado de detalhamento que você pode esperar em cada nível de zoom:

  • 1: Mundo
  • 5: Terra ou continente
  • 10: cidade
  • 15: ruas
  • 20: construções

As três imagens a seguir refletem a mesma localização de Tóquio, nos níveis de zoom 0, 7 e 18.

Adicionar um marcador

O código abaixo coloca um marcador no mapa. A propriedade position define a posição dele.

TypeScript

// The marker, positioned at Uluru
const marker = new AdvancedMarkerElement({
  map: map,
  position: position,
  title: 'Uluru'
});
index.ts

JavaScript

// The marker, positioned at Uluru
const marker = new AdvancedMarkerElement({
  map: map,
  position: position,
  title: "Uluru",
});
index.js

Exemplo de código completo

Confira o exemplo de código completo aqui:

TypeScript

// Initialize and add the map
let map;
async function initMap(): Promise<void> {
  // The location of Uluru
  const position = { lat: -25.344, lng: 131.031 };

  // Request needed libraries.
  //@ts-ignore
  const { Map } = await google.maps.importLibrary("maps") as google.maps.MapsLibrary;
  const { AdvancedMarkerElement } = await google.maps.importLibrary("marker") as google.maps.MarkerLibrary;

  // The map, centered at Uluru
  map = new Map(
    document.getElementById('map') as HTMLElement,
    {
      zoom: 4,
      center: position,
      mapId: 'DEMO_MAP_ID',
    }
  );

  // The marker, positioned at Uluru
  const marker = new AdvancedMarkerElement({
    map: map,
    position: position,
    title: 'Uluru'
  });
}

initMap();
index.ts

JavaScript

// Initialize and add the map
let map;

async function initMap() {
  // The location of Uluru
  const position = { lat: -25.344, lng: 131.031 };
  // Request needed libraries.
  //@ts-ignore
  const { Map } = await google.maps.importLibrary("maps");
  const { AdvancedMarkerElement } = await google.maps.importLibrary("marker");

  // The map, centered at Uluru
  map = new Map(document.getElementById("map"), {
    zoom: 4,
    center: position,
    mapId: "DEMO_MAP_ID",
  });

  // The marker, positioned at Uluru
  const marker = new AdvancedMarkerElement({
    map: map,
    position: position,
    title: "Uluru",
  });
}

initMap();
index.js

CSS

/* 
 * Always set the map height explicitly to define the size of the div element
 * that contains the map. 
 */
#map {
  height: 100%;
}

/* 
 * Optional: Makes the sample page fill the window. 
 */
html,
body {
  height: 100%;
  margin: 0;
  padding: 0;
}

style.css

HTML

<html>
  <head>
    <title>Add Map</title>

    <link rel="stylesheet" type="text/css" href="./style.css" />
    <script type="module" src="./index.js"></script>
  </head>
  <body>
    <h3>My Google Maps Demo</h3>
    <!--The div element for the map -->
    <div id="map"></div>

    <!-- prettier-ignore -->
    <script>(g=>{var h,a,k,p="The Google Maps JavaScript API",c="google",l="importLibrary",q="__ib__",m=document,b=window;b=b[c]||(b[c]={});var d=b.maps||(b.maps={}),r=new Set,e=new URLSearchParams,u=()=>h||(h=new Promise(async(f,n)=>{await (a=m.createElement("script"));e.set("libraries",[...r]+"");for(k in g)e.set(k.replace(/[A-Z]/g,t=>"_"+t[0].toLowerCase()),g[k]);e.set("callback",c+".maps."+q);a.src=`https://maps.${c}apis.com/maps/api/js?`+e;d[q]=f;a.onerror=()=>h=n(Error(p+" could not load."));a.nonce=m.querySelector("script[nonce]")?.nonce||"";m.head.append(a)}));d[l]?console.warn(p+" only loads once. Ignoring:",g):d[l]=(f,...n)=>r.add(f)&&u().then(()=>d[l](f,...n))})
        ({key: "AIzaSyB41DRUbKWJHPxaFjMAwdrzWzbVKartNGg", v: "weekly"});</script>
  </body>
</html>
index.html

Testar amostra

Saiba mais sobre marcadores:

Dicas e solução de problemas

  • Saiba mais sobre como receber coordenadas de latitude/longitude ou converter um endereço em coordenadas geográficas.
  • É possível modificar as opções, como estilo e propriedades, para personalizar o mapa. Para mais informações sobre como personalizar mapas, leia os guias sobre estilizar e desenhar no mapa.
  • Use o console de Ferramentas para desenvolvedores no navegador da Web para testar e executar o código, ler relatórios de erros e resolver problemas.
  • Use estes atalhos do teclado para abrir o console no Chrome:
    Command + Option + J (no Mac) ou Control + Shift + J (no Windows).

  • Siga as etapas abaixo para gerar as coordenadas de latitude e longitude de um local no Google Maps.

    1. Abra o Google Maps em um navegador.
    2. Clique com o botão direito do mouse no local exato das coordenadas no mapa.
    3. Selecione O que há aqui? no menu de contexto que aparece. O mapa mostra um card na parte de baixo da tela. Veja as coordenadas de latitude e longitude na última linha dele.

  • Use o serviço de geocodificação para converter um endereço em coordenadas de latitude e longitude. Os guias para desenvolvedores apresentam informações detalhadas sobre como começar a usar o serviço de geocodificação.