Como fazer upgrade do aplicativo da API Maps JavaScript da V2 para a V3

A API Maps JavaScript v2 não está mais disponível desde 26 de maio de 2021. Como resultado, os mapas da v2 do seu site deixarão de funcionar e vão retornar erros JavaScript. Para continuar usando mapas no seu site, migre para a API Maps JavaScript v3. Este guia ajudará você durante o processo.

Visão geral

Cada aplicativo terá um processo de migração um pouco diferente. No entanto, há algumas etapas comuns a todos os projetos:

  1. Receba uma nova chave. A API Maps JavaScript agora usa o Console do Google Cloud para gerenciar chaves. Se você ainda usa uma chave da v2, consiga a nova chave antes de iniciar a migração.
  2. Atualizar o bootstrap de API. A maioria dos aplicativos carrega a API Maps JavaScript v3 com o seguinte código:
    <script src="//maps.googleapis.com/maps/api/js?key=YOUR_API_KEY"></script>
  3. Atualize seu código. A quantidade de mudança necessária dependerá muito do seu aplicativo. Estas são algumas das mudanças mais comuns:
    • Sempre faça referência ao namespace google.maps. Na v3, todo o código da API Maps JavaScript é armazenado no namespace google.maps.* em vez de no namespace global. A maioria dos objetos também foi renomeada como parte desse processo. Por exemplo, em vez de GMap2, agora você carregará google.maps.Map.
    • Remova todas as referências a métodos obsoletos. Diversos métodos utilitários de uso geral foram removidos, como GDownloadURL e GLog. Substitua essa funcionalidade por bibliotecas de utilitários de terceiros ou remova essas referências do código.
    • (Opcional) Adicionar bibliotecas ao código. Muitos recursos foram externalizados em bibliotecas de utilitários para que cada app precise carregar apenas as partes da API que serão usadas.
    • (Opcional) Configure seu projeto para usar variáveis externas v3. As variáveis externas v3 podem ser usadas para ajudar a validar seu código com o closure Compiler ou para acionar o preenchimento automático no seu ambiente de desenvolvimento integrado. Saiba mais sobre Compilação avançada e variáveis externas.
  4. Teste e itere. Nesse ponto, você ainda terá trabalho a fazer, mas a boa notícia é que você já está no caminho certo para usar seu novo aplicativo de mapas v3.

Alterações na V3 da API Maps JavaScript

Antes de planejar a migração, é preciso entender as diferenças entre a API Maps JavaScript v2 e a API Maps JavaScript v3. A versão mais recente da API Maps JavaScript foi desenvolvida do zero, com foco em técnicas modernas de programação JavaScript, maior uso de bibliotecas e uma API simplificada. Muitos recursos novos foram adicionados à API, e vários recursos familiares foram alterados ou até mesmo removidos. Esta seção destaca algumas das principais diferenças entre as duas versões.

Algumas das mudanças na API v3 incluem:

  • Uma biblioteca principal otimizada. Muitas das funções complementares foram movidas para bibliotecas, ajudando a reduzir os tempos de carregamento e de análise da API Core, permitindo que seu mapa seja carregado rapidamente em qualquer dispositivo.
  • Melhoria no desempenho de vários recursos, como renderização de polígonos e posicionamento de marcadores.
  • Uma nova abordagem aos limites de uso do lado do cliente para acomodar melhor os endereços compartilhados usados por proxies móveis e firewalls corporativos.
  • Adicionado suporte a vários navegadores modernos e navegadores para dispositivos móveis. A compatibilidade com o Internet Explorer 6 foi removida.
  • Remoção de muitas das classes auxiliares de uso geral ( GLog ou GDownloadUrl). Atualmente, existem muitas bibliotecas JavaScript excelentes que oferecem funcionalidades semelhantes, como closure ou jQuery (links em inglês).
  • Uma implementação do Street View em HTML5 que pode ser carregada em qualquer dispositivo móvel.
  • Panoramas personalizados do Street View com suas fotos, permitindo que você compartilhe panoramas de pistas de esqui, casas à venda ou outros lugares interessantes.
  • Personalizações de mapas estilizados que permitem mudar a exibição de elementos no mapa básico de acordo com seu estilo visual exclusivo.
  • Suporte a vários novos serviços, como ElevationService e Distance Matrix.
  • Um serviço de rotas aprimorado oferece trajetos alternativos, otimização de trajetos (soluções aproximadas para o problema do vendedor de viagens), rotas de bicicleta (com camada de bicicleta), rotas de transporte público e rotas arrastáveis.
  • Um formato atualizado de geocodificação que fornece informações de tipo mais precisas do que o valor accuracy da API Geocoding v2.
  • Compatibilidade com várias janelas de informações em um único mapa.

