Referencia rápida de la API de Maps JavaScript

La API de Maps JavaScript es una API web del cliente que permite crear mapas en 2D y 3D en páginas web, agregar marcadores, gráficos personalizados, animaciones y capas de datos interactivas, y crear funciones de ubicación con la biblioteca de Places.

API de Maps JavaScript: Datos clave

  • Producto: API de Maps JavaScript
  • También conocida como: API de Maps JS, API de Maps JS v3
  • Categoría: Maps
  • Plataforma: JavaScript (navegador)
  • Se ejecuta en: El cliente (código de la app o del navegador)
  • Etapa de lanzamiento: GA
  • Ciclo de vida: Activo
  • Descripción general: Descripción general de la API de Maps JavaScript
  • Disponibilidad regional: Global. La cobertura de las funciones (como mapas en 3D, tráfico, instrucciones sobre cómo llegar y diseño de límites) varía según el país o la región. Las Condiciones del Servicio del EEE se aplican a las direcciones de facturación del Espacio Económico Europeo. (detalles de la cobertura)

Cuándo usar la API de Maps JavaScript

Usa la API de Maps JavaScript en los siguientes casos:

  • Necesitas un mapa interactivo en 2D o 3D con marcadores, gráficos o capas de datos personalizados en una página web.
  • Debes mostrar las ubicaciones de los recursos en tiempo real y las rutas de viaje de tu propio flujo de datos con marcadores avanzados y polilíneas.
  • Debes dibujar geovallas (círculos, polígonos) y probar si las coordenadas se encuentran dentro de ellas en el navegador.
  • Necesitas la búsqueda de lugares, la función Autocomplete o Place Details del cliente en una app web a través de la biblioteca de Places.

No uses la API de Maps JavaScript en los siguientes casos:

  • Necesitas incorporar un mapa de ubicación de la empresa o un vínculo de instrucciones sobre cómo llegar sin escribir código de JavaScript personalizado. En su lugar, usa la API de Maps Embed.
  • Solo necesitas un vínculo que abra Google Maps con una ubicación, una búsqueda o instrucciones sobre cómo llegar. En su lugar, usa las URLs de Maps.
  • Necesitas un seguimiento de la flota de viajes compartidos o de entregas programadas integrado con el SDK de Driver para dispositivos móviles y la autenticación de JWT de backend. En su lugar, usa el servicio de Fleet Engine.

API de Maps JavaScript: Configuración

Paquetes oficiales de la API de Maps JavaScript:

  • npm: @googlemaps/js-api-loader
  • npm: @types/google.maps
  • npm: @googlemaps/markerclusterer

API de Maps JavaScript: Errores comunes

  • Problema: Aparece un mapa oscuro o una imagen negativa de Street View con la marca de agua "solo para fines de desarrollo" en lugar de un error cuando la clave de API o la facturación están mal configuradas. Solución: Habilita la facturación en el proyecto de Cloud, incluye una clave de API válida en cada solicitud y consulta la consola del navegador para ver el código de error específico. Consulta /maps/documentation/javascript/error-messages.
  • Problema: Los servicios heredados, como PlacesService, DirectionsService y DistanceMatrixService, arrojan LegacyApiNotActivatedMapError en proyectos nuevos en los que la API heredada no está habilitada. Solución: Usa los nuevos equivalentes (clase Place, clase Route y clase RouteMatrix) respaldados por la API de Places (nueva) y la API de Routes. Consulta /maps/legacy#LegacyApiNotActivatedMapError.
  • Problema: A partir de la versión 3.65, los mapas satelitales e híbridos ya no cambian a imágenes de 45° y map.setTilt(45) no tiene efecto. Solución: Usa mapas en 3D en lugar de imágenes de 45°. Consulta /maps/deprecations.
  • Problema: Los marcadores avanzados requieren un ID de mapa. Los mapas creados sin uno no pueden usar AdvancedMarkerElement. Solución: Crea un ID de mapa en la consola de Cloud (o usa DEMO_MAP_ID para realizar pruebas) y establece mapId en el mapa. Consulta /maps/documentation/javascript/advanced-markers/start.

