Quando si parla di Google Maps API è facile immaginare un singolo servizio che permette di inserire una mappa in un sito. In realtà Google Maps Platform comprende diverse API e SDK, ognuno progettato per un compito specifico: visualizzare mappe interattive, cercare luoghi, convertire indirizzi in coordinate, calcolare percorsi, mostrare Street View o lavorare direttamente con i tile cartografici.

La prima decisione, quindi, non è come ottenere una chiave API. È capire quale servizio ti serve davvero.

Per una semplice mappa incorporata potrebbe bastare Maps Embed API, mentre una web app con marker dinamici richiede Maps JavaScript API. Se devi suggerire indirizzi entra in gioco Places; se devi trasformare un indirizzo in latitudine e longitudine serve Geocoding; per itinerari e matrici il riferimento attuale è Routes API.

In questa guida vedremo come scegliere la Google Maps API corretta, ottenere e proteggere la chiave, creare una prima mappa funzionante, capire i costi reali e riconoscere tutorial che utilizzano servizi ormai Legacy. Vedremo anche cosa cambia per i progetti collegati a un account di fatturazione nello Spazio economico europeo e quando può avere più senso valutare Mapbox, HERE, TomTom, MapTiler oppure uno stack OpenStreetMap.

Indice dei contenuti visualizza

Google Maps API: cos’è davvero e quando serve

Google Maps Platform è un ecosistema di servizi cartografici accessibili tramite API, SDK e componenti dedicati. Il principio di base è lo stesso di qualunque API: un’applicazione può chiedere dati o funzionalità a un servizio esterno attraverso un’interfaccia definita, senza dover costruire da zero l’intera infrastruttura sottostante.

Nel caso di Google Maps, ciò può significare richieste molto diverse tra loro. Puoi voler visualizzare una mappa, cercare una farmacia vicina, ottenere le coordinate di un indirizzo, calcolare un itinerario oppure conoscere i dettagli di un luogo.

La documentazione di Google Maps Platform divide l’offerta in grandi aree come Maps, Routes e Places, alle quali si aggiungono altri servizi specialistici.

Google Maps Platform non è una sola API

La formula “Google Maps API” continua a essere molto usata nelle ricerche, ma tecnicamente è generica.

Un progetto può utilizzare, per esempio:

Maps JavaScript API per creare una mappa web interattiva;
Maps Embed API per incorporare una mappa tramite iframe;
Maps Static API per ottenere un’immagine statica;
Places API per ricerca, autocomplete e dati sui luoghi;
Geocoding API per convertire indirizzi e coordinate;
Routes API per percorsi e matrici;
Street View Static API per immagini Street View;
Map Tiles API quando serve lavorare a un livello cartografico più basso.

Questo dettaglio è importante anche sul piano economico: servizi differenti producono SKU e modalità di fatturazione differenti. Dire genericamente “Google Maps API costa X” può quindi essere fuorviante.

Google Maps API o semplice mappa incorporata: quando basta Maps Embed

Se devi mostrare nella pagina dei contatti la sede di un’azienda, un luogo o un percorso senza costruire un’interfaccia cartografica personalizzata, potresti non avere bisogno di Maps JavaScript API.

Maps Embed API permette di inserire una mappa interattiva tramite iframe, senza scrivere logica JavaScript specifica. Richiede una API key, ma Google indica attualmente lo SKU Embed con utilizzo gratuito illimitato.

La guida ufficiale di Maps Embed API mostra le modalità supportate per mappe, luoghi, indicazioni e Street View.

Per una normale pagina “Dove siamo”, partire direttamente con una soluzione programmabile più complessa può significare aggiungere codice, configurazione e superficie di errore senza ottenere un beneficio reale.

Quando invece serve un’API programmabile

Maps JavaScript API e gli altri servizi diventano interessanti quando la mappa è parte del funzionamento dell’applicazione, non un semplice elemento incorporato.

Alcuni casi tipici sono:

uno store locator che aggiorna i punti vendita mostrati;
immobili visualizzati su una mappa in base ai filtri;
un’applicazione di consegna che calcola percorsi;
un form che suggerisce indirizzi mentre l’utente scrive;
una ricerca di attività o punti di interesse;
una dashboard che rappresenta dati geografici;
un configuratore che modifica marker, poligoni o layer in tempo reale.

La differenza pratica è semplice: con un embed usi una mappa preparata dal servizio; con un’API programmabile la mappa e i dati geografici diventano componenti controllati dalla logica dell’applicazione.

Quale Google Maps API scegliere

Scegliere la Google Maps API sbagliata crea spesso più problemi della configurazione della chiave.

Conviene partire dal risultato che vuoi ottenere:

Esigenza	Servizio da valutare	Dove lavora principalmente	Caso tipico
Mappa interattiva personalizzata	Maps JavaScript API	Browser	Store locator, portali, dashboard
Mappa semplice incorporata	Maps Embed API	Browser / iframe	Pagina contatti
Immagine di una mappa	Maps Static API	HTTP	Email, anteprime, documenti
Ricerca e dettagli di luoghi	Places API / Places UI Kit	Client o server secondo il prodotto	Autocomplete, POI, attività
Indirizzo → coordinate	Geocoding API	Server o client secondo integrazione	Geocoding di indirizzi
Coordinate → indirizzo	Geocoding API	Server o client secondo integrazione	Reverse geocoding
Percorso tra punti	Routes API	Web service / client supportato	Navigazione, consegne
Matrice tempi e distanze	Routes API	Web service	Logistica, confronto destinazioni
Tile cartografici	Map Tiles API	Client specializzato	Rendering cartografico avanzato

Mappa decisionale con cinque percorsi che collegano le esigenze del progetto a Maps Embed, Maps JavaScript, Places, Geocoding e Routes — Ogni esigenza porta a un servizio diverso: Embed, Maps JavaScript, Places, Geocoding o Routes.

Maps JavaScript API per mappe web interattive

La Maps JavaScript API è normalmente la scelta corretta quando la mappa deve reagire all’applicazione.

Puoi:

controllare centro e livello di zoom;
aggiungere marker;
disegnare geometrie;
reagire a click ed eventi;
modificare lo stile;
collegare la mappa a dati caricati dinamicamente;
integrare librerie aggiuntive.

È quindi strettamente legata al funzionamento di JavaScript nel browser.

Non significa però che tutto debba essere eseguito lato client. Un’applicazione reale può visualizzare la mappa nel browser e affidare al backend le operazioni che richiedono credenziali segrete, logica proprietaria o un controllo più rigoroso sulle richieste.

Places API e Places UI Kit per ricerca, autocomplete e dettagli dei luoghi

Places serve quando il problema non è semplicemente “disegnare una mappa”, ma lavorare con luoghi reali.

Può essere utilizzata per:

completare automaticamente un indirizzo o il nome di un luogo;
cercare attività nelle vicinanze;
recuperare informazioni su un luogo;
lavorare con Place ID;
effettuare ricerche testuali o geografiche.

Google documenta Places come un sistema pensato per lavorare con luoghi e punti di interesse attraverso servizi dedicati.

La documentazione ufficiale di Places API è il riferimento da utilizzare per endpoint, campi e modalità di richiesta.

Per i progetti collegati a un account di fatturazione dello Spazio economico europeo è però necessario leggere anche le regole specifiche che vedremo più avanti: visualizzare contenuti Places sopra una mappa non è più un dettaglio da dare per scontato.

Geocoding API per trasformare indirizzi e coordinate

Il geocoding risponde a una domanda diversa:

“Quali coordinate corrispondono a questo indirizzo?”

La Geocoding API può trasformare un indirizzo in latitudine e longitudine. Nel percorso inverso, il reverse geocoding parte invece dalle coordinate e prova a ottenere un indirizzo o una descrizione geografica corrispondente.

La documentazione Geocoding API copre entrambi i casi.

È importante non confonderla con Places. Se devi cercare “ristoranti vicino a me” o trovare un’attività tramite nome e categoria, stai entrando nel dominio Places, non nel semplice geocoding di un indirizzo.

Routes API per percorsi, tempi e matrici

Per i nuovi progetti che devono calcolare itinerari, il riferimento è Routes API.

Il metodo Compute Routes può calcolare un percorso tra origine e destinazione tenendo conto, secondo la configurazione, di modalità di viaggio, traffico e altre opzioni. Compute Route Matrix serve invece quando devi valutare più origini e destinazioni.

La documentazione di Routes API descrive entrambi gli scenari.

La distinzione conta perché molti tutorial ancora online utilizzano Directions API o Distance Matrix API come se fossero la prima scelta per una nuova implementazione. Entrambe sono oggi classificate da Google come Legacy.

Static Maps, Street View, Map Tiles e Geolocation per esigenze specifiche

Non tutto richiede una mappa dinamica.

Maps Static API genera un’immagine cartografica che può essere utile in contesti dove non serve interazione. Street View Static API lavora sulle immagini Street View, mentre Map Tiles API espone tile per integrazioni cartografiche più avanzate.

Geolocation API, infine, non deve essere confusa con la Geolocation API del browser. Il servizio Google può stimare una posizione utilizzando informazioni come celle telefoniche e access point Wi-Fi disponibili nella richiesta.

La scelta corretta dipende quindi dal dato o dalla funzione che ti manca, non dal fatto che il progetto contenga genericamente “una mappa”.

