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

Fazer o upgrade do aplicativo do Google Maps JavaScript API da v2 para a v3

A versão 2 da Google Maps JavaScript API não está mais disponível. O objetivo do guia é ajudar os desenvolvedores que já usam a Google Maps JavaScript API v2 a migrar o código para a versão 3.

Muita coisa mudou da Google Maps JavaScript API v2 para a v3. Quando você começar a trabalhar com a nova API, perceberá rapidamente que não se trata apenas de um upgrade incremental. A boa notícia é que adicionamos vários recursos incríveis e aprimoramos a usabilidade geral das API, do ponto de vista dos desenvolvedores. Se você está planejando fazer o upgrade da Google Maps JavaScript API v2 para a Google Maps JavaScript API v3, este guia ajudará durante o processo e destacará algumas das mudanças mais comuns para usuários da API v2.

Visão geral

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

  1. Obter uma nova chave. A Google Maps JavaScript API agora usa o Google API Console para gerenciar chaves. Antes de iniciar a migração, não deixe de obter uma nova chave de API.
  2. Atualizar o bootstrap de API. A maioria dos aplicativos carrega a Google Maps JavaScript API v3 com o seguinte código:
    <script type="text/javascript" src="//maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&sensor=true_OR_false"></script>
    
  3. Atualizar o código. A extensão das mudanças necessárias dependerá muito do aplicativo. As alterações comuns incluem:
    • Sempre faça referência ao namespace google.maps. Na v3, todo o código da Google Maps JavaScript API é armazenado no namespace google.maps.* em vez de no namespace global. Como parte desse processo, a maioria dos objetos também foi renomeada. Por exemplo, em vez de GMap2, você carregará google.maps.Map.
    • Remover todas as referências a métodos obsoletos. Diversos métodos de 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 exportados para bibliotecas de utilitários, permitindo que cada aplicativo carregue apenas as partes da API que serão usadas.
    • (Opcional) Configurar o projeto para usar funções externas da v3. As funções externas da v3 podem ser usadas para ajudar a validar o código com o Closure Compiler ou para acionar o preenchimento automático na IDE. Saiba mais sobre Compilação avançada e funções externas.
  4. Testar e iterar. Nesse ponto, ainda há trabalho a ser feito, mas a boa notícia é que você já está bem adiantando no caminho para o novo aplicativo de mapas v3.

Alterações na versão 3 da Google Maps JavaScript API

Antes de planejar a migração, você deve reservar um tempo para compreender as diferenças entre a Google Maps JavaScript API v2 e a Google Maps JavaScript API v3. A versão mais recente da Google Maps JavaScript API foi criada do zero, priorizando técnicas de programação modernas de JavaScript, maior uso de bibliotecas e uma API simplificada. Muitos novos recursos foram adicionados à API e diversos 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 suplementares foram mudadas para bibliotecas, ajudando a reduzir os tempos de carga e análise da Core API, que permite carregamentos de mapas com rapidez em qualquer dispositivo.
  • Maior desempenho em diversos recursos, como renderização de polígonos e posicionamento de marcadores.
  • Uma nova abordagem dos limites de uso do lado do cliente para acomodar melhor os endereços compartilhados usados por proxies móveis e firewalls corporativos.
  • Maior compatibilidade com diversos navegadores modernos e navegadores móveis. A compatibilidade com o Internet Explorer 6 foi removida.
  • Foram removidas várias das classes auxiliares de uso geral (GLog ou GDownloadUrl). Atualmente, existem diversas bibliotecas JavaScript excelentes que oferecem funcionalidades similares, 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 Styled Maps que permitem alterar a exibição de elementos no mapa básico de acordo com seu estilo visual exclusivo.
  • Compatibilidade com vários novos serviços, como ElevationService e Distance Matrix.
  • Um serviço aprimorado de rotas oferece rotas alternativas, otimização de rotas (soluções aproximadas para o problema do vendedor viajante), rotas de bicicleta (com uma camada de bicicleta), rotas de trânsito e rotas arrastáveis.
  • Um formato atualizado de geocodificação que oferece informações de tipo mais precisas que o valor accuracy da Google Maps Geocoding API v2.
  • Suporte a várias janelas de informações em um único mapa

