Cómo actualizar tu aplicación de la API de Maps JavaScript de la versión 2 a la 3

La API de Maps JavaScript v2 dejó de estar disponible el 26 de mayo de 2021. Como resultado, los mapas v2 de tu sitio dejarán de funcionar y mostrarán errores de JavaScript. Para seguir usando mapas en tu sitio, migra a la versión 3 de la API de Maps JavaScript. Esta guía te ayudará durante el proceso.

Descripción general

Cada aplicación tendrá un proceso de migración un poco diferente; sin embargo, hay algunos pasos que son comunes a todos los proyectos:

  1. Obtén una clave nueva. La API de Maps JavaScript ahora usa la consola de Google Cloud para administrar las claves. Si todavía usas una clave v2, asegúrate de obtener tu nueva clave de API antes de comenzar la migración.
  2. Actualiza el arranque de tu API. La mayoría de las aplicaciones cargan la API de Maps JavaScript versión 3 con el siguiente código:
    <script src="//maps.googleapis.com/maps/api/js?key=YOUR_API_KEY"></script>
    
  3. Actualiza el código. La cantidad de cambios necesarios dependerá mucho de tu aplicación. Entre los cambios comunes, se incluyen los siguientes:
    • Consulta siempre el espacio de nombres google.maps. En la versión 3, todo el código de la API de Maps JavaScript se almacena en el espacio de nombres google.maps.* en lugar del espacio de nombres global. También se cambió el nombre de la mayoría de los objetos como parte de este proceso. Por ejemplo, en lugar de GMap2, ahora cargarás google.maps.Map.
    • Quita las referencias a los métodos obsoletos. Se quitaron algunos métodos de utilidad de uso general, como GDownloadURL y GLog. Reemplaza esta funcionalidad con bibliotecas de utilidades de terceros o quita estas referencias de tu código.
    • (Opcional) Agrega bibliotecas a tu código. Muchas funciones se externalizaron en bibliotecas de utilidades para que cada app solo tenga que cargar las partes de la API que se utilizarán.
    • Configura tu proyecto para que use los externalizados de la versión 3(opcional). Los externalizados de la v3 se pueden usar para ayudar a validar tu código con el compilador de cierre o para activar el autocompletado en tu IDE. Obtén más información sobre externos y compilación avanzada.
  4. Realiza iteraciones y pruebas. En este punto, aún tienes un trabajo por hacer, pero la buena noticia es que estarás bien encaminado hacia tu nueva aplicación de mapas v3.

Cambios en la versión 3 de la API de Maps JavaScript

Antes de planificar la migración, debes tomarte un tiempo para comprender las diferencias entre la versión 2 de la API de Maps JavaScript y la versión 3 de la API de Maps JavaScript. La versión más reciente de la API de Maps JavaScript se escribió desde cero, con un enfoque en las técnicas modernas de programación de JavaScript, el mayor uso de bibliotecas y una API simplificada. Se agregaron muchas funciones nuevas a la API y se modificaron o incluso quitaron varias funciones familiares. En esta sección, se destacan algunas de las diferencias clave entre las dos versiones.