Come ottenere una Google Maps API key

Per la maggior parte delle integrazioni con Google Maps API devi lavorare all’interno di un progetto Google Cloud.

Il flusso normale è:

creare o selezionare un progetto;
configurare la fatturazione quando richiesta;
abilitare esclusivamente le API necessarie;
creare la API key;
applicare restrizioni coerenti con l’ambiente in cui verrà usata;
verificare quote e monitoraggio.

La documentazione ufficiale per ottenere una chiave di Maps JavaScript API distingue inoltre tra chiave standard e Maps Demo Key per alcuni scenari di prototipazione.

Creare o scegliere il progetto Google Cloud

Una chiave appartiene a un progetto Google Cloud.

Questo permette di collegare nello stesso contenitore:

API abilitate;
credenziali;
fatturazione;
quote;
metriche di utilizzo;
autorizzazioni degli utenti che gestiscono il progetto.

Conviene evitare un unico progetto indistinto che raccoglie integrazioni completamente diverse solo perché appartengono alla stessa azienda. Separare progetti e credenziali può semplificare sicurezza, monitoraggio e gestione futura.

Per i clienti SEE questa separazione può assumere anche un peso ulteriore, perché Google tratta un’integrazione come uno specifico scopo o workflow dell’applicazione e raccomanda, come best practice, un progetto per integrazione.

Abilitare soltanto le API necessarie

Creare una chiave non abilita automaticamente ogni servizio.

Se il tuo sito utilizza Maps JavaScript API, devi abilitare quella API nel progetto. Se successivamente effettui richieste a Places, Routes o altri prodotti, devono essere configurati i servizi pertinenti.

Questo è anche uno dei motivi per cui una mappa può smettere di funzionare nonostante la chiave sembri corretta: la credenziale esiste, ma non è autorizzata a utilizzare l’API richiesta.

Creare la chiave API

Una volta configurato il progetto puoi creare la chiave dalla sezione delle credenziali di Google Cloud.

La parte importante viene subito dopo: non lasciare una chiave nuova senza restrizioni.

Una chiave tecnicamente valida ma utilizzabile da qualunque origine amplia inutilmente il rischio di abuso e di traffico fatturabile non desiderato.

Limitare la chiave per sito, app o indirizzo IP e per API

Google distingue due livelli di restrizione.

Application restrictions stabiliscono da dove può arrivare una richiesta. Per esempio:

HTTP referrer per un sito web;
indirizzi IP per sistemi server-side;
app Android;
app iOS.

API restrictions stabiliscono invece quali API quella chiave può chiamare.

Per una chiave utilizzata da un sito con Maps JavaScript API, quindi, una configurazione sensata può permettere richieste soltanto dai domini autorizzati e soltanto verso le API effettivamente necessarie.

Google raccomanda espressamente di limitare le chiavi, utilizzare chiavi separate per applicazioni differenti e rimuovere quelle inutilizzate nella guida alle best practice per la sicurezza delle API.

Maps Demo Key: quando puoi provare senza configurare la fatturazione

Per alcuni casi di Maps JavaScript API Google offre una Maps Demo Key pensata per prototipare.

Il vantaggio è poter sperimentare alcune funzionalità senza inserire immediatamente informazioni di fatturazione. Il limite fondamentale è altrettanto chiaro: non è una chiave per un ambiente di produzione.

È utile per capire l’API, testare un proof of concept o verificare un’idea prima di configurare il progetto definitivo.

Come usare Google Maps API: un esempio attuale con Maps JavaScript API

Vediamo una configurazione minima di Google Maps API con Maps JavaScript API per capire i componenti in gioco.

L’obiettivo non è costruire uno store locator completo, ma mostrare:

caricamento della Maps JavaScript API;
creazione della mappa;
impostazione di centro e zoom;
caricamento della libreria marker;
inserimento di un marker avanzato.

Google supporta più modalità di caricamento della Maps JavaScript API, comprese dynamic library import, caricamento diretto dello script e il loader NPM.

Caricare le librerie con `importLibrary()`

Nel codice JavaScript possiamo richiedere soltanto le librerie che ci servono:

const { Map } = await google.maps.importLibrary("maps");
const { AdvancedMarkerElement } =
  await google.maps.importLibrary("marker");

importLibrary() consente di caricare funzionalità specifiche in modo più controllato rispetto all’idea di trattare l’intera piattaforma come un unico blocco.

La documentazione sulle librerie Maps JavaScript API mostra le modalità disponibili.

Creare la mappa e impostare centro e zoom

Un esempio completo può essere questo:

<div id="map" style="height: 420px;"></div>