Fazer upgrade do aplicativo

Sua nova chave

A API Maps JavaScript v3 usa o novo sistema de chaves da v2. Talvez você já esteja usando uma chave da v3 com seu aplicativo. Nesse caso, nenhuma alteração é necessária. Para verificar, confira o URL de onde você carrega a API Maps JavaScript para o parâmetro key. Se o valor da chave começar com "ABQIAA", você está usando uma chave da v2. Se você tiver uma chave v2, vai precisar fazer upgrade para uma v3 como parte da migração, o que vai:

A chave é transmitida durante o carregamento da API Maps JavaScript v3. Saiba mais sobre como gerar chaves de API.

Se você é cliente das APIs do Google Maps for Work, pode usar um ID de cliente com o parâmetro client em vez de key. Os IDs de cliente ainda são aceitos na API Maps JavaScript v3 e não precisam passar pelo processo de upgrade de chave.

Carregar a API

A primeira modificação que você precisa fazer no código envolve o modo de carregamento da API. Na v2, a API Maps JavaScript é carregada com uma solicitação para http://maps.google.com/maps. Se estiver carregando a API Maps JavaScript v3, você precisará fazer as seguintes alterações:

  1. Carregar a API de //maps.googleapis.com/maps/api/js
  2. Remova o parâmetro file.
  3. Atualize o parâmetro key com a nova chave da v3. Os clientes das APIs Google Maps for Work devem usar um parâmetro client.
  4. (Somente Plano Premium da Plataforma Google Maps) Verifique se o parâmetro client foi fornecido conforme explicado no Guia para desenvolvedores do Plano Premium da Plataforma Google Maps.
  5. Remova o parâmetro v para solicitar a versão lançada mais recente ou altere o valor de acordo com o esquema de controle de versões v3.
  6. (Opcional) Substitua o parâmetro hl por language e preserve o valor dele.
  7. (Opcional) Adicione um parâmetro libraries para carregar bibliotecas opcionais.

No caso mais simples, o bootstrap da v3 especificará somente seu parâmetro de chave de API:

<script src="//maps.googleapis.com/maps/api/js?key=YOUR_API_KEY"></script>

O exemplo abaixo solicita a versão mais recente da API Maps JavaScript v2 em alemão:

<script src="//maps.google.com/maps?file=api&v=2.x&key=YOUR_API_KEY&hl=de"></script>

O exemplo abaixo é uma solicitação equivalente para a v3.

<script src="//maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&language=de"></script>

Apresentação do namespace google.maps

É provável que a mudança mais perceptível na API Maps JavaScript v3 seja a introdução do namespace google.maps. A API v2 coloca todos os objetos no namespace Global por padrão, o que pode resultar em colisões de nomenclatura. Na v3, todos os objetos estão localizados no namespace google.maps.

Ao migrar seu aplicativo para a v3, será necessário alterar o código para usar o novo namespace. Infelizmente, pesquisar "G" e substituí-lo por "google.maps" não funcionará completamente, mas é uma boa regra prática a ser aplicada ao revisar seu código. Veja a seguir alguns exemplos de classes equivalentes nas v2 e v3.

v2 v3
GMap2 google.maps.Map
GLatLng google.maps.LatLng
GInfoWindow google.maps.InfoWindow
GMapOptions google.map.MapOptions
G_API_VERSION google.maps.version
GPolyStyleOptions google.maps.PolygonOptions
or google.maps.PolylineOptions

Remover código obsoleto

A API Maps JavaScript v3 tem paralelos com a maioria das funcionalidades da v2. No entanto, algumas classes não são mais compatíveis. Como parte da migração, substitua essas classes por bibliotecas de utilitários de terceiros ou remova essas referências do código. Existem muitas bibliotecas JavaScript excelentes que oferecem funcionalidade semelhante, como closure ou jQuery.

As seguintes classes não têm paralelo na API Maps JavaScript v3:

GBoundsGLanguage
GBrowserIsCompatibleGLayer
GControlGLog
GControlAnchorGMercatorProjection
GControlImplGNavLabelControl
GControlPositionGObliqueMercator
GCopyrightGOverlay
GCopyrightCollectionGPhotoSpec
GDownloadUrlGPolyEditingOptions
GDraggableObjectGScreenOverlay
GDraggableObjectOptionsGStreetviewFeatures
GFactualGeocodeCacheGStreetviewLocation
GGeoAddressAccuracyGStreetviewOverlay
GGeocodeCacheGStreetviewUserPhotosOptions
GGoogleBarGTileLayerOptions
GGoogleBarAdsOptionsGTileLayerOverlayOptions
GGoogleBarLinkTargetGTrafficOverlayOptions
GGoogleBarListingTypesGUnload
GGoogleBarOptionsGXml
GGoogleBarResultListGXmlHttp
GInfoWindowTabGXslt
GKeyboardHandler