Fazer upgrade do aplicativo

Sua nova chave

A Google Maps JavaScript API v3 usa um novo sistema de chaves. Isso significa que a chave da v2 não funcionará com aplicativos da v3. A adição de uma chave da v3 antes de implantar o aplicativo em produção:

  • Permite que você veja relatórios de uso no Google API Console.
  • Permite que você compre cotas adicionais quando necessário.
  • Oferece ao Google uma forma de entrar em contato com você sobre seu aplicativo.

A chave é passada no carregamento da Google Maps JavaScript API v3. Para gerar uma chave:

  1. Acesse o Google API Console e faça login com sua Conta do Google.
  2. Clique no link Services no menu à esquerda e ative o serviço Google Maps JavaScript API v3.
  3. Após a ativação do serviço, a chave de API será disponibilizada na página API Access, na seção Simple API Access. Aplicativos de Maps API usam a chave para aplicativos de navegador.

IDs do cliente para licenças do Maps APIs for Work

Se você tiver uma licença do Google Maps APIs for Work, precisará usar um ID do cliente em vez de uma chave. Observe que não é possível usar os dois ao mesmo tempo. Os IDs do cliente são semelhantes às chaves, com as seguintes diferenças:

  • Aplicativos das Google Maps APIs que usam um ID do cliente podem ter acesso a recursos ou limites adicionais, como Maps Analytics.
  • O ID do cliente é criado pelo Google Cloud Support e fornecido em sua carta de boas-vindas do Maps APIs for Work. Não use o Google API Console para criar ou encontrar seu ID do cliente.
  • Durante a carga da Google Maps JavaScript API, você usará o parâmetro client em vez do parâmetro key. Por exemplo:
    <script src="//maps.googleapis.com/maps/api/js?v=3&client=gme-yourclientid&sensor=true_or_false" type="text/javascript"></script>
  • IDs do cliente são sempre prefixados com gme-.

Carregar a API

A primeira modificação a ser feita no código envolve a forma de carregamento da API. Na v2, a Google Maps JavaScript API é carregada por meio de uma solicitação enviada para http://maps.google.com/maps. Se você carregar a Google Maps JavaScript API v3, será necessário fazer as seguintes alterações:

  1. Carregue a API de //maps.googleapis.com/maps/api/js
  2. Remova o parâmetro file.
  3. Não deixe de incluir o parâmetro obrigatório sensor.
  4. Atualize o parâmetro key com a nova chave da v3. Clientes do Google Maps APIs for Work devem usar um parâmetro client.
  5. (Somente para Google Maps APIs Premium Plan) Verifique se o parâmetro client é fornecido como explicado no Guia do desenvolvedor do Google Maps APIs Premium Plan.
  6. Remova o parâmetro v para solicitar a versão lançada mais recentemente ou altere seu valor de acordo com o esquema de controle de versões da v3.
  7. (Opcional) Substitua o parâmetro hl por language e preserve seu valor.
  8. (Opcional) Adicione um parâmetro libraries para carregar bibliotecas opcionais.

No caso mais simples, o bootstrap da v3 especificará apenas a chave de API e o parâmetro sensor:

<script type="text/javascript" src="//maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&sensor=false"></script>

O exemplo abaixo solicita a versão mais recente (experimental) das Maps JavaScript API v2 em alemão:

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

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

<script type="text/javascript" src="//maps.googleapis.com/maps/api/js?v=3.exp&sensor=false&key=YOUR_API_KEY&language=de"></script>

Controle de versões

Não é necessário carregar uma versão específica na v3. Se você omitir o parâmetro de versão, obterá a versão experimental mais recente da API. Se preferir, você poderá informar um número de versão específico, a versão mais recente (experimental) ou a versão mais estável, congelada.

A tabela a seguir associa o esquema de versões da v2 e da v3.

v2 v3 Caso de uso
2.s 3.0 Versão congelada. Versão mais antiga disponível.
2 3 Versão de lançamento. Versão estável mais recente.
2.x 3.exp Versão experimental.

Importante: O ANS do Google Maps APIs Premium Plan não se aplica à versão experimental. Os aplicativos do Google Maps APIs Premium Plan devem usar a versão de lançamento ou congelada atual para manterem a cobertura do ANS.