<script>
  async function initMap() {
    const { Map } = await google.maps.importLibrary("maps");
    const { AdvancedMarkerElement } =
      await google.maps.importLibrary("marker");

    const centro = {
      lat: 41.9028,
      lng: 12.4964
    };

    const map = new Map(
      document.getElementById("map"),
      {
        center: centro,
        zoom: 14,
        mapId: "DEMO_MAP_ID"
      }
    );

    new AdvancedMarkerElement({
      map,
      position: centro,
      title: "Roma"
    });
  }
</script>

<script
  async
  src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&loading=async&callback=initMap">
</script>

Sostituisci YOUR_API_KEY con una chiave configurata per il progetto. Nell’esempio viene utilizzato DEMO_MAP_ID per il test; in un progetto reale conviene configurare il Map ID appropriato.

Gli Advanced Markers richiedono la relativa libreria e un Map ID. Google documenta entrambi i requisiti nella guida dedicata agli Advanced Markers.

Aggiungere un marker

La parte:

new AdvancedMarkerElement({
  map,
  position: centro,
  title: "Roma"
});

associa il marker alla mappa e alle coordinate scelte.

Da qui puoi iniziare ad aggiungere dati provenienti da un database, da una tua API o da altri servizi. Quando i dati arrivano via HTTP, spesso vengono scambiati come JSON, ma il formato della risposta dipende naturalmente dall’API utilizzata.

Cosa cambia tra codice client-side e chiamate server-side

Qui entra in gioco una distinzione di sicurezza fondamentale.

Con Maps JavaScript API il browser deve poter caricare la risorsa e quindi la chiave utilizzata dal client non può essere trattata come un segreto che nessuno vedrà mai. La protezione dipende soprattutto da referrer e restrizioni API.

Una chiave utilizzata invece da un web service sul server non dovrebbe essere pubblicata nel JavaScript, nel repository pubblico o nell’HTML. Va mantenuta nell’ambiente server e limitata, quando appropriato, agli indirizzi IP autorizzati.

La strategia corretta non è quindi “nascondere a tutti i costi ogni chiave”, ma utilizzare credenziali differenti in base al contesto e applicare la restrizione adatta.

Google Maps API è gratis? Costi e modello di fatturazione

La risposta breve è: dipende dal servizio e dal volume.

Google Maps API utilizza un modello di fatturazione basato su SKU differenti all’interno di Google Maps Platform. Molti servizi prevedono una quantità mensile gratuita, dopo la quale viene applicato il prezzo previsto per lo scaglione di utilizzo.

Un’informazione particolarmente importante per chi legge guide meno recenti è che il vecchio credito ricorrente mensile da 200 dollari non è più il modello standard. Google lo ha sostituito con soglie gratuite specifiche per SKU.

La FAQ ufficiale sul pricing va quindi preferita ai tutorial che continuano a calcolare tutto partendo dal vecchio credito.

Free usage cap: cosa è cambiato rispetto al vecchio credito mensile

Le soglie gratuite non sono uguali per tutti i prodotti.

Nel listino globale, per esempio:

Dynamic Maps: 10.000 eventi gratuiti al mese;
Maps Embed: utilizzo gratuito illimitato;
Static Maps: 10.000;
Compute Routes Essentials: 10.000;
Geocoding: 10.000;
Places Autocomplete Requests: 10.000;
alcune SKU Places Pro: 5.000.

Questo significa che non ha senso chiedersi soltanto “quante mappe posso visualizzare gratis?”. Bisogna prima identificare quali SKU genera l’applicazione.

Quanto costano Dynamic Maps, Static Maps, Geocoding, Routes e Places

La tabella seguente riporta alcuni esempi del listino globale Google in USD. I prezzi sono per 1.000 eventi e la colonna economica mostra il primo scaglione a pagamento dopo il free usage cap; per volumi maggiori Google applica scaglioni differenti.

SKU	Free usage cap mensile	Primo prezzo oltre la soglia	Unità
Dynamic Maps	10.000	$7,00	1.000 eventi
Static Maps	10.000	$2,00	1.000 eventi
Routes: Compute Routes Essentials	10.000	$5,00	1.000 eventi
Routes: Compute Route Matrix Essentials	10.000	$5,00	1.000 eventi
Geocoding	10.000	$5,00	1.000 eventi
Places Autocomplete Requests	10.000	$2,83	1.000 eventi
Places Place Details Essentials	10.000	$5,00	1.000 eventi
Places Nearby Search Pro	5.000	$32,00	1.000 eventi
Places Text Search Pro	5.000	$32,00	1.000 eventi

Il listino ufficiale Google Maps Platform specifica gli scaglioni e i prezzi aggiornati.

Per questo la tabella non va letta come una classifica “più economico/più costoso”: una chiamata a Dynamic Maps e una ricerca Places Pro non svolgono lo stesso lavoro e non rappresentano unità funzionalmente comparabili.