Entre algunos de los cambios en la API v3 se incluyen los siguientes:

  • Una biblioteca central simplificada. Muchas de las funciones complementarias se trasladaron a las bibliotecas, lo que ayudó a reducir los tiempos de carga y análisis de la API de Core, lo que permite que tu mapa se cargue rápidamente en cualquier dispositivo.
  • Se mejoró el rendimiento de varias funciones, como el procesamiento de polígonos y la posición de marcadores.
  • Un enfoque nuevo de los límites de uso del cliente para adaptarse mejor a las direcciones compartidas que usan los proxies para dispositivos móviles y los firewalls corporativos.
  • Se agregó compatibilidad con varios navegadores modernos y navegadores para dispositivos móviles. Se quitó la compatibilidad con Internet Explorer 6.
  • Se quitaron muchas de las clases auxiliares de uso general ( GLog o GDownloadUrl). Hoy en día, existen muchas bibliotecas de JavaScript excelentes que proporcionan funcionalidades similares, como Closure o jQuery.
  • Una implementación de Street View HTML5 que se carga en cualquier dispositivo móvil.
  • Panorámicas personalizadas de Street View con tus propias fotos, lo que te permite compartir panorámicas de pistas de esquí, casas en venta y otros lugares interesantes.
  • Personalizaciones de Mapas con diseños que te permiten cambiar la visualización de los elementos en el mapa base para que coincidan con tu estilo visual único.
  • Compatibilidad con varios servicios nuevos, como ElevationService y Distance Matrix.
  • Un servicio mejorado de instrucciones sobre cómo llegar proporciona rutas alternativas, optimización de rutas (soluciones aproximadas para el problema de persona que viaja), rutas en bicicleta (con capa de rutas para bicicletas), rutas en transporte público y instrucciones arrastrables.
  • Un formato de Geocoding actualizado que proporciona información de tipo más precisa que el valor accuracy de la API de Geocoding versión 2.
  • Compatibilidad con varias ventanas de información en un solo mapa

Actualizar tu aplicación

Tu clave nueva

La API de Maps JavaScript v3 usa un sistema de claves nuevo de la versión 2. Es posible que ya uses una clave v3 con tu aplicación, en cuyo caso no es necesario realizar ningún cambio. Para verificarlo, comprueba la URL desde la que cargas la API de Maps JavaScript para su parámetro key. Si el valor de la clave comienza con “ABQIAA”, estás usando una clave v2. Si tienes una clave v2, debes actualizar a una clave v3 como parte de la migración, que hará lo siguiente:

La clave se pasa cuando se carga la versión 3 de la API de Maps JavaScript. Obtén más información para generar claves de API.

Ten en cuenta que, si eres cliente de las APIs de Google Maps for Work, puedes usar un ID de cliente con el parámetro client en lugar de usar el parámetro key. Los IDs de cliente aún se admiten en la versión 3 de la API de Maps JavaScript y no es necesario que realices el proceso de actualización de la clave.

Cómo cargar la API

La primera modificación que deberás hacer a tu código implica la forma en que cargas la API. En la versión 2, la API de Maps JavaScript se carga a través de una solicitud a http://maps.google.com/maps. Si cargas la versión 3 de la API de Maps JavaScript, deberás realizar los siguientes cambios:

  1. Carga la API desde //maps.googleapis.com/maps/api/js
  2. Quita el parámetro file.
  3. Actualiza el parámetro key con tu clave v3 nueva. Los clientes de Google Maps APIs for Work deben usar un parámetro client.
  4. Asegúrate de que el parámetro client se proporcione como se explica en la Guía para desarrolladores del plan Premium de Google Maps Platform (solo para el plan Premium de Google Maps Platform).
  5. Quita el parámetro v para solicitar la versión más reciente o cambia su valor según el esquema de control de versiones v3.
  6. Reemplaza el parámetro hl por language y conserva su valor (opcional).
  7. (Opcional) Agrega un parámetro libraries para cargar bibliotecas opcionales.

En el caso más sencillo, la inicialización de la v3 solo especificará el parámetro de tu clave de API:

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

En el siguiente ejemplo, se solicita la versión más reciente de la API de Maps JavaScript v2 en alemán:

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

El siguiente ejemplo es una solicitud equivalente para v3.

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

Presentación del espacio de nombres google.maps

Probablemente, el cambio más notable en la versión 3 de la API de Maps JavaScript sea la introducción del espacio de nombres google.maps. La API v2 coloca todos los objetos en el espacio de nombres global de forma predeterminada, lo que puede generar conflictos de nombres. En la versión 3, todos los objetos se encuentran dentro del espacio de nombres google.maps.

Cuando migres tu aplicación a la versión 3, deberás cambiar tu código para usar el espacio de nombres nuevo. Lamentablemente, buscar "G" y reemplazar por "google.maps." no funcionará por completo; sin embargo, es una buena regla general que debes aplicar cuando revisas tu código. A continuación, se muestran algunos ejemplos de las clases equivalentes en las versiones 2 y 3.

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

