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 vão deixar de funcionar e vão retornar erros de JavaScript. Para continuar usando mapas no seu site, migre para a API Maps JavaScript v3. Este guia vai ajudar você no processo.

Visão geral

Cada aplicativo terá um processo de migração ligeiramente 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 estiver usando uma chave v2, confira se tem uma nova chave de API antes de começar a migração.
  2. Atualize o Bootstrap da 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 vai depender muito do seu aplicativo. Mudanças comuns incluem:
    • Sempre faça referência ao namespace google.maps. Na v3, todo o código da API Maps JavaScript é armazenado no namespaces google.maps.* em vez do namespace global. A maioria dos objetos também foi renomeada como parte desse processo. Por exemplo, em vez de GMap2, você vai carregar google.maps.Map.
    • Remova todas as referências a métodos obsoletos. Vários métodos de utilitário 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 as externas da v3. Os externos da v3 podem ser usados 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 externos.
  4. Teste e itere. Neste ponto, você ainda terá algum trabalho a fazer, mas a boa notícia é que você estará no caminho para o novo aplicativo do Maps v3.

Mudanças na V3 da API Maps JavaScript

Antes de planejar a migração, entenda 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 criada do zero, com foco em técnicas modernas de programação em JavaScript, maior uso de bibliotecas e uma API simplificada. Muitos novos recursos foram adicionados à API, e vários recursos conhecidos foram modificados ou até 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 suplementares foram movidas para bibliotecas, ajudando a reduzir os tempos de carregamento e análise da API Core, o que permite que o 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 para limites de uso do lado do cliente para acomodar melhor os endereços compartilhados usados por proxies móveis e firewalls corporativos.
  • Foi adicionado suporte a vários navegadores modernos e de dispositivos móveis. O suporte para o Internet Explorer 6 foi removido.
  • Muitas das classes auxiliares de finalidade geral foram removidas ( GLog ou GDownloadUrl). Atualmente, existem muitas bibliotecas JavaScript excelentes que oferecem funcionalidades semelhantes, como Closure ou jQuery.
  • Uma implementação do Street View em HTML5 que pode ser carregada em qualquer dispositivo móvel.
  • Panoramas personalizados do Street View com suas próprias 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 de base para corresponder ao seu estilo visual exclusivo.
  • Suporte a vários novos serviços, como o ElevationService e a Distance Matrix.
  • Um serviço de direções aprimorado oferece rotas alternativas, otimização de rotas (soluções aproximadas para o problema do vendedor viajante), direções para ciclistas (com a camada de ciclismo), direções de transporte público e direções 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.
  • Suporte a várias janelas de informações em um único mapa

Fazer upgrade do aplicativo

Sua nova chave

A API Maps JavaScript v3 usa um novo sistema de chaves da v2. Talvez você já esteja usando uma chave v3 com seu aplicativo. Nesse caso, não é necessário fazer mudanças. Para verificar, verifique o URL em que você carrega a API Maps JavaScript para o parâmetro key. Se o valor da chave começar com "ABQIAA", você estará usando uma chave v2. Se você tiver uma chave v2, será necessário fazer upgrade para uma chave v3 como parte da migração, que:

  • Permite que você monitore o uso da API no console do Google Cloud.
  • Permite que você compre cota extra quando necessário.
  • Oferece ao Google uma forma de entrar em contato com você sobre seu aplicativo.

A chave é transmitida ao carregar a API Maps JavaScript v3. Saiba mais sobre como gerar chaves de API.

Se você for cliente das APIs Maps for Work, talvez esteja usando um ID do 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ê vai precisar fazer no código envolve como carregar a API. Na v2, você carrega a API Maps JavaScript com uma solicitação para http://maps.google.com/maps. Se você estiver carregando a API Maps JavaScript v3, vai precisar fazer as seguintes mudanças:

  1. Carregar a API de //maps.googleapis.com/maps/api/js
  2. Remova o parâmetro file.
  3. Atualize o parâmetro key com sua nova chave v3. Os clientes das APIs Maps for Work precisam usar um parâmetro client.
  4. (Somente no plano Premium da Plataforma Google Maps) Verifique se o parâmetro client é 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 mude o valor de acordo com o esquema de controle de versão 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 v3 especifica apenas o 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

Provavelmente, a mudança mais perceptível na API Maps JavaScript v3 é 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 nomes. Na v3, todos os objetos estão localizados no namespace google.maps.

Ao migrar seu aplicativo para a v3, você vai precisar mudar o código para usar o novo namespace. Infelizmente, pesquisar "G" e substituir por "google.maps." não vai funcionar completamente, mas é uma boa regra geral a ser aplicada ao revisar o código. Confira abaixo alguns exemplos de classes equivalentes na 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 para a maioria das funcionalidades da v2. No entanto, algumas classes não têm mais suporte. 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 funcionalidades semelhantes, como Closure ou jQuery.

As classes a seguir 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 simples criados 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 ver, 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 inline.
  • Na v3, a IU padrão é ativada por padrão. Para desativar esse recurso, defina a propriedade disableDefaultUI como "true" no objeto MapOptions.

Resumo

Neste ponto, você já terá uma ideia de alguns dos principais pontos envolvidos na migração da v2 para a v3 da API Maps JavaScript. Talvez você precise de mais informações, 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 problemas ou dúvidas sobre este artigo, use o link ENVIAR FEEDBACK na parte de cima da página.

Referência detalhada

Esta seção oferece uma comparação detalhada dos recursos mais usados da v2 e da v3 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 este material para ajudar na migração de cada caso.

  • Eventos - como registrar e tratar eventos.
  • Controles: manipulação dos controles de navegação que aparecem no mapa.
  • Sobreposições: adição e edição de objetos no mapa.
  • Tipos de mapa - os blocos que compõem o mapa de base.
  • Camadas: adição e edição de conteúdo como um grupo, como camadas KML ou de tráfego.
  • Serviços: trabalhar com os serviços de geocodificação, direções ou do Street View do Google.

Eventos

O modelo de eventos da API Maps JavaScript v3 é semelhante ao usado na v2, embora muitas coisas tenham mudado em segundo plano.

Controles

A API Maps JavaScript mostra controles de interface que permitem a interação dos usuários com o mapa. É possível 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 na v2 e na v3 são um pouco diferentes, mas todos os tipos de mapa básicos 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

As 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