Starter, Essentials e Pro: come funzionano gli abbonamenti

Al modello pay-as-you-go si affiancano anche piani di abbonamento disponibili ai clienti self-service idonei.

Piano	Chiamate combinate incluse al mese	Prezzo mensile
Starter	50.000	$100
Essentials	100.000	$275
Pro	250.000	$1.200

Non significa che qualsiasi chiamata Maps valga automaticamente allo stesso modo o che ogni SKU sia indistintamente utilizzabile. Ogni piano ha una lista di SKU inclusi e restano applicabili termini e condizioni del programma.

Gli SKU gratuiti, come quelli indicati da Google per determinati servizi, non consumano il limite mensile dell’abbonamento.

La pagina degli abbonamenti Google Maps Platform è quindi la fonte da verificare prima di scegliere un piano sulla base del solo numero di chiamate.

Quote, budget e alert: come evitare sorprese

Un’applicazione in produzione non dovrebbe affidarsi soltanto alla speranza che il traffico rimanga basso.

Conviene impostare:

quote coerenti con il traffico previsto;
monitoraggio per API e SKU;
alert di budget;
controllo periodico dei report di fatturazione;
restrizioni sulle credenziali;
rate limiting applicativo quando utile.

Un dettaglio spesso frainteso è che un budget alert non blocca automaticamente la spesa. L’alert avvisa quando una soglia viene raggiunta; se vuoi controllare materialmente il numero di richieste devi lavorare anche sulle quote e sull’architettura dell’applicazione.

La documentazione Google sul monitoraggio spiega come controllare utilizzo e metriche.

Come proteggere la chiave API di Google Maps

Una chiave Google Maps API non va configurata allo stesso modo in ogni scenario.

Il criterio da usare è:

dove viene eseguita la richiesta → chi può vedere la credenziale → quale restrizione può impedire un uso improprio.

Perché una chiave visibile nel JavaScript non va trattata come una password

Una chiave usata dal browser per Maps JavaScript API viene inviata al client e può essere osservata negli strumenti di sviluppo.

Tentare di renderla “segreta” attraverso offuscamento del JavaScript non risolve il problema.

La protezione corretta consiste nel:

consentire soltanto i referrer autorizzati;
permettere soltanto le API realmente necessarie;
monitorare l’utilizzo;
utilizzare una chiave distinta da quelle server-side.

È una differenza sostanziale rispetto a password, token privati e chiavi destinate esclusivamente al backend.

Restrizioni HTTP referrer per i siti web

Per una mappa caricata da un sito, la restrizione HTTP referrer consente di stabilire quali origini web possono usare la chiave.

In questo modo una persona che copia la chiave dal codice non dovrebbe poterla riutilizzare liberamente da un proprio dominio.

La configurazione deve comunque essere testata attentamente: pattern errati, sottodomini esclusi o differenze tra ambiente di sviluppo e produzione possono produrre il classico RefererNotAllowedMapError.

Restrizioni IP per i servizi server-side

Quando una chiave viene usata esclusivamente da server con indirizzi IP prevedibili, la restrizione IP è normalmente più appropriata.

La credenziale dovrebbe inoltre essere conservata:

in variabili d’ambiente;
in un secret manager;
in configurazioni escluse dal repository pubblico.

Non c’è alcun vantaggio nel far transitare nel browser una chiave che serve esclusivamente a una chiamata backend.

Perché conviene separare chiavi client e server

Usare una stessa chiave per JavaScript nel browser e web service lato server rende più difficile applicare restrizioni sensate.

Google raccomanda di separare il traffico client e server, arrivando a suggerire progetti distinti quando questo migliora la protezione delle credenziali.

La separazione aiuta anche durante la diagnosi: se aumenta improvvisamente il traffico di una chiave, sai già quale componente dell’applicazione controllare.

Quote, monitoraggio e chiavi inutilizzate

Le credenziali vecchie sono un rischio inutile.

Una buona manutenzione comprende:

identificare chiavi senza traffico;
verificare quali API possono chiamare;
eliminare quelle non più necessarie;
ruotare le credenziali quando opportuno;
controllare anomalie di traffico;
rivedere le quote dopo cambiamenti importanti dell’applicazione.

La sicurezza della API key non è quindi una configurazione da eseguire una volta e dimenticare.

Google Maps API in Italia: cosa cambia nello Spazio economico europeo

Se utilizzi Google Maps API in un progetto italiano, questa verifica non è opzionale.

Google ha introdotto termini specifici per i clienti dello Spazio economico europeo (SEE), efficaci dall’8 luglio 2025. Le modifiche riguardano i progetti collegati a un billing account con indirizzo SEE e possono incidere su nuovi progetti o integrazioni modificate materialmente. L’Italia rientra tra i territori interessati.

