Pronto!

Para começar a desenvolver, acesse nossa documentação do desenvolvedor.

Ativar a Google Maps JavaScript API

Para começar, orientaremos você pelo Console do Desenvolvedor do Google para realizar algumas atividades:

  1. Criar ou selecionar um projeto
  2. Ativar a Google Maps JavaScript API e serviços relacionados
  3. Criar chaves apropriadas
Continuar

Primeiros passos

Público-alvo

Esta documentação foi projetada para pessoas familiarizadas com programação JavaScript e com conceitos de programação orientada a objeto. Também é necessário estar familiarizado com o Google Maps do ponto de vista de um usuário. Há vários tutoriais de JavaScript disponíveis na web.

Esta documentação conceitual foi projetada para permitir que você comece rapidamente a explorar e desenvolver aplicativos com a Google Maps JavaScript API. Publicamos também a Referência da Google Maps JavaScript API.

Hello, World

A maneira mais fácil de começar a aprender sobre a Google Maps JavaScript API é ver um exemplo simples. A página a seguir exibe um mapa centralizado em Sidnei, New South Wales, Austrália:

var map;
function initMap() {
  map = new google.maps.Map(document.getElementById('map'), {
    center: {lat: -34.397, lng: 150.644},
    zoom: 8
  });
}
<div id="map"></div>
/* 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;
}
<!-- Replace the value of the key parameter with your own API key. -->
<script src="https://maps.googleapis.com/maps/api/js?key=AIzaSyCkUOdZ5y7hMm0yrcCQoCvLwzdM6M8s5qk&callback=initMap" async defer></script>
<!DOCTYPE html>
<html>
  <head>
    <title>Simple Map</title>
    <meta name="viewport" content="initial-scale=1.0">
    <meta charset="utf-8">
    <style>
      /* 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>
  </head>
  <body>
    <div id="map"></div>
    <script>
      var map;
      function initMap() {
        map = new google.maps.Map(document.getElementById('map'), {
          center: {lat: -34.397, lng: 150.644},
          zoom: 8
        });
      }
    </script>
    <script src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&callback=initMap"
    async defer></script>
  </body>
</html>

Ver o exemplo (map-simple.html)

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 denominado "map" para conter o mapa.
  3. Definimos uma função JavasScript que cria um mapa no div.
  4. Carregamos as Maps JavaScript API usando uma tag script.

Essas etapas são explicadas a seguir:

Declarar o aplicativo como HTML5

Recomendamos declarar um DOCTYPE verdadeiro no aplicativo web. Nestes exemplos, declaramos nossos aplicativos como HTML5 usando o DOCTYPE simples do HTML5, mostrado a seguir:

<!DOCTYPE html>

A maioria dos navegadores atuais renderiza o conteúdo declarado com esse DOCTYPE no "modo padrão", o que significa que o aplicativo deve ter maior compatibilidade em diversos navegadores. O DOCTYPE também é projetado para degradar de forma organizada. Esse recurso é ignorado por navegadores que não o entendem e usam o "modo quirks" para exibir o conteúdo.

Observe que há código CSS que funciona no modo quirks, mas não é válido no modo padrão. Especificamente, todos os tamanhos baseados em porcentagem devem 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 100% da altura do corpo HTML. Observe que devemos declarar especificamente essas porcentagens para <body> e também para <html>.

Carregar a Google Maps JavaScript API

Para carregar a Google Maps JavaScript API, use uma tag script como a deste exemplo:
    <script async defer
      src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&callback=initMap">
    </script>

O URL contido na tag script é o local de um arquivo JavaScript que carrega todos os símbolos e definições necessários para usar as Maps JavaScript API. Essa tag script é obrigatória.

O atributo async permite que o navegador renderize o restante do site durante o carregamento das Maps JavaScript API. Quando a API está pronta, ela chama a função especificada usando o parâmetro callback.

O parâmetro key contém a chave de API do aplicativo. Consulte Obter uma chave para obter mais informações.

Observação: os clientes do Google Maps APIs Premium Plan podem usar uma chave de API ou um ID do cliente válido no carregamento da API. Saiba mais sobre parâmetros de autenticação para clientes Premium Plan.

HTTPS ou HTTP

Consideramos a segurança na web muito importante e recomendamos usar HTTPS sempre que possível. Como parte de nossos esforços para tornar a Web mais segura, disponibilizamos todas as Maps JavaScript API sobre HTTPS. O uso da criptografia HTTPS torna o site mais seguro e mais resistente a invasões ou adulterações.

Recomendamos carregar a Maps JavaScript API sobre HTTPS usando a tag <script> fornecida acima.

Se necessário, carregue a Maps JavaScript API sobre HTTP solicitando http://maps.googleapis.com/ ou http://maps.google.cn para usuários na China.

Bibliotecas

Durante o carregamento das Maps JavaScript API por meio do URL, você pode carregar bibliotecas adicionais usando o parâmetro de URL libraries. As bibliotecas são módulos de código que oferecem funcionalidade adicional às Maps JavaScript API principais e somente são carregadas mediante solicitação explícita. Para obter mais informações, consulte Bibliotecas nas Maps JavaScript API.

Carregamento síncrono da API

Na tag script que carrega as Maps JavaScript API, é possível omitir o atributo async e o parâmetro callback. Essa ação bloqueia o carregamento da API até que seu 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 seja exibido em uma página, é necessário reservar um lugar para ele. Normalmente, isso é feito criando um elemento div nomeado e obtendo uma referência para esse elemento no modelo de objetos do documento (DOM) do navegador.

No exemplo acima, usamos CSS para definir a altura do div do mapa para "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. Observe que os divs normalmente herdam a largura de seu elemento contêiner. Divs vazios normalmente têm a altura 0. Por esse motivo, sempre defina explicitamente uma altura no <div>.

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

A resolução inicial para exibir o mapa é definida pela propriedade zoom, com zoom 0 correspondendo a um mapa do planeta com o zoom mais distante possível, e níveis mais altos de zoom aumentando a resolução da exibição do mapa. Especifique o nível de zoom como inteiro.

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 nas Maps JavaScript API são divididas em "blocos" e "níveis de zoom" de mapa. 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ê consegue ver em cada nível de zoom:

  • 1: Mundo
  • 5: Terra/continente
  • 10: Cidade
  • 15: Ruas
  • 20: Prédios

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

Para obter informações sobre como as Maps JavaScript API carregam blocos de acordo com o nível de zoom atual, consulte Coordenadas de bloco na documentação dos tipos de mapa.

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 de mapa, especifique um elemento HTML <div> na página como contêiner para o mapa. Os nós HTML são filhos do objeto JavaScript document. A referência a esse elemento é obtida por meio do método document.getElementById().

Esse 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 sua definição é 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) passados.

Solução de problemas

Para ajudar seu código de mapas a funcionar rapidamente, Brendan Kenny e Mano Marks apontam alguns erros comuns e como corrigi-los neste vídeo.

Se o código não funciona:

  • Procure erros de digitação. Lembre-se de que 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 as propriedades zoom e center, nas opções do mapa, foram especificadas.
    • Verifique se foi declarado um elemento div no qual o mapa será exibido na tela.
    • Verifique se o elemento div para o mapa tem uma altura. Por padrão, os elementos div são criados com uma altura de 0, o que os torna invisíveis.
    Consulte nossos exemplos para obter uma implementação de referência.
  • Use um depurador JavaScript para ajudar a identificar problemas, como o depurador disponível nas ferramentas para desenvolvedor do Chrome. Comece verificando a existência de erros no console JavaScript.
  • Publique dúvidas no Stack Overflow. A página Support oferece diretrizes sobre a melhor maneira de publicar dúvidas.

Enviar comentários sobre…

Google Maps JavaScript API
Google Maps JavaScript API
Precisa de ajuda? Acesse nossa página de suporte.