Riferimento rapido dell'API Maps JavaScript

L'API Maps JavaScript è un'API web lato client per la creazione di mappe 2D e 3D su pagine web, l'aggiunta di indicatori, grafiche personalizzate, animazioni e livelli di dati interattivi e la creazione di funzionalità di geolocalizzazione con la libreria Places.

API Maps JavaScript: informazioni chiave

  • Product: API Maps JavaScript
  • Nota anche come: API Maps JS, API Maps JS v3
  • Category: Maps
  • Piattaforma: JavaScript (browser)
  • Esecuzione su: client (codice dell'app o del browser)
  • Fase di lancio: GA
  • Ciclo di vita: Attivo
  • Panoramica: Panoramica dell'API Maps JavaScript
  • Disponibilità regionale: ovunque. La copertura delle funzionalità (come mappe 3D, traffico, indicazioni stradali e stile dei confini) varia in base al paese o alla regione; i Termini di servizio per il SEE si applicano agli indirizzi di fatturazione dello Spazio economico europeo. (dettagli sulla copertura)

API Maps JavaScript: quando utilizzarla

Utilizza l'API Maps JavaScript quando:

  • Hai bisogno di una mappa 2D o 3D interattiva con indicatori, grafiche o livelli di dati personalizzati su una pagina web.
  • Devi mostrare le posizioni degli asset in tempo reale e i percorsi di viaggio dal tuo stream di dati utilizzando gli indicatori avanzati e le polilinee.
  • Devi disegnare i geofence (cerchi, poligoni) e verificare se le coordinate rientrano al loro interno nel browser.
  • Hai bisogno di Place Search, Autocomplete o Place Details lato client in un'app web tramite la libreria Places.

  • Devi incorporare una mappa della sede dell'attività o un link alle indicazioni stradali senza scrivere codice JavaScript personalizzato. Utilizza invece l'API Maps Embed.
  • Ti serve solo un link che apra Google Maps con una posizione, una ricerca o delle indicazioni stradali. Utilizza invece gli URL di Maps.
  • Devi integrare il monitoraggio della flotta per il ridesharing o la consegna programmata con l'SDK Driver per dispositivi mobili e l'autenticazione JWT di backend. Utilizza invece il servizio Fleet Engine.

API Maps JavaScript: configurazione

Pacchetti ufficiali dell'API Maps JavaScript:

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

API Maps JavaScript: errori comuni

  • Problema: se la chiave API o la fatturazione non sono configurate correttamente, viene visualizzata una mappa oscurata o un'immagine di Street View negativa con la filigrana immagine "Solo per scopi di sviluppo" anziché un errore. Correzione: abilita la fatturazione nel progetto Cloud, includi una chiave API valida in ogni richiesta e controlla la console del browser per il codice di errore specifico. Consulta /maps/documentation/javascript/error-messages.
  • Problema: i servizi legacy come PlacesService, DirectionsService e DistanceMatrixService generano LegacyApiNotActivatedMapError nei nuovi progetti in cui l'API legacy non è abilitata. Correzione: utilizza i nuovi equivalenti (classe Place, classe Route, classe RouteMatrix) supportati dall'API Places (novità) e dall'API Routes. Consulta /maps/legacy#LegacyApiNotActivatedMapError.
  • Problema: a partire dalla versione 3.65, le mappe satellitari e ibride non passano più alle immagini a 45° e map.setTilt(45) non ha alcun effetto. Correzione: utilizza mappe 3D anziché immagini a 45°. Consulta la pagina /maps/deprecations.
  • Problema: gli indicatori avanzati richiedono un ID mappa; le mappe create senza un ID mappa non possono utilizzare AdvancedMarkerElement. Correzione: crea un ID mappa nella console Cloud (o utilizza DEMO_MAP_ID per i test) e imposta mapId sulla mappa. Consulta /maps/documentation/javascript/advanced-markers/start.

API Maps JavaScript: funzionalità legacy e deprecate

  • Directions Service (google.maps.DirectionsService): legacy dal 1° marzo 2025. Sostituzione: classe Route. Sintomo: LegacyApiNotActivatedMapError nei progetti in cui l'API Directions precedente non è abilitata. Consulta la guida alla migrazione.
  • Servizio Distance Matrix (google.maps.DistanceMatrixService): legacy dal 1° marzo 2025. Sostituzione: classe RouteMatrix. Sintomo: LegacyApiNotActivatedMapError nei progetti in cui non è abilitata l'API Distance Matrix legacy. Consulta la guida alla migrazione.
  • Servizio Places (google.maps.places.PlacesService): Legacy dal 01-03-2025. Sostituzione: classe Place (API Places (nuova)). Sintomo: LegacyApiNotActivatedMapError su progetti senza l'API Places precedente abilitata. Consulta la guida alla migrazione.
  • google.maps.Marker: deprecato dal 22/02/2024. Sostituzione: google.maps.marker.AdvancedMarkerElement. Sintomo: funziona ancora e non è prevista la dismissione; i bug esistenti non verranno corretti. Consulta la guida alla migrazione.
  • KmlLayer: deprecato dal 30/04/2026. Sostituzione: stile basato sui dati per i set di dati o parser KML di terze parti con il livello dati. Sintomo: KmlLayer non è disponibile nella versione 3.66 e successive; la versione 3.65, l'ultima versione che lo supporta, verrà ritirata a maggio 2027. Consulta la guida alla migrazione.
  • Livello mappa termica (libreria Visualization): ritirato dal 20/05/2026. Sostituzione: librerie di terze parti come deck.gl HeatmapLayer. Sintomo: non disponibile a partire da maggio 2026. Consulta la guida alla migrazione.
  • Libreria di disegno: ritirata dal 4 giugno 2026. Sostituzione: Terra Draw. Sintomo: non disponibile a partire da maggio 2026. Consulta la guida alla migrazione.
  • Immagini a 45°: ritirate dal 20/05/2026. Sostituzione: mappe 3D. Sintomo: map.setTilt(45) non è efficace; la vista satellitare rimane dall'alto verso il basso. Consulta la guida alla migrazione.
  • google.maps.event.addDomListener() e addDomListenerOnce(): ritirati dal 7 aprile 2022. Sostituzione: DOM standard addEventListener().
  • Opzioni bounds, location e radius nel servizio Place Autocomplete: ritirate dal 18 maggio 2023. Sostituzione: locationBias e locationRestriction.
  • gmp-place-content-config (PlaceContentConfigElement) in Places UI Kit: Deprecato. Sostituzione: aggiungi elementi dei contenuti direttamente agli elementi di Place Details o nella configurazione di Place Search.
  • Local Context Library: ritirata. Sostituzione: libreria Places.

Cosa puoi fare con l'API Maps JavaScript

Consulta le guide collegate di seguito per ogni attività o confronta i prodotti in Capabilities Explorer.

API Maps JavaScript: Address Validation

API Maps JavaScript: stili basati sui dati per i confini

API Maps JavaScript: stile basato sui dati per i set di dati

API Maps JavaScript: set di dati

  • Aggiungi un livello KML a una mappa. Nota: nell'API Maps JavaScript, KmlLayer è stato ritirato (ultima versione supportata v3.65, dismissione a maggio 2027). Esegui la migrazione allo stile basato sui dati per i confini o i set di dati oppure carica GeoJSON sul livello dati. I livelli KML continuano a essere supportati su Android e iOS tramite le librerie di utilità di Maps SDK.
  • Aggiungi un livello GeoRSS a una mappa. Nota: ritirato nell'API Maps JavaScript (KmlLayer è supportato per l'ultima volta nella versione 3.65, ritirato a maggio 2027); converti i feed GeoRSS in GeoJSON e caricali sul livello dati con map.data.addGeoJson().
  • Aggiungi dati GeoJSON a una mappa.

