Eso es todo.

Para comenzar a desarrollar, consulta nuestra documentación para desarrolladores.

Activar la Google Maps JavaScript API

Para que puedas comenzar, te proporcionaremos orientación en la Google Developers Console a fin de que hagas primero algunas acciones:

  1. Crear o seleccionar un proyecto
  2. Activar la Google Maps JavaScript API y servicios relacionados
  3. Crear claves correspondientes
Continuar

Actualizar tu aplicación de Google Maps JavaScript API de la v2 a la v3

La versión 2 de la Google Maps JavaScript API ya no está disponible. Esta guía está pensada para ayudar a los desarrolladores que ya usen la Google Maps JavaScript API v2 a migrar su código a la versión 3.

Muchísimos aspectos han cambiado entre la v2 y la v3 de la Google Maps JavaScript API. Al comienzar a trabajar con la API nueva, rápidamente descubres que no se trata simplemente de una actualización progresiva. La buena noticia es que hemos agregado muchas funciones nuevas y mejorado la usabilidad general de la API desde el punto de vista de los desarrolladores. Si planeas realizar una actualización de la Google Maps JavaScript API v2 a la Google Maps JavaScript API v3, esta guía te servirá en el proceso y en ella se mostrarán algunos de los cambios más comunes para usuarios de la API v2.

Información general

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

  1. Obtener una clave nueva: la Google Maps JavaScript API ahora usa la Google API Console para administrar claves. Antes de iniciar la migración, asegúrate de obtener tu clave de API nueva.
  2. Actualizar el código de arranque de tu API: la mayoría de las aplicaciones cargan la Google Maps JavaScript API v3 con el código que se muestra a continuación.
    <script type="text/javascript" src="//maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&sensor=true_OR_false"></script>
    
  3. Actualizar tu código: la cantidad de cambios necesarios dependerá muchísimo de tu aplicación. Dentro de los cambios comunes se incluye lo siguiente:
    • Consultar siempre el espacio de nombres google.maps: en la v3, todo el código de Google Maps JavaScript API se almacena en el espacio de nombres google.maps.* en lugar del espacio de nombres global. También se han cambiado los nombres de la mayoría de los objetos como parte de este proceso. Por ejemplo, en lugar de GMap2 ahora se carga google.maps.Map.
    • Quitar las referencias a los métodos obsoletos: se han quitado varios métodos de utilidades de propósitos generales, como GDownloadURL y GLog. Reemplaza esta funcionalidad con bibliotecas de utilidad para terceros o quita estas referencias de tu código.
    • (Opcional) Agregar bibliotecas a tu código: muchas funciones se han externalizado en bibliotecas de utilidades para que cada app solo deba cargar las partes de la API que se usarán.
    • (Opcional) Configurar tu proyecto para que use los elementos externalizados de la v3: se pueden usar los externalizados de la v3 para ayudar a validar tu código con el compilador de cierre o activar el autocompletado en tu IDE. Obtén más información sobre Compilación y elementos externalizados avanzados.
  4. Realizar pruebas e iteraciones: En este punto aún tienes algunas cosas por hacer, pero la buena noticia es que estás en camino a tu nueva aplicación de mapas v3.

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

