Visão geral

Selecione a plataforma: Android iOS JavaScript

Com a API Maps JavaScript, você pode personalizar mapas com seu próprio conteúdo e imagens para exibir em páginas da Web e dispositivos móveis. A API Maps JavaScript tem quatro tipos básicos de mapa (roteiro, satélite, híbrido e terreno) que você pode modificar usando camadas e estilos, controles e eventos, além de vários serviços e bibliotecas.

Público-alvo

Esta documentação destina-se a pessoas familiarizadas com a programação JavaScript e com conceitos de programação orientada a objetos. Também é preciso saber utilizar o Maps como usuário. Existem muitos tutoriais de JavaScript disponíveis na Web.

Com esta documentação conceitual, você pode explorar e desenvolver aplicativos com a API Maps JavaScript. Também publicamos a Referência da API Maps JavaScript.

Hello World

A maneira mais fácil de começar a conhecer a API Maps JavaScript é com um exemplo simples. Confira a seguir um mapa centralizado em Sydney, Nova Gales do Sul, Austrália.

TypeScript

let map: google.maps.Map;
async function initMap(): Promise<void> {
  //@ts-ignore
  const { Map } = await google.maps.importLibrary("maps");
  map = new Map(document.getElementById("map") as HTMLElement, {
    center: { lat: -34.397, lng: 150.644 },
    zoom: 8,
  });
}

initMap();
index.ts

JavaScript

let map;

async function initMap() {
  //@ts-ignore
  const { Map } = await google.maps.importLibrary("maps");

  map = new Map(document.getElementById("map"), {
    center: { lat: -34.397, lng: 150.644 },
    zoom: 8,
  });
}

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>Simple Map</title>
    <script src="https://polyfill.io/v3/polyfill.min.js?features=default"></script>

    <link rel="stylesheet" type="text/css" href="./style.css" />
    <script type="module" src="./index.js"></script>
  </head>
  <body>
    <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
Exemplo

Testar amostra

Mesmo nesse exemplo simples, há algumas coisas a observar:

  1. Declaramos o aplicativo como HTML5 usando a declaração <!DOCTYPE html>.
  2. Criamos um elemento div chamado "map" para conter o mapa.
  3. Definimos uma função JavaScript que cria um mapa no div.
  4. Nós carregamos a API Maps JavaScript usando o carregador de inicialização.

Essas etapas são explicadas a seguir:

Carregar a API Maps JavaScript

O carregador de inicialização é a maneira recomendada de carregar a API Maps JavaScript. O carregador da API JS também é uma alternativa. Recomendamos que você analise as duas abordagens e escolha a mais adequada para a estrutura do código no seu projeto.

Para mais detalhes, confira Carregar a API Maps JavaScript.

Carregador de inicialização

Carregue a API Maps JavaScript adicionando um carregador de inicialização inline ao código do aplicativo, conforme mostrado no trecho a seguir:

<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_HERE",
    // Add other bootstrap parameters as needed, using camel case.
    // Use the 'v' parameter to indicate the version to load (alpha, beta, weekly, etc.)
  });
</script>

Para carregar bibliotecas no tempo de execução, use o operador await para chamar a função importLibrary() em uma função assíncrona, conforme mostrado aqui:

TypeScript

let map: google.maps.Map;
async function initMap(): Promise<void> {
  //@ts-ignore
  const { Map } = await google.maps.importLibrary("maps");
  map = new Map(document.getElementById("map") as HTMLElement, {
    center: { lat: -34.397, lng: 150.644 },
    zoom: 8,
  });
}

initMap();
index.ts

JavaScript

let map;

async function initMap() {
  //@ts-ignore
  const { Map } = await google.maps.importLibrary("maps");

  map = new Map(document.getElementById("map"), {
    center: { lat: -34.397, lng: 150.644 },
    zoom: 8,
  });
}

initMap();
index.js

Pacote js-api-loader do NPM

Use @googlemaps/js-api-loader para usar o NPM e carregar a API Maps JavaScript. Instale pelo NPM usando o seguinte comando:

npm install @googlemaps/js-api-loader

Este pacote pode ser importado para o aplicativo com:

import { Loader } from "@googlemaps/js-api-loader"

O carregador expõe uma interface de callback e promessa. Confira a seguir o uso do método de promessa padrão load().

TypeScript