Comparar código

Vamos comparar dois aplicativos bastante simples que foram escritos com as APIs v2 e v3.

<!DOCTYPE html>
<html>
  <head>
    <script src="//maps.google.com/maps?file=api&v=2&key=YOUR_API_KEY"></script>
    <style>
      html, body, #map { height: 100%; margin: 0; }
    </style>
    <script>
    function initialize() {
      if (GBrowserIsCompatible()) {
        var map = new GMap2(
            document.getElementById('map'));
        map.setCenter(new GLatLng(37.4419, -122.1419), 13);
        map.setUIToDefault();

        map.addOverlay(new GMarker(new GLatLng(37.4419, -122.1419)));

      }
    }
    </script>
  </head>
  <body onload="initialize()" onunload="GUnload()">
    <div id="map"></div>
  </body>
</html>
    
<!DOCTYPE html>
<html>
  <head>
    <script src="//maps.googleapis.com/maps/api/js?key=YOUR_API_KEY"></script>
    <style>
      html, body, #map { height: 100%; margin: 0; }
    </style>
    <script>
    function initialize() {
      var map = new google.maps.Map(
        document.getElementById('map'), {
          center: new google.maps.LatLng(37.4419, -122.1419),
          zoom: 13,
          mapTypeId: google.maps.MapTypeId.ROADMAP
      });

      var marker = new google.maps.Marker({
            position: new google.maps.LatLng(37.4419, -122.1419),
            map: map
      });

    }
    google.maps.event.addDomListener(window, 'load', initialize);
    </script>
  </head>
  <body>
    <div id="map"></div>
  </body>
</html>

Como você pode notar, há várias diferenças entre os dois aplicativos. As principais mudanças incluem:

  • O endereço de onde a API é carregada foi alterado.
  • Os métodos GBrowserIsCompatible() e GUnload() não são mais necessários na v3 e foram removidos da API.
  • O objeto GMap2 é substituído por google.maps.Map como o objeto central na API.
  • Agora, as propriedades são carregadas por meio das classes Options. No exemplo acima, definimos as três propriedades necessárias para carregar um mapa (center, zoom e mapTypeId) usando um objeto MapOptions embutido.
  • Na v3, a IU padrão é ativada por padrão. É possível desativar isso definindo a propriedade disableDefaultUI como verdadeira no objeto MapOptions.

Resumo

Agora, você já conhece alguns dos principais pontos envolvidos na migração da API Maps JavaScript da v2 para a v3. Há mais informações que você talvez precise saber, mas isso vai depender do seu aplicativo. Nas seções a seguir, incluímos instruções de migração para casos específicos que você pode encontrar. Além disso, há vários recursos que podem ser úteis durante o processo de upgrade.

Se você tiver dúvidas ou problemas com este artigo, use o link ENVIAR FEEDBACK na parte de cima desta página.

Referência detalhada

Nesta seção, você encontra uma comparação detalhada dos recursos mais usados nas versões 2 e 3 da API Maps JavaScript. Cada seção da referência foi projetada para ser lida individualmente. Recomendamos que você não leia esta referência na íntegra. Em vez disso, use esse material para ajudar na migração caso a caso.

  • Eventos - como registrar e tratar eventos.
  • Controles: manipular os controles de navegação que aparecem no mapa.
  • Sobreposições: adicionar e editar objetos no mapa.
  • Tipos de mapa - os blocos que compõem o mapa de base.
  • Camadas: adicionar e editar conteúdo como um grupo, como camadas KML ou de trânsito.
  • Serviços: trabalhar com os serviços de geocodificação, rotas ou Street View do Google.

Eventos

O modelo de eventos da API Maps JavaScript v3 é semelhante ao usado na v2, embora muita coisa tenha mudado internamente.

Controles

A API Maps JavaScript exibe controles de IU que permitem que os usuários interajam com seu mapa. Você pode usar a API para personalizar a aparência desses controles.

Sobreposições

As sobreposições refletem objetos que você "adiciona" ao mapa para designar pontos, linhas, áreas ou coleções de objetos.

Tipos de mapa

Os tipos de mapa disponíveis nas versões v2 e v3 são um pouco diferentes, mas todos os tipos básicos de mapa estão disponíveis nas duas versões da API. Por padrão, a v2 usa blocos de mapa de vias "pintados" padrão. No entanto, a v3 exige que um tipo de mapa específico seja fornecido ao criar um objeto google.maps.Map.

Camadas

Camadas são objetos no mapa que consistem em uma ou mais sobreposições. Eles podem ser manipulados como uma única unidade e geralmente refletem coleções de objetos.

Serviços