API Maps JavaScript: indicazioni stradali e routing

API Maps JavaScript: Elevation

API Maps JavaScript: Fleet Engine

API Maps JavaScript: geocodifica

API Maps JavaScript: Maps

API Maps JavaScript: annotazioni delle mappe

API Maps JavaScript: stile di mappa

API Maps JavaScript: altro

API Maps JavaScript: mappe 3D fotorealistiche

API Maps JavaScript: Places

API Maps JavaScript: Places UI Kit

  • Aggiungi un elemento UI che mostra riassunti e recensioni basati sull'AI relativi a luoghi specifici in una pagina web o un'app mobile. Nota: supportato solo sul web (Places UI Kit dell'API Maps JavaScript); i Places UI Kit per dispositivi mobili non includono un elemento di riassunto dell'AI. REQUISITO DI CONFORMITÀ SEE: per mostrare i dati dei luoghi su una mappa nello Spazio economico europeo (SEE), utilizza i componenti di Places UI Kit lato client nell'API Maps JavaScript anziché chiamare i servizi web dell'API Places da un server di backend. Requisiti completi e domande frequenti: https://developers.google.com/maps/comms/eea/faq
  • Applica lo stile CSS a un elemento UI dei dati dei luoghi. Nota: le proprietà personalizzate CSS si applicano agli elementi di Places UI Kit dell'API Maps JavaScript; Places SDK for Android e Places SDK for iOS applicano lo stile alle visualizzazioni di Place UI Kit in modo programmatico utilizzando gli attributi di tema e stile. REQUISITO DI CONFORMITÀ SEE: per mostrare i dati dei luoghi su una mappa nello Spazio economico europeo (SEE), non chiamare i servizi web dell'API Places da un server di backend. Utilizza i componenti di Places UI Kit lato client sulla piattaforma di destinazione (API Maps JavaScript sul web, Places SDK for Android su Android o Places SDK for iOS su iOS). Requisiti completi e domande frequenti: https://developers.google.com/maps/comms/eea/faq
  • Personalizza lo stile e le configurazioni degli elementi UI dei dati dei luoghi con uno strumento di personalizzazione degli elementi UI. Nota: REQUISITO DI CONFORMITÀ SEE: per mostrare i dati dei luoghi su una mappa nello Spazio economico europeo (SEE), non chiamare i servizi web dell'API Places da un server di backend. Utilizza i componenti di Places UI Kit lato client sulla piattaforma di destinazione (API Maps JavaScript sul web, Places SDK for Android su Android o Places SDK for iOS su iOS). Requisiti completi e domande frequenti: https://developers.google.com/maps/comms/eea/faq
  • Aggiungi un elemento UI che mostra informazioni su un luogo specifico in una pagina web o in un'app mobile. Nota: REQUISITO DI CONFORMITÀ SEE: per mostrare i dati dei luoghi su una mappa nello Spazio economico europeo (SEE), non chiamare i servizi web dell'API Places da un server di backend. Utilizza i componenti di Places UI Kit lato client sulla piattaforma di destinazione (API Maps JavaScript sul web, Places SDK for Android su Android o Places SDK for iOS su iOS). Requisiti completi e domande frequenti: https://developers.google.com/maps/comms/eea/faq
  • Aggiungi a una pagina web un elemento UI che mostra un elenco di luoghi in base a una stringa di query. Nota: supportato sia sulle pagine web (API Maps JavaScript) sia sulle app mobile (Places SDK for Android e Places SDK for iOS). REQUISITO DI CONFORMITÀ SEE: per mostrare i dati dei luoghi su una mappa nello Spazio economico europeo (SEE), non chiamare i servizi web dell'API Places da un server di backend. Utilizza i componenti di Places UI Kit lato client sulla piattaforma di destinazione (API Maps JavaScript sul web, Places SDK for Android su Android o Places SDK for iOS su iOS). Requisiti completi e domande frequenti: https://developers.google.com/maps/comms/eea/faq
  • Aggiungi a una pagina web un elemento UI che mostra un elenco di luoghi vicini a una località specifica. Nota: supportato sia sulle pagine web (API Maps JavaScript) sia sulle app mobile (Places SDK for Android e Places SDK for iOS). REQUISITO DI CONFORMITÀ SEE: per mostrare i dati dei luoghi su una mappa nello Spazio economico europeo (SEE), non chiamare i servizi web dell'API Places da un server di backend. Utilizza i componenti di Places UI Kit lato client sulla piattaforma di destinazione (API Maps JavaScript sul web, Places SDK for Android su Android o Places SDK for iOS su iOS). Requisiti completi e domande frequenti: https://developers.google.com/maps/comms/eea/faq
  • Aggiungi un elemento UI di completamento automatico di base a una pagina web o a un'app che restituisce gli identificatori di Google Places in base a una stringa di query. Nota: REQUISITO DI CONFORMITÀ SEE: per mostrare i dati dei luoghi su una mappa nello Spazio economico europeo (SEE), non chiamare i servizi web dell'API Places da un server di backend. Utilizza i componenti di Places UI Kit lato client sulla piattaforma di destinazione (API Maps JavaScript sul web, Places SDK for Android su Android o Places SDK for iOS su iOS). Requisiti completi e domande frequenti: https://developers.google.com/maps/comms/eea/faq

API Maps JavaScript: Street View