Antes de planear tu migración, debes tomarte un tiempo para comprender las diferencias ente la Google Maps JavaScript API v2 y la Google Maps JavaScript API v3. La versión más nueva de la Google Maps JavaScript API se escribió desde cero, con un enfoque en técnicas modernas de programación de JavaScript, en el uso incrementado de bibliotecas y una API simplificada. Se han agregado muchas funciones nuevas a la API y se han cambiado, o incluso quitado, muchas funciones familiares. En esta sección, se destacan algunas de las diferencias claves 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 han desplazado hacia bibliotecas, lo cual ayuda a reducir los tiempos de carga y análisis de la Core API. Esto permite que tu app se cargue rápidamente en cualquier dispositivo.
  • Un mejor rendimiento de varias funciones, como la representación de polígonos y la disposición de marcadores.
  • Un enfoque nuevo de los límites de uso del cliente, para un mejor tratamiento de las direcciones compartidas usadas por proxies móviles y firewalls corporativos.
  • Incorporación de compatibilidad con varios navegadores modernos y los navegadores móviles. Eliminación de la compatibilidad con Internet Explorer 6.
  • Eliminación de muchas clases auxiliares de propósitos generales ( GLog o GDownloadUrl). En la actualidad, muchas bibliotecas excelentes de JavaScript proporcionan una funcionalidad similar, como Closure o jQuery.
  • Una implementación de Street View HTML5 que se carga en cualquier dispositivo móvil.
  • Panoramas de Street View personalizados con tus propias fotos, lo cual te permite compartir panoramas de pistas de esquí, casas en venta u otros lugares interesantes.
  • Personalizaciones de mapas con ajustes de estilo que te permiten cambiar la visualización de elementos en el mapa básico para adecuarlos a tu estilo visual único.
  • Asistencia para varios servicios nuevos, como ElevationService y la matriz de distancia.
  • Un servicio de indicaciones mejorado proporciona rutas alternativas, optimización de rutas (soluciones aproximadas para el problema del viajante), indicaciones para andar en bicicleta (con nivel de bicicleta), indicaciones de tránsito e indicaciones arrastrables.
  • Un formato de geocodificación actualizado que proporciona información de tipo más precisa en comparación con el valor accuracy de la Google Maps Geocoding API v2.
  • Asistencia para varias ventanas de información en un solo mapa.

Actualizar tu aplicación

Tu clave nueva

La Google Maps JavaScript API v3 usa un sistema con claves nuevas. Esto significa que tu clave v2 no funcionará con tu aplicación v3. Agregar una clave v3 antes de implementar tu aplicación para producción te permitirá:

La clave se pasa cuando se carga la Google Maps JavaScript API v3. Para generar una clave:

  1. Visita Google API Console e inicia sesión con tu cuenta de Google.
  2. Haz clic en el vínculo Services del menú de la izquierda y activa el servicio Google Maps JavaScript API v3.
  3. Una vez que se active el servicio, tu clave de API estará disponible desde la página Acceso a API, en la sección Acceso simple a API. Las aplicaciones de la Google Maps API usan aplicaciones con clave para navegador.

ID de cliente para licencias de Maps APIs for Work

Si tienes una licencia de Google Maps APIs for Work, debes usar un ID de cliente en lugar de una clave. Ten en cuenta que ambos elementos no pueden usarse juntos. Los ID de cliente son similares a las claves, pero existen las siguientes diferencias:

  • Las aplicaciones de Google Maps APIs que usan un ID de cliente tienen acceso a funciones o límites adicionales, como Maps Analytics.
  • Google Cloud Support genera tu ID de cliente y te lo proporciona en tu carta de bienvenida de Maps APIs for Work. No se recurre a la Google API Console para generar o buscar tu ID de cliente.
  • Cuando se carga la Google Maps JavaScript API, usas el parámetro client en lugar de clave. Por ejemplo:
    <script src="//maps.googleapis.com/maps/api/js?v=3&client=gme-yourclientid&sensor=true_or_false" type="text/javascript"></script>
  • Los ID de cliente siempre llevan el prefijo gme-.

Cargar la API

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

  1. Cargar la API desde //maps.googleapis.com/maps/api/js.
  2. Quitar el parámetro file.
  3. Asegurarte de incluir el parámetro sensor.
  4. Actualizar el parámetro key con tu clave v3 nueva. Los clientes de Google Maps APIs for Work deben usar un parámetro client.
  5. (solo Google Maps APIs Premium Plan) Asegúrate de que el parámetro client se suministre como se explica en la Guía del desarrollador del Google Maps APIs Premium Plan.
  6. Quita el parámetro v para solicitar la versión más reciente o cambiar su valor de manera correspondiente al esquema de versión v3.
  7. (Opcional) Reemplaza el parámetro hl por language y preserva su valor.
  8. (Opcional) Agregar un parámetro libraries para cargar las bibliotecas opcionales.

En el caso más simple, la carga inicial de programas v3 solo especifica tu clave de API y parámetro sensor.

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

En el siguiente ejemplo se solicita la última versión (experimental) de la Maps JavaScript API v2 en alemán:

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

