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 Google 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;

function initMap(): void {
  map = new google.maps.Map(document.getElementById("map") as HTMLElement, {
    center: { lat: -34.397, lng: 150.644 },
    zoom: 8,
  });
}

declare global {
  interface Window {
    initMap: () => void;
  }
}
window.initMap = initMap;
index.ts

JavaScript

let map;

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

window.initMap = 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>

    <!--
      The `defer` attribute causes the callback to execute after the full HTML
      document has been parsed. For non-blocking uses, avoiding race conditions,
      and consistent behavior across browsers, consider loading using Promises
      with https://www.npmjs.com/package/@googlemaps/js-api-loader.
      -->
    <script
      src="https://maps.googleapis.com/maps/api/js?key=AIzaSyB41DRUbKWJHPxaFjMAwdrzWzbVKartNGg&callback=initMap&v=weekly"
      defer
    ></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. A API Maps JavaScript é carregada usando uma tag script.

Essas etapas são explicadas a seguir:

Como 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(() => {
  map = new google.maps.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(() => {
  map = new google.maps.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 com o parâmetro de URL libraries. 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, consulte Bibliotecas na API Maps JavaScript.

Carregamento síncrono da API

Na tag script que carrega a API Maps JavaScript, é possível omitir o atributo defer e o parâmetro callback. Essa ação bloqueia o carregamento da API até que o download seja concluído.

Como resultado, o carregamento da página provavelmente será mais lento. Por outro lado, isso significa que é possível escrever as tags de script subsequentes supondo que a API já está carregada.

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 google.maps.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 google.maps.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.