Non è soltanto una modifica contrattuale: alcuni servizi hanno anche comportamenti o condizioni di utilizzo specifici.

La FAQ ufficiale per i clienti SEE è il riferimento da verificare per i progetti europei.

I termini SEE in vigore dall’8 luglio 2025

Google distingue tra:

integrazioni esistenti rimaste in uno stato non modificato;
nuovi progetti;
integrazioni esistenti modificate materialmente.

Tra gli esempi di modifica materiale Google include l’abilitazione di nuovi servizi Generally Available, l’uso di nuovi metodi o campi e l’aggiunta di determinate funzionalità.

Per questo non conviene copiare automaticamente un’architettura progettata anni fa in un nuovo progetto italiano senza verificare le condizioni correnti.

Places API, contenuti Places e Places UI Kit

Uno dei cambiamenti più rilevanti riguarda Places.

Google indica che, quando le regole SEE si applicano e vuoi visualizzare contenuti relativi a Places insieme a una mappa, per le nuove integrazioni va considerato Places UI Kit.

La documentazione specifica che, in determinati casi soggetti alle nuove condizioni, il modo in cui i contenuti Places possono essere visualizzati insieme a una mappa è regolato diversamente rispetto alle vecchie integrazioni.

La conseguenza progettuale è importante: scegliere Maps JavaScript API e Places API come due pezzi indipendenti e collegarli alla fine potrebbe non essere l’architettura corretta per un nuovo progetto SEE.

Perché il tipo di billing account può cambiare l’architettura dell’integrazione

Un tutorial tecnico tende a concentrarsi su codice e API key, ma il billing account può determinare quali condizioni si applicano.

Prima di progettare un nuovo servizio in Italia conviene quindi verificare:

a quale billing account è collegato il progetto;
quali Google Maps Platform Services utilizzerà;
se l’integrazione è nuova o materialmente modificata;
quali regole specifiche esistono per quei servizi;
se Places UI Kit è richiesto o più appropriato per l’esperienza prevista.

Per integrazioni complesse o con implicazioni contrattuali importanti, la documentazione tecnica non sostituisce la verifica dei termini applicabili al proprio account.

API Google Maps legacy: cosa non conviene iniziare oggi

Google distingue tra prodotti attuali, prodotti Legacy e servizi deprecati.

Legacy non significa necessariamente che un servizio smetta di funzionare domani. Significa però che non è la base che sceglierei per iniziare una nuova integrazione quando Google indica un successore moderno.

La pagina ufficiale dei prodotti Legacy è il controllo più rapido quando un tutorial propone servizi che non riconosci.

Directions API e Distance Matrix API sono Legacy

Google classifica:

Directions API come Legacy;
Distance Matrix API come Legacy.

Per i nuovi progetti il percorso indicato è Routes API.

Lo stesso principio vale sul lato Maps JavaScript per i vecchi servizi Directions e Distance Matrix, per i quali Google indica classi e servizi più recenti come riferimento.

Routes API è il percorso attuale per i nuovi progetti

Routes API separa in modo più esplicito due job:

calcolare un percorso;
calcolare una matrice tra più origini e destinazioni.

Se stai iniziando un’applicazione di logistica, delivery, ricerca del negozio più vicino o stima dei tempi di percorrenza, partire direttamente dalla documentazione Routes evita di costruire un nuovo componente su un servizio che Google ha già spostato nel catalogo Legacy.

Places API Legacy e Places API (New)

Anche Places ha attraversato una migrazione importante.

La versione nuova introduce differenze nelle richieste, nei campi restituiti e nella gestione dei field mask.

Google mantiene una documentazione specifica per la migrazione da Places Legacy.

Se un tutorial utilizza endpoint o pattern Places precedenti, quindi, non basta controllare che il codice “sembri ancora plausibile”: bisogna verificare a quale generazione dell’API si riferisce.

Come riconoscere un tutorial ormai obsoleto

Ci sono alcuni segnali pratici:

presenta “Google Maps API” come un singolo servizio indistinto;
calcola ancora i costi soltanto attraverso il vecchio credito mensile da 200 dollari;
insegna Directions API come prima scelta per un progetto nuovo;
utilizza Distance Matrix API senza menzionare Routes;
tratta Places Legacy come se fosse l’unica versione;
non parla di restrizioni della API key;
per un progetto europeo ignora completamente le condizioni SEE.

La data di pubblicazione del tutorial aiuta, ma non basta. Una guida aggiornata superficialmente può conservare codice e architettura vecchi.

Alternative a Google Maps API: quale scegliere e perché

Google Maps API non è automaticamente la scelta migliore per qualsiasi progetto geografico.

La decisione dipende almeno da:

tipo di mappa;
geocoding e ricerca richiesti;
routing;
dati proprietari;
livello di personalizzazione cartografica;
condizioni di licenza;
volume e prevedibilità dei costi;
necessità di utilizzare dati Google;
controllo desiderato sull’infrastruttura.

È inoltre importante evitare confronti impropri: Mapbox, HERE e TomTom sono piattaforme geospaziali; Leaflet è una libreria JavaScript; OpenStreetMap è un progetto e un ecosistema di dati cartografici; SerpApi risolve un problema ancora diverso.

Lo stesso vale per Apple: Apple Maps è prima di tutto il prodotto cartografico e di navigazione destinato all’utente, mentre quando devi integrare le mappe Apple in un sito o in un’app entrano in gioco MapKit e gli strumenti dedicati agli sviluppatori. Prima di confrontare piattaforme, API e prezzi conviene quindi capire se stai scegliendo un navigatore oppure uno stack di sviluppo.

Soluzione	La valuterei soprattutto per	Trade-off da verificare
Google Maps Platform	Ecosistema Google, Maps + Places + Routes	PAYG per SKU o piani in abbonamento, condizioni d’uso e regole SEE
Apple MapKit / MapKit JS	Integrare Apple Maps in app e siti, soprattutto in progetti vicini all’ecosistema Apple	Quote, termini Apple, compatibilità e restrizioni d’uso per il caso specifico
Mapbox	Cartografia web/mobile altamente personalizzabile	Pricing e servizi differiscono da Google
HERE	Routing, localizzazione e scenari enterprise/mobility	Stack e modello commerciale propri
TomTom	Mappe, routing, traffico e search	Verificare quote e copertura per il caso d’uso
MapTiler	Mappe, tile, geocoding e controllo visuale	Piano e licenza in base all’utilizzo
OpenStreetMap + Leaflet/provider	Stack aperto e flessibile	Tile hosting e servizi vanno progettati separatamente
SerpApi	Ottenere risultati strutturati da Google Maps Search	Non sostituisce un’API per renderizzare mappe

Mapbox

Mapbox offre mappe web e mobile, search, geocoding e altri servizi geospaziali.

Uno dei suoi punti forti è il controllo sulla rappresentazione cartografica. Il pricing di Mapbox GL JS include una soglia gratuita di map load mensili prima degli scaglioni a consumo, ma non va confrontato direttamente con un singolo SKU Google senza normalizzare cosa produce effettivamente ogni chiamata.

Lo valuterei soprattutto quando lo stile e il comportamento della mappa sono parte importante del prodotto.

HERE

HERE Maps API for JavaScript permette di sviluppare mappe personalizzate e si inserisce in un ecosistema che comprende routing, geocoding e servizi di localizzazione.

HERE ha particolare senso quando il progetto entra in scenari mobility, fleet, logistica o enterprise nei quali routing e dati geografici assumono un ruolo centrale.

TomTom

TomTom Maps APIs comprende Map Display, Routing, Search, Geocoding, Traffic e altri servizi.

Il modello prevede quote gratuite mensili per diverse API e successivo consumo a pagamento.

Anche qui il criterio non dovrebbe essere “costa meno di Google” in astratto. Va confrontato il flusso completo: mappa, ricerca, routing, traffico, volumi e copertura necessaria.

MapTiler

MapTiler Cloud offre mappe, tile, geocoding e API con piani differenziati.

È interessante quando vuoi mantenere un forte controllo sulla cartografia o lavorare con un ecosistema basato su standard e dati differenti da quelli Google.

Il piano Free ha limiti e condizioni d’uso proprie; per un servizio commerciale vanno quindi verificate le condizioni del piano corretto, non semplicemente usata la parola “free” come sinonimo di produzione gratuita.

OpenStreetMap con Leaflet

Questa combinazione viene spesso descritta troppo rapidamente come “alternativa gratuita a Google Maps”, ma mette insieme due cose diverse.

Leaflet è una libreria JavaScript open source per realizzare mappe interattive.

OpenStreetMap fornisce un enorme patrimonio di dati cartografici aperti, ma i tile server pubblici standard del progetto non sono un CDN commerciale gratuito destinato a qualunque volume.

La policy ufficiale dei tile OpenStreetMap specifica limiti, caching e casi non ammessi e sottolinea l’assenza di SLA.

Per un progetto reale puoi quindi usare Leaflet con:

un provider di tile;
servizi di geocoding separati;
un’infrastruttura propria;
dati OpenStreetMap secondo la relativa licenza.

È uno stack più componibile, ma proprio per questo richiede decisioni che Google Maps Platform nasconde dietro un ecosistema più integrato.

SerpApi: perché risolve un problema differente