El siguiente ejemplo es una solicitud equivalente para v3.

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

Versiones

No se exige la carga de una versión específica en v3. Si omites el parámetro de versión, obtendrás la versión experimental mas reciente de la API. Si lo prefieres, puedes especificar un número de versión, la última versión (experimental) o la versión más estable y sin actualizar.

En la tabla siguiente, se asigna el esquema de la v2 a la v3.

v2 v3 Caso de uso
2.s 3.0 Versiónsin actualizar. La versión más antigua disponible.
2 3 Versión de lanzamiento. La versión estable más reciente.
2.x 3.exp Versión experimental.

Importante: El SLA del Google Maps APIs Premium Plan no se aplica a la versión experimental. Para que se contemplen en el SLA, las aplicaciones del Google Maps APIs Premium Plan deben usar la versión actual de lanzamiento o sin actualización.

Presentación del espacio de nombres google.maps

Es posible que la introducción del espacio de nombres google.maps sea el cambio más notable en la Google Maps JavaScript API v3. La API v2 ubica todos los objetos en el espacio de nombres global de forma predeterminada, lo cual puede generar conflictos de nombres. En la v3, todos los objetos se ubican dentro del espacio de nombres google.maps.

Cuando migres tu aplicación a la v3, deberás cambiar tu código para asegurarte de usar el espacio de nombres nuevo. Desafortunadamente, no bastará con solo buscar “G” y aplicar el reemplazo por “google.maps.”, pero es una buena regla general que debe aplicarse cuando al revisar tu código. A continuación, se muestran algunos ejemplos de las clases equivalentes en v2 y 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
o google.maps.PolylineOptions

Quitar el código obsoleto

En la Google Maps JavaScript API v3 existen alternativas para la mayor parte de la funcionalidad de la v2; sin embargo, hay algunas clases que ya no son compatibles. Como parte de tu 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 Google Maps JavaScript API v3 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 escritas con las API v2 y 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 puedes ver, hay muchas 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 obligatorios en la v3 y se quitaron de la API.
  • El objeto GMap2 se reemplazó por google.maps.Map como objeto central de la API.
  • Ahora, las propiedades se cargan a través de las clases de Options. En el ejemplo anterior, se establecen las tres propiedades obligatorias para cargar un mapa (center, zoom y mapTypeId) a través de un objeto en línea MapOptions.
  • En la v3, se encuentra habilitado el valor predeterminado de la IU. Puedes inhabilitar esto fijando la propiedad disableDefaultUI en true en el objeto MapOptions.

Resumen

En este punto, tendrás cierto conocimiento de algunos de los puntos claves de tu migración de la Google Maps JavaScript API v2 a la Google Maps JavaScript API v3. Posiblemente debas obtener más información, pero esto dependerá de tu aplicación. En las siguientes secciones, hemos incluido instrucciones de migración para casos específicos que con los que puedes toparte. A su fez, existen 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 Send Feedback de 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 Google Maps JavaScript API. Cada sección de la referencia se designa para su lectura individual. No te recomendamos leer esta referencia por completo. En lugar de ello, usa el material como guía para tu 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.
  • Superposición: adición y edición de objetos del mapa.
  • Tipos de mapa : mosaicos que componen el mapa básico.
  • Capas: adición y edición de contenido en un grupo, como en el caso de las capas KML o Traffic.
  • Servicios: trabajo con la geocodificación, las indicaciones o los servicios de Street View de Google.

eventos;

El modelo de evento para la Google Maps JavaScript API v3 es similar al que se usa en la v2, aunque muchos aspectos no visibles han cambiado.

Controles

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

Superposiciones

Las superposiciones reflejan 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, en la v2 se usan mosaicos de mapa de ruta estándares “pintados”. Sin embargo, en la v3 se debe proporcionar un tipo de mapa específico cuando se crea un objeto google.maps.Map.

Capas

Lascapas son objetos del mapa que consisten en una o más superposiciones. Se pueden manipular como una única unidad y, por lo general, reflejan conjuntos de objetos.

Servicios

Enviar comentarios sobre...

Google Maps JavaScript API
Google Maps JavaScript API
Si necesitas ayuda, visita nuestra página de asistencia.