const loader = new Loader({
  apiKey: "YOUR_API_KEY",
  version: "weekly",
  ...additionalOptions,
});

loader.load().then(async () => {
  const { Map } = await google.maps.importLibrary("maps") as google.maps.MapsLibrary;
  map = new Map(document.getElementById("map") as HTMLElement, {
    center: { lat: -34.397, lng: 150.644 },
    zoom: 8,
  });
});
index.ts

JavaScript

const loader = new Loader({
  apiKey: "YOUR_API_KEY",
  version: "weekly",
  ...additionalOptions,
});

loader.load().then(async () => {
  const { Map } = await google.maps.importLibrary("maps");

  map = new Map(document.getElementById("map"), {
    center: { lat: -34.397, lng: 150.644 },
    zoom: 8,
  });
});

index.js

Declarar o aplicativo como HTML5

Recomendamos que você declare um DOCTYPE verdadeiro dentro do seu aplicativo da Web. Nestes exemplos, declaramos nossos aplicativos como HTML5 usando o DOCTYPE HTML 5 simples, como mostrado a seguir:

<!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>
  #map {
    height: 100%;
  }
  html, body {
    height: 100%;
    margin: 0;
    padding: 0;
  }
</style>

Essa declaração CSS indica que o contêiner do mapa <div> (com ID map) ocupa toda a altura do corpo do HTML. É necessário declarar especificamente essas percentagens para <body> e para <html>.

Como carregar a API Maps JavaScript

A API Maps JavaScript é carregada usando uma tag script, que pode ser adicionada inline no seu arquivo HTML ou dinamicamente usando um arquivo JavaScript separado. Recomendamos que você analise as duas abordagens e escolha a mais adequada para a estrutura do código no seu projeto.

Carregamento inline

Para carregar a API Maps JavaScript inline em um arquivo HTML, adicione uma tag script, como mostrado abaixo.

<script async
    src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&callback=initMap">
</script>

Carregamento dinâmico

Para carregar dinamicamente a API Maps JavaScript usando um arquivo JavaScript separado, consulte o exemplo abaixo. Essa abordagem permite que você manipule todo o código para trabalhar com a API em um arquivo .js separado e é equivalente a adicionar a tag de script inline.

// Create the script tag, set the appropriate attributes
var script = document.createElement('script');
script.src = 'https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&callback=initMap';
script.async = true;

// Attach your callback function to the `window` object
window.initMap = function() {
  // JS API is loaded and available
};

// Append the 'script' element to 'head'
document.head.appendChild(script);

Carregamento dinâmico

O pacote @googlemaps/js-api-loaderestá disponível para proporcionar uma experiência de carregamento dinâmico melhor. Ele pode ser instalado pelo NPM com o seguinte:

npm install @googlemaps/js-api-loader

Este pacote pode ser importado para o aplicativo com:

import { Loader } from "@googlemaps/js-api-loader"

O carregador expõe uma interface de callback e promessa. Confira a seguir o uso do método de promessa padrão load().

TypeScript

const loader = new Loader({
  apiKey: "YOUR_API_KEY",
  version: "weekly",
  ...additionalOptions,
});

loader.load().then(async () => {
  const { Map } = await google.maps.importLibrary("maps") as google.maps.MapsLibrary;
  map = new Map(document.getElementById("map") as HTMLElement, {
    center: { lat: -34.397, lng: 150.644 },
    zoom: 8,
  });
});
index.ts

JavaScript

const loader = new Loader({
  apiKey: "YOUR_API_KEY",
  version: "weekly",
  ...additionalOptions,
});

loader.load().then(async () => {
  const { Map } = await google.maps.importLibrary("maps");

  map = new Map(document.getElementById("map"), {
    center: { lat: -34.397, lng: 150.644 },
    zoom: 8,
  });
});

index.js

Atributos da tag de script

Observe nos exemplos acima que vários atributos são definidos na tag script, o que é recomendado. Confira a seguir uma explicação de cada atributo.

  • src: o URL de onde a API Maps JavaScript é carregada, incluindo todos os símbolos e definições necessários para usá-la. O URL neste exemplo tem dois parâmetros: key, em que você fornece a chave de API, e callback, em que você especifica o nome de uma função global a ser chamada quando a API Maps JavaScript é carregada completamente. Leia mais sobre os parâmetros de URL.
  • async: solicita que o navegador faça o download e execute o script de forma assíncrona. Quando o script é executado, ele chama a função especificada usando o parâmetro callback.

