O Google usa tecnologia de IA na tradução de conteúdos para seu idioma de preferência. As traduções com IA podem ter erros.

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. Também mostramos como definir opções de mapa e usar o controle de slots 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 um conhecido, como o Google Chrome (recomendado), Firefox, Safari ou Edge, com base na sua plataforma na lista de navegadores compatíveis.

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

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

Entender o código

Nesta fase do exemplo, temos:

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

Declarar o aplicativo como HTML5

Recomendamos que você declare um DOCTYPE verdadeiro no seu aplicativo da Web. Nos exemplos aqui, declaramos nossos aplicativos como HTML5 usando o DOCTYPE HTML5, conforme mostrado abaixo:

<!DOCTYPE html>

A maioria dos navegadores atuais renderiza o conteúdo declarado com esse DOCTYPE no "modo padrão", o que significa que seu aplicativo deve ser mais compatível com vários navegadores. O DOCTYPE também foi projetado para ser degradado normalmente. Os navegadores que não o entendem vão ignorá-lo e usar o "modo quirks" para mostrar o conteúdo.

Observação: 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 ser herdados de elementos de bloco pai. Se algum desses ancestrais não especificar um tamanho, eles serão considerados como 0 x 0 pixels. Por esse motivo, incluímos a seguinte declaração style:

<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 fase do tutorial, uma janela em branco aparece, mostrando apenas o texto do rótulo não formatado. Isso ocorre 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 div elemento para fazer isso (saiba mais), mas é recomendável usar o gmp-map elemento.

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 necessá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

Oferecer um mapa de toda a Terra como uma única imagem exigiria um mapa imenso ou um mapa pequeno com baixa resolução. 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: Massa de 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. Defina a largura e a altura como maiores que 0 px para que o mapa fique visível. Nesse caso, o gmp-map está definido como uma altura de 400 pixels e uma largura de 100% para ser exibido na largura da página da Web. Recomendamos sempre definir explicitamente os estilos de altura e largura.

Controle de slots

Você pode usar o controle de slots 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 para um elemento e aninhe elementos dentro do elemento gmp-map. O snippet a seguir mostra como adicionar um rótulo HTML ao canto superior esquerdo do mapa.