Apresentação do namespace google.maps

A mudança mais evidente da Google Maps JavaScript API v3 é, provavelmente, 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.

Na migração do aplicativo para a v3, será necessário alterar o código para usar o novo namespace. Infelizmente, pesquisar por "G" e substituir por "google.maps" não resolverá todo o problema, mas é uma boa regra a ser aplicada na revisão do código. Veja a seguir alguns exemplos de classes equivalentes na v2 e na 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
ou google.maps.PolylineOptions

Remover código obsoleto

A Google Maps JavaScript API v3 tem funcionalidades equivalentes à maioria das funcionalidades da v2. No entanto, algumas classes deixaram de existir. Como parte da migração, você deve substituir essas classes por bibliotecas de utilitários de terceiros ou remover as referências do código. Existem diversas bibliotecas JavaScript excelentes que oferecem funcionalidades similares, como Closure ou jQuery.

As classes a seguir não têm paralelo na Google Maps JavaScript API 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 muito simples que foram escritas com as APIs v2 e v3.

<!DOCTYPE html>
<html>
  <head>
    <script src="//maps.google.com/maps?file=api&v=2&key=YOUR_API_KEY&sensor=false"
        type="text/javascript"></script>
    <style type="text/css">
      html, body, #map { height: 100%; margin: 0; }
    </style>
    <script type="text/javascript">
    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?sensor=false"
        type="text/javascript"></script>
    <style type="text/css">
      html, body, #map { height: 100%; margin: 0; }
    </style>
    <script type="text/javascript">
    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 podemos 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 foi substituído por google.maps.Map como objeto central da API.
  • Agora, as propriedades são carregadas por meio das classes Options. No exemplo acima, definimos três propriedades necessárias para carregar um mapa: center, zoom e mapTypeId, por meio de um objeto MapOptions em linha.
  • Na v3, a IU padrão é ativada por padrão. Isso pode ser alterado definido a propriedade disableDefaultUI como true no objeto MapOptions.

Resumo

Neste ponto, você já percebeu alguns dos principais fatores envolvidos na migração da Google Maps JavaScript API v2 para a Google Maps JavaScript API v3. Ainda há uma grande quantidade de informações que você pode precisar conhecer, mas isso dependerá do aplicativo. Nas seções seguintes, incluímos instruções de migração para casos específicos que você pode encontrar. Além disso, há diversos recursos que poderão ser úteis durante o processo de ugprade.

Se você tiver qualquer dúvida ou pergunta sobre este artigo, use o link Comentários sobre este documento na parte superior da página.

Referência detalhada

Esta seção oferece uma comparação detalhada dos recursos mais populares das versões 2 e 3 da Google Maps JavaScript API. Cada seção da referência foi criada para ser lida individualmente. Não recomendamos que você leia toda a referência. Em vez disso, use esse material como ajuda na migração, caso a caso.

  • Eventos - registro e processamento de eventos.
  • Controles - manipulação dos controles de navegação exibidos no mapa.
  • Sobreposições - adição e edição de objetos no mapa.
  • Tipos de mapa - os blocos que compõem o mapa básico.
  • Camadas - adição e edição e conteúdo como um grupo, como camadas de KML ou trânsito.
  • Serviços - uso dos serviços de geocodificação, rotas ou Street View do Google.

Eventos

O modelo de eventos da Google Maps JavaScript API v3 é semelhante ao usado na v2, mas existe um grande número de mudanças internas.

Controles

A Google Maps JavaScript API exibe controles de IU que permitem a interação dos usuários com o mapa. Use a API para personalizar a aparência dos controles.

Sobreposições

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

Tipos de mapa

Os tipos de mapas disponíveis na v2 e na v3 são ligeiramente 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 via "pintados" padrão. No entanto, a v3 exige a especificação de um tipo de mapa específico na criação de um objeto google.maps.Map.

Camadas

As camadas são objetos do mapa que consistem em uma ou mais sobreposições. Elas podem ser manipuladas como uma única unidade e normalmente refletem coleções de objetos.

Serviços

Enviar comentários sobre…

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