Bibliotecas

Ao carregar a API Maps JavaScript pelo URL, você pode carregar outras bibliotecas usando o operador await para chamar importLibrary() em uma função assíncrona. As bibliotecas são módulos de código que fornecem mais funcionalidades para a API Maps JavaScript principal, mas não são carregadas, a menos que você as solicite especificamente. Para mais informações, confira Bibliotecas na API Maps JavaScript.

Elementos de DOM do mapa

<div id="map"></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 chamado div e obtendo uma referência a ele no DOM (modelo de objeto do documento) do navegador.

No exemplo acima, usamos CSS para definir a altura do div do mapa como "100%". O mapa se expande de acordo com o tamanho dos dispositivos móveis. Pode ser necessário ajustar os valores de largura e altura com base no tamanho da tela e no preenchimento do navegador. Os divs normalmente herdam a largura do elemento contêiner. Divs vazios normalmente têm a altura 0. Por esse motivo, é sempre necessário definir uma altura no <div> explicitamente.

Opções do mapa

Há duas opções obrigatórias para cada mapa: center e zoom.

map = new Map(document.getElementById('map'), {
  center: {lat: -34.397, lng: 150.644},
  zoom: 8
});

Níveis de zoom

Especifique a resolução na qual um mapa deve ser exibido definindo a propriedade zoom, em que 0 de zoom corresponde a um mapa da Terra sem nenhuma ampliação, e níveis de zoom mais altos aumentam o zoom em uma resolução maior.

zoom: 8

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

Para informações sobre como a API Maps JavaScript carrega blocos com base no nível de zoom atual, consulte o guia sobre coordenadas de mapa e bloco.

O objeto Map

map = new Map(document.getElementById("map"), {...});

A classe JavaScript que representa um mapa é a classe Map. Os objetos dessa classe definem um único mapa na página. É possível criar mais de uma instância dessa classe. Cada objeto define um mapa separado na página. Criamos uma nova instância dessa classe usando o operador JavaScript new.

Ao criar uma nova instância do mapa, você especifica um elemento HTML <div> na página como um contêiner do mapa. Os nós HTML são filhos do objeto JavaScript document, e obtemos uma referência a esse elemento pelo método document.getElementById().

Este código define uma variável (denominada map) e atribui essa variável a um novo objeto Map. A função Map() é conhecida como um construtor, e a definição dela é mostrada abaixo:

Construtor Descrição
Map(mapDiv:Node, opts?:MapOptions ) Cria um novo mapa dentro do contêiner HTML informado (normalmente, um elemento DIV) usando os parâmetros (opcionais) transmitidos.

Solução de problemas

Chave de API e erros de faturamento

Em algumas situações, um mapa escuro ou uma imagem "negativa" do Street View pode aparecer com a marca d'água "somente para fins de desenvolvimento". Normalmente, isso indica problemas com uma chave de API ou com o faturamento. Para usar os produtos da Plataforma Google Maps, o faturamento precisa estar ativado na sua conta, e todas as solicitações têm que incluir uma chave de API válida. O fluxo a seguir ajudará a resolver esse problema:

Se o código não funciona:

Para que seu código de mapas funcione bem, Brendan Kenny e Mano Marks mostram neste vídeo alguns erros comuns e a correção deles.

  • Procure erros de digitação. A linguagem JavaScript diferencia maiúsculas de minúsculas.
  • Verifique os elementos básicos. Alguns dos problemas mais comuns ocorrem na criação inicial do mapa. Por exemplo:
    • Confirme se você especificou as propriedades zoom e center nas opções do mapa.
    • Verifique se declarou um elemento "div" que vai ser usado para mostrar o mapa na tela.
    • Confira se esse elemento tem uma altura. Por padrão, os elementos "div" são criados com uma altura de zero, o que os torna invisíveis.
    Consulte uma implementação de referência nos nossos exemplos.
  • Para identificar problemas, use um Depurador de JavaScript, como o disponível nas Ferramentas para desenvolvedores do Chrome. Comece procurando erros no Console JavaScript.
  • Faça perguntas no Stack Overflow. Confira na página Suporte orientações para postar boas perguntas.