Quitar el código obsoleto

En la versión 3 de la API de Maps JavaScript, existen alternativas para la mayor parte de la funcionalidad de la versión 2. Sin embargo, hay algunas clases que ya no se admiten. Como parte de la migración, debes reemplazar estas clases por bibliotecas de utilidades de terceros o quitar estas referencias de tu código. Muchas bibliotecas excelentes de JavaScript proporcionan una funcionalidad similar, como Closure o jQuery.

En la versión 3 de la API de Maps JavaScript, no existen alternativas para las siguientes clases:

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

Comparar el código

Comparemos dos aplicaciones bastante simples que se escribieron con las APIs v2 y 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 puedes ver, existen varias diferencias entre las dos aplicaciones. Entre los cambios destacados se incluyen los siguientes:

  • Se modificó la dirección desde la cual se carga la API.
  • Los métodos GBrowserIsCompatible() y GUnload() ya no son necesarios en la versión 3 y se quitaron de la API.
  • google.maps.Map reemplazó el objeto GMap2 como el objeto central de la API.
  • Ahora, las propiedades se cargan a través de las clases de Options. En el ejemplo anterior, configuramos las tres propiedades necesarias para cargar un mapa (center, zoom y mapTypeId) a través de un objeto MapOptions intercalado.
  • En la v3, se encuentra habilitado el valor predeterminado de la IU. Para inhabilitarlo, configura la propiedad disableDefaultUI como verdadera en el objeto MapOptions.

Resumen

En este punto, ya conocerás algunos de los puntos clave involucrados en la migración de la versión 2 a la 3 de la API de Maps JavaScript. Es posible que necesites saber más información, pero esto dependerá de tu aplicación. En las siguientes secciones, incluimos instrucciones de migración para casos específicos con los que puedes encontrarte. Además, hay varios recursos que pueden resultarte útiles durante el proceso de actualización.

Si tienes problemas o preguntas sobre este artículo, usa el vínculo ENVIAR COMENTARIOS que aparece en la parte superior de esta página.

Referencia detallada

En esta sección, se proporciona una comparación detallada de las funciones más populares de las versiones 2 y 3 de la API de Maps JavaScript. Cada sección de la referencia está diseñada para leerse de manera individual. Te recomendamos que no leas esta referencia completa. En cambio, usa este material para facilitar la migración según el caso.

  • Eventos: registro y manejo de eventos.
  • Controles: Manipulación de los controles de navegación que aparecen en el mapa.
  • Superposiciones: Agregar y editar objetos en el mapa.
  • Tipos de mapas: Son los mosaicos que conforman el mapa base.
  • Capas: Agregar y editar contenido como un grupo, como capas KML o Traffic.
  • Servicios: Cómo trabajar con los servicios de geocodificación, instrucciones sobre cómo llegar y Street View de Google.

Eventos

El modelo de evento de la versión 3 de la API de Maps JavaScript es similar al que se usa en la versión 2, aunque muchos aspectos no visibles han cambiado.

Controles

La API de Maps JavaScript muestra los controles de la IU que permiten a los usuarios interactuar con tu mapa. Puedes usar la API para personalizar la forma en que aparecen estos controles.

Superposiciones

Las superposiciones reflejan los objetos que "agregas" al mapa para designar puntos, líneas, áreas o conjuntos de objetos.

Tipos de mapas

Los tipos de mapas disponibles en la v2 y la v3 son ligeramente diferentes, pero todos los tipos de mapas básicos están disponibles en ambas versiones de la API. De forma predeterminada, la v2 usa mosaicos de mapas de rutas estándar "pintados". Sin embargo, v3 requiere que se proporcione un tipo de mapa específico cuando se crea un objeto google.maps.Map.

Capas

Las capas son objetos del mapa que constan de una o más superposiciones. Se pueden manipular como una sola unidad y, por lo general, reflejan colecciones de objetos.

Servicios