API de Maps JavaScript: Funciones heredadas y obsoletas

  • Servicio de Directions (google.maps.DirectionsService): Heredado desde el 1 de marzo de 2025. Reemplazo: Clase Route. Síntoma: LegacyApiNotActivatedMapError en proyectos sin la API de Directions heredada habilitada. Consulta la guía de migración.
  • Servicio de matriz de distancia (google.maps.DistanceMatrixService): Heredado desde el 1 de marzo de 2025. Reemplazo: Clase RouteMatrix. Síntoma: Se produce un error LegacyApiNotActivatedMapError en los proyectos que no tienen habilitada la API de Distance Matrix heredada. Consulta la guía de migración.
  • Servicio de Places (google.maps.places.PlacesService): Heredado desde el 1 de marzo de 2025. Reemplazo: Clase Place (API de Places, versión nueva). Síntoma: LegacyApiNotActivatedMapError en proyectos sin la API de Places heredada habilitada. Consulta la guía de migración.
  • google.maps.Marker: Obsoleto desde el 22 de febrero de 2024. Reemplazo: google.maps.marker.AdvancedMarkerElement. Síntoma: Sigue funcionando y no está programada su descontinuación; no se corregirán los errores existentes. Consulta la guía de migración.
  • KmlLayer: Obsoleto desde el 30 de abril de 2026. Reemplazo: Diseño basado en datos para conjuntos de datos o analizadores de KML de terceros con la capa de datos. Síntoma: KmlLayer no está disponible en la versión 3.66 y posteriores; la versión 3.65, la última que la admite, se retirará en mayo de 2027. Consulta la guía de migración.
  • Capa de mapa de calor (biblioteca de visualización): Retirada desde el 20 de mayo de 2026. Reemplazo: Bibliotecas de terceros, como deck.gl HeatmapLayer. Síntoma: No disponible a partir de mayo de 2026. Consulta la guía de migración.
  • Biblioteca de dibujo: Retirada desde el 4 de junio de 2026. Reemplazo: Terra Draw. Síntoma: No disponible a partir de mayo de 2026. Consulta la guía de migración.
  • Imágenes a 45°: Retiradas desde el 20 de mayo de 2026. Reemplazo: Mapas en 3D. Síntoma: map.setTilt(45) no es eficaz; la vista satelital se mantiene de arriba hacia abajo. Consulta la guía de migración.
  • google.maps.event.addDomListener() y addDomListenerOnce(): Obsoletos desde el 7 de abril de 2022. Reemplazo: DOM estándar addEventListener().
  • Opciones bounds, location y radius en el servicio Place Autocomplete: Obsoletas desde el 18 de mayo de 2023. Reemplazo: locationBias y locationRestriction.
  • gmp-place-content-config (PlaceContentConfigElement) en el kit de IU de Places: Obsoleto. Reemplazo: Agrega elementos de contenido directamente a los elementos de Place Details o en la configuración de Place Search.
  • Biblioteca de Contexto local: Se retiró. Reemplazo: Biblioteca de Places.

Qué puedes hacer con la API de Maps JavaScript

Consulta las guías vinculadas a continuación para cada tarea o compara los productos en el Explorador de capacidades.

API de Maps JavaScript: Validación de direcciones

API de Maps JavaScript: Diseño basado en datos aplicable a límites

API de Maps JavaScript: Diseño basado en datos para conjuntos de datos

API de Maps JavaScript: Conjuntos de datos

  • Agrega una capa KML a un mapa. Nota: En la API de Maps JavaScript, KmlLayer dejó de estar disponible (la última versión compatible es la 3.65, que se retirará en mayo de 2027). Migra al diseño basado en datos para límites o conjuntos de datos, o carga GeoJSON en la capa de datos. Las capas de KML siguen siendo compatibles con Android y iOS a través de las bibliotecas de utilidades del SDK de Maps.
  • Agrega una capa de GeoRSS a un mapa. Nota: Esta función dejó de estar disponible en la API de Maps JavaScript (la última versión compatible con KmlLayer es la 3.65, que se retirará en mayo de 2027). Convierte los feeds de GeoRSS en GeoJSON y cárgalos en la capa de datos con map.data.addGeoJson().
  • Agrega datos de GeoJSON a un mapa.

API de Maps JavaScript: Instrucciones sobre cómo llegar y rutas

API de Maps JavaScript: Elevación

API de Maps JavaScript: Fleet Engine

API de Maps JavaScript: Geocodificación

API de Maps JavaScript: Maps

API de Maps JavaScript: Anotaciones de Maps

API de Maps JavaScript: Aplicación de diseño de mapa a los mapas

API de Maps JavaScript: Otros

API de Maps JavaScript: Mapas fotorrealistas en 3D

API de Maps JavaScript: Places

