Esta página foi traduzida pela API Cloud Translation.

Adicionar um mapa do Google com um marcador usando JavaScript

Introdução

Neste tutorial, mostramos como adicionar um mapa do Google com um marcador a uma página da Web usando HTML, CSS e JavaScript. Ele também mostra como definir opções de mapa e usar a inclusão de controles para adicionar um rótulo ao mapa.

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:

Gerar uma chave de API
Criar uma página HTML
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:

Acesse o console do Google Cloud.
Crie ou selecione um projeto.
Clique em Continuar para ativar a API e os serviços relacionados.
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.
Para evitar roubo de cota e proteger sua chave, consulte Usar chaves de API.
Ative o faturamento. Consulte Utilização e faturamento para mais informações.

Após obter a chave de API, clique em "YOUR_API_KEY" para adicioná-la a este snippet. Copie e cole a tag script do carregador de inicialização para usar 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 2025 Google LLC. All Rights Reserved.
 SPDX-License-Identifier: Apache-2.0
-->

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

    <link rel="stylesheet" type="text/css" href="./style.css" />
    <script type="module" src="./index.js"></script>
    <!-- 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: "YOUR_API_KEY", v: "weekly"});</script>
  </head>
  <body>

    <!-- The map, centered at Uluru, Australia. -->
    <gmp-map center="-25.344,131.031" zoom="4" map-id="DEMO_MAP_ID">
    </gmp-map>

  </body>
</html>

Essa é uma página HTML muito básica que usa um gmp-map element para mostrar um mapa na página. O mapa vai ficar em branco porque ainda não adicionamos nenhum código JavaScript.

Entender o código

Nesta etapa do exemplo, temos:

Declaramos o aplicativo como HTML5 usando a declaração !DOCTYPE html.
Carregou a API Maps JavaScript usando o carregador bootstrap.
Criou um elemento gmp-map para conter o mapa.

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 HTML5 DOCTYPE, como mostrado abaixo:

<!DOCTYPE html>

A maioria dos navegadores atuais renderiza o conteúdo declarado com este DOCTYPE em "modo padrão", o que significa que seu aplicativo deve ser mais compatível 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>
  gmp-map {
    height: 100%;
  }
  html, body {
    height: 100%;
    margin: 0;
    padding: 0;
  }
</style>

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.

Nesta etapa do tutorial, uma janela em branco aparece, mostrando apenas o texto do rótulo sem formatação. Isso porque ainda não adicionamos nenhum código JavaScript.

Criar um elemento `gmp-map`

Para que o mapa apareça em uma página da Web, precisamos reservar um lugar para ele. Normalmente, fazemos isso criando um elemento gmp-map e obtendo uma referência a ele no DOM (modelo de objeto do documento) do navegador. Você também pode usar um elemento div para fazer isso (saiba mais), mas é recomendável usar o elemento gmp-map.

O código abaixo define o elemento gmp-map e define os parâmetros center, zoom e map-id.

<gmp-map center="-25.344,131.031" zoom="4" map-id="DEMO_MAP_ID">
</gmp-map>

As opções center e zoom são sempre obrigatórias. No código acima, a propriedade center informa à API onde centralizar o mapa, e 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.

Níveis de zoom

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 detalhes 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.

O código abaixo descreve o CSS que define o tamanho do elemento gmp-map.

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

No código acima, o elemento style define o tamanho do gmp-map. Para que o mapa fique visível, a largura e a altura têm que ser maiores do que zero. Neste caso, gmp-map é configurado com uma altura de 400 pixels e uma largura de 100%, que ocupa toda a página da Web. Recomendamos sempre definir explicitamente os estilos de altura e largura.

Controle de posição

Você pode usar o controle de slot para adicionar controles de formulário HTML ao mapa. Um slot é uma posição predefinida no mapa. Use o atributo slot para definir a posição necessária de um elemento e aninhe os elementos no elemento gmp-map. O snippet a seguir mostra como adicionar um rótulo HTML ao canto superior esquerdo do mapa.

<!-- The map, centered at Uluru, Australia. -->
<gmp-map center="-25.344,131.031" zoom="4" map-id="DEMO_MAP_ID">
  <div id="controls" slot="control-inline-start-block-start">
    <h3>My Google Maps Demo</h3>
  </div>
</gmp-map>

Etapa 3: adicionar código JavaScript

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

TypeScript

async function initMap(): Promise<void> {
  //  Request the needed libraries.
  const [{ Map }, { AdvancedMarkerElement }] = await Promise.all([
    google.maps.importLibrary("maps") as Promise<google.maps.MapsLibrary>,
    google.maps.importLibrary("marker") as Promise<google.maps.MarkerLibrary>,
  ]);
  // Get the gmp-map element.
  const mapElement = document.querySelector(
    "gmp-map"
  ) as google.maps.MapElement;

  // Get the inner map.
  const innerMap = mapElement.innerMap;

  // Set map options.
  innerMap.setOptions({
    mapTypeControl: false,
  });

  // Add a marker positioned at the map center (Uluru).
  const marker = new AdvancedMarkerElement({
    map: innerMap,
    position: mapElement.center,
    title: "Uluru/Ayers Rock",
  });
}
initMap();index.ts

JavaScript

