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

Controle de versões

A equipe da Google Maps JavaScript API atualiza regularmente a API com novos recursos, correções de erros e melhoras de desempenho. Esta página descreve as versões da API disponíveis para uso nos aplicativos em ambientes de teste ou produção. As versões de API têm os seguintes nomes:

  • Experimental
  • Lançada
  • Congelada

Também oferecemos práticas recomendadas para gerenciar procedimentos de controle de versões de acordo com o tipo ou o propósito do aplicativo.

Progressão e tipos de versões

A cada trimestre, geramos uma nova versão sem número, que é lançada para uso público como a versão experimental. Ao mesmo tempo, a versão experimental anterior se torna a versão lançada, e a versão lançada anterior torna-se a versão congelada. Esse processo é chamado de progressão de versões.

Ao longo do trimestre, continuamos a adicionar correções de erros às versões experimental e lançada. Essas atualizações são registradas nas notas de versão da Google Maps JavaScript API.

Indique a versão de API que quer carregar no aplicativo especificando o parâmetro v na solicitação de bootstrap da Google Maps JavaScript API. As opções a seguir são permitidas:

  • A versão experimental, especificada com v=3.exp.
  • A versão lançada, especificada com v=3.
  • Um número de versão específico. Por exemplo, v=3.25 ou v=3.26.

Se você não especificar explicitamente uma versão, receberá a versão experimental por padrão se estiver no plano padrão (inclusive clientes que não forneceram uma chave). Se você estiver no plano premium e não especificar uma versão, receberá por padrão a versão de lançamento.

A versão experimental

A versão experimental (no momento, 3.27) contém os mais recentes recursos e correções de erro disponibilizados publicamente. As alterações efetuadas na versão experimental não têm estabilidade de recursos garantida. Recomendamos que você teste regularmente os aplicativos com a versão experimental, o que pode ser feito adicionando 3.27 no carregamento da API. Se você gosta de viver perigosamente, pode adicionar v=3.exp para receber sempre a versão experimental atual, com todos seus recursos mais recentes.

Especifique a versão experimental com este bootstrap:

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

A versão lançada

Aplicamos continuamente correções de erros na versão lançada, além de garantir que o conjunto de recursos permaneça estável. As correções estão listadas nas notas de versão.

A versão lançada atual é 3.26. Solicite essa versão com um destes bootstraps:

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

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

A versão congelada

Quando lançamos uma nova versão numerada, congelamos a versão lançada anterior, o que significa que ela não será mais regularmente atualizada com correções de problemas. No entanto, podemos fazer algumas alterações ocasionais. Por exemplo, se houver um motivo legal para isso.

A cada versão congelada introduzida, removemos a versão congelada anterior. A especificação de uma versão removida, como v=3.0, retorna sempre a versão congelada atual.

A versão congelada atual é 3.25. Você pode solicitá-la com este bootstrap:

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

Práticas recomendadas

A equipe da Google Maps JavaScript API se esforça ao máximo para manter a compatibilidade entre versões diferentes da API. No entanto, para continuar a oferecer um serviço moderno, bem como por motivos operacionais, fazemos ocasionalmente alterações que podem interagir com recursos existentes. Nesses momentos, pode ser necessário fazer ajustes ao código (principalmente nos aplicativos mais avançados) que usa a Google Maps JavaScript API para que ele continue a funcionar da forma esperada. Apresentamos abaixo as práticas recomendadas para uso de versões para diversos cenários comuns.

Para aplicativos de alta disponibilidade e alto tráfego

Disposto a algum trabalho extra para garantir estabilidade e disponibilidade

Para garantir que a progressão das versões não cause nenhum problema, recomendamos especificar explicitamente o número da versão lançada atual da API no bootstrap. Por exemplo, v=3.26. Para evitar o uso da versão congelada da API ao longo do tempo, é importante assinar as notificações de progressão de versão do Google no grupo de notificações e anúncios da Google Maps JS API v3.

Após o rollover de uma versão (a cada trimestre), o sistema de produção solicitará a versão congelada da API. Nesse momento, recomendamos a configuração de um ambiente de preparação/desenvolvimento para testar aplicativos com a nova versão de lançamento da API. Se ocorrerem problemas, você poderá fazer os ajustes necessários no código. Quando você estiver confiante de que o aplicativo executa sem problemas com a nova versão da API, implante as correções necessárias (se houver) e, ao mesmo tempo, atualize o aplicativo para solicitar o número de versão correspondente à nova versão lançada.

Para aplicativos regulares

Recomendamos especificar v=3 na solicitação de bootstrap. Isso significa que você sempre obtém a versão lançada atual da Google Maps JavaScript API, que já passou por grandes volumes de tráfego e pelas correções de erro necessárias. Na maioria dos casos, nenhuma ação será necessária na progressão de uma versão. No entanto, para garantir que o aplicativo continue a funcionar sem problemas, recomendamos assinar as notificações de progressão de versão do Google no grupo de notificações e anúncios da Google Maps JS API v3.

Após uma progressão, o aplicativo passa a usar uma nova versão da Google Maps JavaScript API. Inspecione também as notas de versão para ficar a par de qualquer alteração que pode afetá-lo. Se você notar que alguma coisa no aplicativo não funciona corretamente, volte para a versão antiga especificando explicitamente o número da versão congelada atual na solicitação de bootstrap enquanto efetua os ajustes necessários no código.

Para aplicativos de vanguarda

Acesso antecipado aos mais recentes recursos

Para aplicativos onde a disponibilidade contínua é menos crítica, recomendamos obter todos os recursos mais recentes solicitando a versão experimental (v=3.exp) da Google Maps JavaScript API. A versão experimental é totalmente testada pela Google antes do lançamento semanal e, no geral, é bastante estável. No entanto, o ciclo de lançamento semanal significa que são necessários cuidados adicionais para garantir que o aplicativo continue a funcionar da forma esperada.

Verificar versão

Para depuração, usamos a propriedade google.maps.version para obter a versão atual da Google Maps JavaScript API no aplicativo. O código a seguir escreve a versão da API no console do navegador. (Para obter mais informações sobre o console do navegador, consulte o guia de verificação de erros no navegador.)

<!DOCTYPE html>
<html>
  <head>
    <title>Display Google Maps API Version</title>
  </head>
  <body>
    <script>
      function initMap() {
        // Add your map here.
        console.log('Google Maps API version: ' + google.maps.version);
      }
    </script>
    <script src="https://maps.googleapis.com/maps/api/js?YOUR_API_KEY&callback=initMap"
    async defer></script>
  </body>
</html>

Documentação das versões de API

O guia do desenvolvedor sempre descreve a versão experimental.

Além disso, há uma referência mantida separadamente para cada versão:

Enviar comentários sobre…

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