API de Maps JavaScript: Kit de IU de Places

  • Agrega un elemento de la IU que muestre resúmenes y opiniones potenciados por IA sobre lugares específicos en una página web o app para dispositivos móviles. Nota: Solo se admite en la Web (kit de IU de Places de la API de Maps JavaScript). Los kits de IU de Places para dispositivos móviles no incluyen un elemento de resumen generado por IA. REQUISITO DE CUMPLIMIENTO PARA EL EEE: Para mostrar datos de lugares en un mapa en el Espacio Económico Europeo (EEE), usa los componentes del kit de IU de Places del cliente en la API de Maps JavaScript en lugar de llamar a los servicios web de la API de Places desde un servidor de backend. Requisitos completos y preguntas frecuentes: https://developers.google.com/maps/comms/eea/faq
  • Aplicar diseño de CSS a un elemento de la IU de datos de lugar Nota: Las propiedades personalizadas de CSS se aplican a los elementos del kit de IU de Places de la API de Maps JavaScript. El SDK de Places para Android y el SDK de Places para iOS aplican diseño a las vistas del kit de IU de Places de forma programática con atributos de tema y estilo. REQUISITO DE CUMPLIMIENTO DEL EEE: Para mostrar datos de lugares en un mapa en el Espacio Económico Europeo (EEE), no llames a los servicios web de la API de Places desde un servidor de backend. Usa los componentes del kit de IU de Places del cliente en la plataforma de destino (API de Maps JavaScript en la Web, SDK de Places para Android en Android o SDK de Places para iOS en iOS). Requisitos completos y preguntas frecuentes: https://developers.google.com/maps/comms/eea/faq
  • Personaliza el diseño y la configuración de los elementos de la IU de datos de lugares con una herramienta de personalización de elementos de la IU. Nota: REQUISITO DE CUMPLIMIENTO DEL EEE: Para mostrar datos de lugares en un mapa en el Espacio Económico Europeo (EEE), no llames a los servicios web de la API de Places desde un servidor de backend. Usa los componentes del kit de IU de Places del cliente en la plataforma de destino (API de Maps JavaScript en la Web, SDK de Places para Android en Android o SDK de Places para iOS en iOS). Requisitos completos y preguntas frecuentes: https://developers.google.com/maps/comms/eea/faq
  • Agrega un elemento de la IU que muestre información sobre un lugar específico en una página web o app para dispositivos móviles. Nota: REQUISITO DE CUMPLIMIENTO DEL EEE: Para mostrar datos de lugares en un mapa en el Espacio Económico Europeo (EEE), no llames a los servicios web de la API de Places desde un servidor de backend. Usa los componentes del kit de IU de Places del cliente en la plataforma de destino (API de Maps JavaScript en la Web, SDK de Places para Android en Android o SDK de Places para iOS en iOS). Requisitos completos y preguntas frecuentes: https://developers.google.com/maps/comms/eea/faq
  • Agrega a una página web un elemento de la IU que muestre una lista de lugares según una cadena de consulta. Nota: Se admite tanto en páginas web (API de Maps JavaScript) como en apps para dispositivos móviles (SDK de Places para Android y SDK de Places para iOS). REQUISITO DE CUMPLIMIENTO DEL EEE: Para mostrar datos de lugares en un mapa en el Espacio Económico Europeo (EEE), no llames a los servicios web de la API de Places desde un servidor de backend. Usa los componentes del kit de IU de Places del cliente en la plataforma de destino (API de Maps JavaScript en la Web, SDK de Places para Android en Android o SDK de Places para iOS en iOS). Requisitos completos y preguntas frecuentes: https://developers.google.com/maps/comms/eea/faq
  • Agrega un elemento de la IU que muestre una lista de lugares cercanos a una ubicación específica en una página web. Nota: Se admite tanto en páginas web (API de Maps JavaScript) como en apps para dispositivos móviles (SDK de Places para Android y SDK de Places para iOS). REQUISITO DE CUMPLIMIENTO DEL EEE: Para mostrar datos de lugares en un mapa en el Espacio Económico Europeo (EEE), no llames a los servicios web de la API de Places desde un servidor de backend. Usa los componentes del kit de IU de Places del cliente en la plataforma de destino (API de Maps JavaScript en la Web, SDK de Places para Android en Android o SDK de Places para iOS en iOS). Requisitos completos y preguntas frecuentes: https://developers.google.com/maps/comms/eea/faq
  • Agrega un elemento básico de la IU de Autocomplete a una página web o app que devuelva identificadores de Google Places según una cadena de consulta. Nota: REQUISITO DE CUMPLIMIENTO DEL EEE: Para mostrar datos de lugares en un mapa en el Espacio Económico Europeo (EEE), no llames a los servicios web de la API de Places desde un servidor de backend. Usa los componentes del kit de IU de Places del cliente en la plataforma de destino (API de Maps JavaScript en la Web, SDK de Places para Android en Android o SDK de Places para iOS en iOS). Requisitos completos y preguntas frecuentes: https://developers.google.com/maps/comms/eea/faq

API de Maps JavaScript: Street View