async function initMap() {
    //  Request the needed libraries.
    const [{ Map }, { AdvancedMarkerElement }] = await Promise.all([
        google.maps.importLibrary("maps"),
        google.maps.importLibrary("marker"),
    ]);
    // Get the gmp-map element.
    const mapElement = document.querySelector("gmp-map");
    // Get the inner map.
    const innerMap = mapElement.innerMap;
    // Set map options.
    innerMap.setOptions({
        mapTypeControl: false,
    });
    // Add a marker positioned at the map center (Uluru).
    const marker = new AdvancedMarkerElement({
        map: innerMap,
        position: mapElement.center,
        title: "Uluru/Ayers Rock",
    });
}
initMap();index.js

O código acima faz o seguinte quando initMap() é chamado:

Carrega as bibliotecas maps e marker.
Recebe o elemento do mapa do DOM.
Define outras opções de mapa no mapa interno.
Adiciona um marcador ao mapa.

Receber o objeto de mapa e definir opções

O innerMap representa uma instância da classe Map. Para definir opções de mapa, extraia a instância innerMap do elemento de mapa e chame setOptions. O snippet a seguir mostra como receber a instância innerMap do DOM e chamar setOptions:

// Get the gmp-map element.
const mapElement = document.querySelector(
  "gmp-map"
) as google.maps.MapElement;

// Get the inner map.
const innerMap = mapElement.innerMap;

// Set map options.
innerMap.setOptions({
  mapTypeControl: false,
});

Aguarde o carregamento do mapa

Ao usar o elemento gmp-map, o mapa é carregado de forma assíncrona. Isso pode resultar em uma condição de disputa se outras solicitações forem feitas no momento da inicialização (por exemplo, geolocalização ou uma solicitação de detalhes de lugar). Para garantir que o código só seja executado depois que o mapa estiver totalmente carregado, use um manipulador de eventos ociosos addListenerOnce na função de inicialização, conforme mostrado aqui:

// Do things once the map has loaded.
google.maps.event.addListenerOnce(innerMap, 'idle', () => {
    // Run this code only after the map has loaded.
    console.log("The map is now ready!");
});

Isso garante que o código só seja executado depois que o mapa for carregado. O manipulador só é acionado uma vez durante o ciclo de vida do app.

Exemplo de código completo

Confira o exemplo de código completo aqui:

TypeScript

async function initMap(): Promise<void> {
  //  Request the needed libraries.
  const [{ Map }, { AdvancedMarkerElement }] = await Promise.all([
    google.maps.importLibrary("maps") as Promise<google.maps.MapsLibrary>,
    google.maps.importLibrary("marker") as Promise<google.maps.MarkerLibrary>,
  ]);
  // Get the gmp-map element.
  const mapElement = document.querySelector(
    "gmp-map"
  ) as google.maps.MapElement;

  // Get the inner map.
  const innerMap = mapElement.innerMap;

  // Set map options.
  innerMap.setOptions({
    mapTypeControl: false,
  });

  // Add a marker positioned at the map center (Uluru).
  const marker = new AdvancedMarkerElement({
    map: innerMap,
    position: mapElement.center,
    title: "Uluru/Ayers Rock",
  });
}
initMap();index.ts

JavaScript

async function initMap() {
    //  Request the needed libraries.
    const [{ Map }, { AdvancedMarkerElement }] = await Promise.all([
        google.maps.importLibrary("maps"),
        google.maps.importLibrary("marker"),
    ]);
    // Get the gmp-map element.
    const mapElement = document.querySelector("gmp-map");
    // Get the inner map.
    const innerMap = mapElement.innerMap;
    // Set map options.
    innerMap.setOptions({
        mapTypeControl: false,
    });
    // Add a marker positioned at the map center (Uluru).
    const marker = new AdvancedMarkerElement({
        map: innerMap,
        position: mapElement.center,
        title: "Uluru/Ayers Rock",
    });
}
initMap();index.js

CSS

/*
 * Always set the map height explicitly to define the size of the div element
 * that contains the map.
 */
gmp-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 a Map</title>

    <link rel="stylesheet" type="text/css" href="./style.css" />
    <script type="module" src="./index.js"></script>
    <!-- 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: "AIzaSyA6myHzS10YXdcazAFalmXvDkrYCp5cLc8", v: "weekly"});</script>
  </head>
  <body>
    <!-- The map, centered at Uluru, Australia. -->
    <gmp-map center="-25.344,131.031" zoom="4" map-id="DEMO_MAP_ID">
      <div id="controls" slot="control-inline-start-block-start">
        <h3>My Google Maps Demo</h3>
      </div>
    </gmp-map>
  </body>
</html>index.html

Testar amostra

JSFiddle.net

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.

Adicionar um mapa do Google com um marcador usando JavaScript Mantenha tudo organizado com as coleções Salve e categorize o conteúdo com base nas suas preferências.

Introdução

Como começar

Etapa 1: gerar uma chave de API

Etapa 2: criar uma página HTML

Entender o código

Declarar o aplicativo como HTML5

Carregar a API Maps JavaScript

Criar um elemento gmp-map

Níveis de zoom

Controle de posição

Etapa 3: adicionar código JavaScript

TypeScript

JavaScript

Receber o objeto de mapa e definir opções

Aguarde o carregamento do mapa

Exemplo de código completo

TypeScript

JavaScript

CSS

HTML

Testar amostra

Saiba mais sobre marcadores:

Dicas e solução de problemas

Adicionar um mapa do Google com um marcador usando JavaScript

Criar um elemento `gmp-map`