SerpApi compare spesso per la query “Google Maps API”, ma è importante non confondere i due prodotti.

La sua Google Maps API è progettata per ottenere risultati strutturati provenienti dalla ricerca Google Maps.

Può quindi avere senso quando il job è raccogliere programmaticamente risultati, luoghi o informazioni restituite da Google Maps Search attraverso il servizio SerpApi.

Non è invece un sostituto diretto di Maps JavaScript API se devi renderizzare e programmare una mappa nel tuo sito o nella tua applicazione.

Questa distinzione risolve una delle ambiguità più frequenti della query stessa: due prodotti possono parlare entrambi di “Google Maps API” pur svolgendo lavori molto diversi.

Errori comuni con Google Maps API e come diagnosticarli

Quando una mappa non appare o viene visualizzata con un messaggio di errore, modificare codice a caso è quasi sempre il modo più lento di procedere.

Maps JavaScript API scrive errori e warning nella console del browser. Google mantiene una tabella ufficiale degli errori di Maps JavaScript API con causa e soluzione.

La chiave è assente, invalida o non autorizzata

Due errori molto espliciti sono:

MissingKeyMapError: manca la API key richiesta;
InvalidKeyMapError: la chiave fornita non è valida o non viene riconosciuta.

Controlla prima il tag che carica Maps JavaScript API e verifica che key= contenga la credenziale prevista per quell’ambiente.

Se gestisci più ambienti — sviluppo, staging e produzione — verifica inoltre di non aver utilizzato una chiave con restrizioni progettate per un dominio differente.

L’API necessaria non è stata abilitata

ApiNotActivatedMapError indica che Maps JavaScript API non è attiva nel progetto associato alla chiave.

Può capitare facilmente quando:

il progetto Google Cloud esiste;
la chiave esiste;
la fatturazione è configurata;
ma la specifica API non è stata abilitata.

C’è anche ApiTargetBlockedMapError, che può comparire quando le API restrictions della chiave non autorizzano il servizio richiesto.

Referrer o indirizzo IP non consentito

Se la console mostra RefererNotAllowedMapError, l’URL dal quale stai caricando Maps JavaScript API non corrisponde ai referrer autorizzati.

Controlla soprattutto:

protocollo http/https;
dominio principale;
sottodomini;
ambiente staging;
eventuale porta locale;
pattern inserito nelle restrizioni.

Per le chiamate server-side il problema equivalente può derivare invece dalla restrizione IP applicata alla chiave.

Billing e quote

Una mappa oscurata o contrassegnata per uso di sviluppo è spesso collegata a API key o billing.

OverQuotaMapError, invece, segnala che l’applicazione ha superato i limiti di utilizzo configurati.

In quel caso devi capire se si tratta di:

quota troppo bassa rispetto al traffico reale;
picco legittimo;
chiamate duplicate o non necessarie;
loop applicativo;
abuso della chiave;
configurazione non ottimizzata.

Aumentare semplicemente il limite senza diagnosticare il traffico può trasformare un errore tecnico in un problema di fatturazione.

Codice copiato da una API legacy

Un altro tipo di errore è meno evidente: il codice funziona, ma stai iniziando il progetto sull’API sbagliata.

Se il tutorial utilizza Directions API, Distance Matrix API o vecchi endpoint Places, verifica la pagina Legacy prima di investire tempo nell’integrazione.

Il fatto che un endpoint esista ancora non significa che sia la scelta migliore per un progetto nuovo.

Conclusione

La domanda giusta non è semplicemente “come ottenere una Google Maps API key?”, ma quale componente di Google Maps Platform risolve il problema del progetto.

Per mostrare una normale mappa aziendale, Maps Embed può essere sufficiente e ha uno SKU gratuito illimitato. Per una mappa web interattiva programmabile il riferimento è Maps JavaScript API. Places serve quando lavori con luoghi, Geocoding con indirizzi e coordinate, Routes con itinerari e matrici.

Prima di andare in produzione conviene poi fare quattro verifiche che evitano gran parte dei problemi successivi: scegliere API non Legacy, limitare correttamente le chiavi, stimare i costi per SKU e controllare le condizioni SEE applicabili al progetto.

Google Maps Platform resta una soluzione molto completa, soprattutto quando mappe, Places e routing devono convivere nello stesso ecosistema. Non è però l’unica opzione: Mapbox, HERE, TomTom, MapTiler e stack basati su OpenStreetMap possono essere preferibili quando cambiano esigenze di controllo cartografico, dati, licenza o infrastruttura.

La scelta migliore, quindi, parte dall’architettura: definisci prima cosa deve fare la mappa e quali dati deve utilizzare. Solo dopo scegli API, credenziali e modello di costo.

Google Maps API: cos’è, come funziona, chiave API, costi e come usarla