Places UI Kit: una libreria pronta all'uso che offre spazio per la personalizzazione e il controllo agli sviluppatori. Provalo e condividi il tuo feedback sull'esperienza con UI Kit.

Google utilizza la tecnologia AI per tradurre i contenuti nella tua lingua preferita. Le traduzioni generate dall'AI potrebbero contenere errori.

Messaggi di errore

Questa pagina descrive i messaggi di errore che possono essere restituiti dall'API Maps JavaScript. L'API Maps JavaScript scrive messaggi di errore e avviso nella console JavaScript. Possono verificarsi anche determinate condizioni di errore che comportano la visualizzazione di una mappa oscurata con filigrana.

Errori relativi alla chiave API e alla fatturazione

Risoluzione dei problemi

In determinate circostanze, potrebbe essere visualizzata una mappa oscurata o un'immagine di Street View "negativa" con la filigrana "Solo per scopi di sviluppo". Questo comportamento in genere indica problemi con una chiave API o con la fatturazione. Per utilizzare i prodotti Google Maps Platform, la fatturazione deve essere abilitata nel tuo account e tutte le richieste devono includere una chiave API valida. Per assistenza su come trovare i messaggi di errore, consulta la sezione Controllare gli errori nel browser.

Il seguente flusso ti aiuterà a risolvere il problema.

Stai utilizzando una chiave API?

Non saprei. Come faccio a verificare se sto utilizzando una chiave API?

Una chiave API viene passata come parametro key nell'URL utilizzato per caricare l'API Maps JavaScript. Ecco alcune opzioni per verificare se stai utilizzando una chiave API:

Utilizza l'estensione di Chrome Google Maps Platform API Checker. In questo modo puoi determinare se il tuo sito web sta implementando correttamente le API di Google Maps concesse in licenza da Google.
Se utilizzi una libreria o un plug-in per caricare l'API Maps JavaScript, controlla le impostazioni della libreria e cerca un'opzione per la chiave API.
Controlla gli errori nel browser. Se visualizzi i seguenti messaggi, significa che non stai utilizzando correttamente la chiave API:

Avviso dell'API Maps JavaScript di Google: NoApiKeys
Errore dell'API Google Maps JavaScript: MissingKeyMapError

Per gli sviluppatori web:

Se hai accesso al codice sorgente della tua applicazione, cerca il tag <script>, che viene utilizzato per caricare l'API Maps JavaScript. Quando carichi l'API Maps JavaScript, sostituisci YOUR_API_KEY nel codice seguente con la tua chiave API.
```
  <script async defer
    src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&callback=initMap">
  </script>
```
Controlla il traffico di rete generato dal tuo sito web nel browser. In Chrome, puoi visualizzarlo utilizzando la scheda DevTools Rete. Qui vedrai le richieste di rete effettuate dal tuo sito web. Le richieste effettuate utilizzando l'API Maps JavaScript saranno nel percorso maps/api/js. Qui puoi verificare se le richieste utilizzano il parametro key. Potrebbe essere utile filtrare il traffico di rete in base a maps/api/js quando visualizzi la scheda Rete.

No, non utilizzo una chiave API.

Per ottenere una chiave API, fai clic sul pulsante di seguito. Se non vedi una configurazione guidata, segui le istruzioni complete riportate in Inizia a utilizzare Google Maps Platform.
Inizia

Sì, sto utilizzando una chiave API.

Bene. Andiamo avanti e controlliamo se al tuo progetto è collegato un account di fatturazione.

Al tuo progetto è collegato un account di fatturazione?

Non saprei. Come posso verificare se l'account di fatturazione è collegato al mio progetto?

Vai alla pagina Fatturazione nella console Google Cloud e seleziona il progetto in cui è stata creata la chiave API. Per confermare che la chiave è associata al progetto:

Vai alla sezione Credenziali, a cui puoi accedere dalla barra laterale sinistra in Google Maps Platform > Credenziali.
Verifica che la chiave API che utilizzi attualmente sul tuo sito web sia elencata. In caso contrario, passa a un altro progetto e controlla le credenziali.
Se non riesci a individuare il progetto per la tua chiave API, potresti aver perso l'accesso a questo progetto. Chiedi aiuto ad altri membri della tua organizzazione. Se non è possibile individuare il progetto originale, devi:
1. Crea un nuovo progetto. Per farlo, seleziona Nuovo progetto dall'elenco dei progetti o Crea progetto tramite la pagina Resource Manager.
2. Creazione di una nuova chiave API. Puoi farlo nella pagina Credenziali. A questo punto, fai clic su Crea credenziali e poi seleziona Chiave API.

Una volta individuato il progetto nella console Cloud, verifica se è collegato un account di fatturazione accedendo alla sezione Fatturazione nel menu a sinistra.

No, al mio progetto non è associato un account di fatturazione.

Vai alla pagina Attiva la fatturazione nella console Cloud e aggiungi un account di fatturazione al tuo progetto. Per ulteriori informazioni, consulta Inizia a utilizzare Google Maps Platform.

Sì, al mio progetto è collegato un account di fatturazione.

Bene. Assicuriamoci che il metodo di fatturazione fornito sia valido.

Il metodo di fatturazione fornito non è più valido (ad esempio, una carta di credito scaduta)?

Puoi aggiungere, rimuovere o aggiornare un metodo di pagamento nella console Google Cloud.

Esiste un limite giornaliero autoimposto superato per l'API?

Se hai impostato un limite giornaliero per una delle tue API, il che è comune per evitare aumenti imprevisti, puoi risolvere il problema aumentando il limite giornaliero.

Puoi controllare i limiti giornalieri andando alla dashboard API e servizi nella console Cloud. In questa sezione:

Se richiesto, seleziona un progetto.
Seleziona un'API dall'elenco, quindi fai clic sulla scheda Quote.

La tua chiave API ha una limitazione relativa agli indirizzi IP?

Le chiavi API con una limitazione per indirizzi IP possono essere utilizzate solo con i servizi web destinati all'utilizzo lato server (ad esempio l'API Geocoding e altre API di servizi web). La maggior parte di questi servizi web ha servizi equivalenti all'interno dell'API Maps JavaScript (ad esempio, vedi il servizio di geocodifica). Per utilizzare i servizi lato client dell'API Maps JavaScript, devi creare una chiave API separata che può essere protetta con una limitazione dei referrer HTTP (consulta Ottieni, aggiungi e limita una chiave API).

Codici di errore dell'API Maps JavaScript per sviluppatori e proprietari di siti

Le tabelle seguenti elencano i possibili codici di errore restituiti dall'API Maps JavaScript, con una descrizione della causa e di come risolvere il problema. Per assistenza su come trovare i messaggi di errore, consulta la sezione Controllare gli errori nel browser.

Errori di caricamento della mappa

Se si verifica un errore durante il caricamento dell'API Maps JavaScript, consulta la tabella seguente per trovare le spiegazioni dei codici di errore.

Codice di errore Messaggio Descrizione

Codice di errore	Messaggio	Descrizione
`NotLoadingAPIFromGoogleMapsError`	L'API Maps JavaScript deve essere scaricata direttamente dai server di Google.	L'elemento script che carica l'API Maps JavaScript non è incluso correttamente nella pagina. Affinché l'API funzioni correttamente, deve essere caricata direttamente da https://maps.googleapis.com. Consulta Caricamento dell'API Maps JavaScript.
`TOSViolationMapError`	Questo sito web sembra violare i Termini di servizio dell'API di Google Maps. L'API di Google Maps è stata disabilitata per questo sito web.	La tua applicazione è stata bloccata per mancata conformità ai Termini di servizio di Google Maps Platform, dopo l'invio di diverse notifiche via email. Per presentare ricorso contro il blocco e richiedere la revisione della tua implementazione, compila questo modulo. Riceverai una risposta via email entro pochi giorni lavorativi. Utilizza le credenziali della chiave API o dell'ID client per risolvere questo errore. Consulta la guida alle chiavi API e agli ID client.
`UnauthorizedURLForClientIdMapError`	Questo URL non è autorizzato a utilizzare l'ID cliente Google Maps fornito.	L'ID cliente incluso nel caricamento dello script non è valido, è scaduto o l'indirizzo corrente che carica l'API Maps JavaScript non è stato aggiunto all'elenco degli URL autorizzati. Consulta la sezione Registrazione degli URL autorizzati.

NotLoadingAPIFromGoogleMapsError

L'API Maps JavaScript deve essere scaricata direttamente dai server di Google.

L'elemento script che carica l'API Maps JavaScript non è incluso correttamente nella pagina. Affinché l'API funzioni correttamente, deve essere caricata direttamente da https://maps.googleapis.com.

Consulta Caricamento dell'API Maps JavaScript.

TOSViolationMapError

Questo sito web sembra violare i Termini di servizio dell'API di Google Maps. L'API di Google Maps è stata disabilitata per questo sito web.

La tua applicazione è stata bloccata per mancata conformità ai Termini di servizio di Google Maps Platform, dopo l'invio di diverse notifiche via email. Per presentare ricorso contro il blocco e richiedere la revisione della tua implementazione, compila questo modulo. Riceverai una risposta via email entro pochi giorni lavorativi.

Utilizza le credenziali della chiave API o dell'ID client per risolvere questo errore. Consulta la guida alle chiavi API e agli ID client.

UnauthorizedURLForClientIdMapError

Questo URL non è autorizzato a utilizzare l'ID cliente Google Maps fornito.

L'ID cliente incluso nel caricamento dello script non è valido, è scaduto o l'indirizzo corrente che carica l'API Maps JavaScript non è stato aggiunto all'elenco degli URL autorizzati.

Consulta la sezione Registrazione degli URL autorizzati.

Codici di errore dell'API Maps JavaScript

Se trovi un errore nella console JavaScript di Chrome, nella console web di Firefox o in altri strumenti equivalenti sui browser, consulta la tabella riportata di seguito per trovare le spiegazioni dei codici di errore.

L'API Maps JavaScript restituisce sia errori che avvisi. Un errore indica un problema grave verificatosi durante il caricamento dell'API Maps JavaScript. La tua pagina non può caricare correttamente l'API, che non funzionerà su quella pagina. Un avviso è un messaggio supplementare relativo al caricamento dell'API Maps JavaScript. L'avviso descrive i possibili motivi di un errore o suggerisce potenziali problemi nel codice che carica l'API Maps JavaScript. Se ricevi solo avvisi senza errori, l'API funzionerà correttamente su quella pagina. Tuttavia, ti consigliamo di risolvere anche questi potenziali problemi.

Codice di errore per gli sviluppatori	Tipo	Descrizione
`ApiNotActivatedMapError`	Errore	L'API Maps JavaScript non è attivata nel tuo progetto API. Potresti dover abilitare l'API Maps JavaScript in API nella console Google Cloud. Per attivare l'API Maps JavaScript per il tuo progetto, fai clic sul pulsante qui sotto. Scopri come
`ApiTargetBlockedMapError`	Errore	Questa chiave API non è autorizzata a utilizzare questo servizio o questa API. Controlla le impostazioni delle restrizioni API della tua chiave API nella console Google Cloud per assicurarti che tutte le API e i servizi che devi utilizzare siano specificati correttamente nell'elenco delle API abilitate. Consulta Chiavi API nella console Cloud. Per saperne di più, consulta le best practice per la sicurezza delle API.
`DeletedApiProjectMapError`	Errore	Il tuo progetto API potrebbe essere stato eliminato dalla console Cloud. Controlla il progetto per cui hai generato la chiave API inclusa nel caricatore dell'API JavaScript. Puoi creare un nuovo progetto API e ottenere una nuova chiave nella console Cloud. Per creare un nuovo progetto e ottenere una chiave API per il progetto, fai clic sul pulsante di seguito. Scopri come
`ClientBillingNotEnabledMapError`	Errore	Non hai abilitato la fatturazione per il tuo progetto. Devi abilitare la fatturazione nel progetto Google Cloud associato a questo ID client, qui.
`BillingNotEnabledMapError`	Errore	Non hai abilitato la fatturazione nel tuo progetto, il che sta causando questo errore. Devi abilitare la fatturazione nel progetto Google Cloud qui. Scopri di più
`ExpiredKeyMapError`	Errore	La chiave API inclusa nell'elemento script che carica l'API è scaduta o non è riconosciuta dal sistema. Potresti ricevere questo errore dopo aver creato una nuova chiave API se provi a utilizzarla prima che venga riconosciuta dal sistema. Attendi qualche minuto e riprova oppure potrebbe essere necessario generare una nuova chiave API nella console Cloud. Per ottenere una chiave API, fai clic sul pulsante di seguito. Inizia
`InvalidAppCheckTokenMapError`	Errore	Il token App Check fornito non è valido o è scaduto. Questo errore può verificarsi solo se è in uso la verifica di App Check. Consulta la guida alla verifica App Check.
`InvalidClientIdMapError`	Errore	Per aumentare la sicurezza e l'affidabilità dell'autenticazione, gli ID client di Maps Platform sono deprecati dal 26 maggio 2025 e non potranno più essere utilizzati dopo il 31 maggio 2026. Anziché utilizzare un ID client, devi utilizzare le credenziali della chiave API per autenticare il traffico del servizio API di Google Maps. Per saperne di più, consulta la guida alla migrazione degli ID cliente. Segui i passaggi della guida per ripristinare temporaneamente l'ID client.
`InvalidKeyMapError`	Errore	La chiave API inclusa nell'elemento script che carica l'API non è stata trovata. Assicurati di utilizzare una chiave API corretta. Puoi generare una nuova chiave API nella console Cloud. Per ottenere una chiave API, fai clic sul pulsante di seguito. Inizia
`MalformedCredentialsMapError`	Errore	La tua applicazione utilizza uno schema dell'URI non supportato. Verifica che l'applicazione utilizzi un formato URI valido come definito in RFC 3986.
`MissingKeyMapError`	Errore	Nell'elemento script che carica l'API manca il parametro di autenticazione obbligatorio. Se utilizzi l'API Maps JavaScript, devi utilizzare un parametro `key` con una chiave API valida. Per ulteriori informazioni, consulta Inizia a utilizzare Google Maps Platform. Se utilizzi un ID client, devi utilizzare un parametro `client` con l'ID client o un parametro `key` con una chiave API valida. Per saperne di più, consulta la guida alle chiavi API e agli ID client. Se NON sei il proprietario del sito web, non puoi eseguire alcun passaggio per correggere questo errore. Tuttavia, se possibile, ti consigliamo di informare il proprietario del sito.
`ProjectDeniedMapError`	Errore	La tua richiesta non è stata completata. Potresti trovare ulteriori dettagli sull'errore nella console Cloud. Consulta la console Cloud.
`RefererDeniedMapError`	Errore	La tua applicazione è stata bloccata per mancata conformità ai Termini di servizio di Google Maps Platform, in seguito all'invio di diverse notifiche via email. Per presentare ricorso contro il blocco e richiedere la revisione della tua implementazione, compila questo modulo. Riceverai una risposta via email entro pochi giorni lavorativi.
`RefererNotAllowedMapError`	Errore	L'URL corrente che carica l'API Maps JavaScript non è stato aggiunto all'elenco dei referrer consentiti. Controlla le impostazioni del referrer della chiave API nella console Cloud. Consulta l'API Maps JavaScript e ottieni una chiave API.
`OverQuotaMapError`	Errore	Il numero di richieste ha superato i limiti di utilizzo dell'API Maps JavaScript. Le richieste della tua app funzioneranno di nuovo al successivo ripristino della quota giornaliera. Se NON sei il proprietario del sito web, non puoi eseguire alcun passaggio per correggere questo errore. Tuttavia, ti consigliamo di avvisare il proprietario del sito, se possibile. Per maggiori dettagli, consulta la guida ai limiti di utilizzo. La pagina spiega anche come ottenere limiti di utilizzo più elevati.
`ApiProjectMapError`	Errore	Impossibile risolvere la chiave API fornita o il progetto API a cui è associata. Questo errore potrebbe essere temporaneo. Se questo messaggio di errore persiste, potrebbe essere necessario ottenere una nuova chiave API o creare un nuovo progetto API. Per saperne di più, consulta Inizia a utilizzare Google Maps Platform.
`ClientIdLooksLikeCryptoKey`	Avviso	Potresti aver fornito una chiave di crittografia nel parametro `client`. Specifica il tuo ID client come parametro `client`. Non è necessario utilizzare la chiave di crittografia per l'API Maps JavaScript. Consulta la guida agli ID client.
`ClientIdLooksLikeKey`	Avviso	Potresti aver fornito una chiave API nel parametro `client`. Specifica il tuo ID cliente come parametro `client` oppure utilizza un parametro `key` con una chiave API valida anziché un parametro `client`. Consulta la guida alle chiavi API e agli ID client.
`InvalidChannel`	Avviso	Potresti aver fornito un parametro `channel` non valido. Il canale deve essere una stringa alfanumerica ASCII, che può includere punto (.), trattino basso (_) e trattino (-). Assicurati di specificare un parametro `channel` valido. Consulta Report \| Google Maps Platform.
`InvalidClientId`	Avviso	Il parametro `client` non sembra contenere un ID client corretto. Un ID client deve iniziare con "gme-". Consulta la guida alle chiavi API e agli ID client.
`InvalidKey`	Avviso	La chiave API inclusa nell'elemento script che carica l'API non sembra corretta. Assicurati di utilizzare una chiave API corretta. Puoi generare una nuova chiave API nella console Cloud. Per ottenere una chiave API, fai clic sul pulsante di seguito. Inizia
`InvalidVersion`	Avviso	Potresti aver fornito un numero di versione errato nell'elemento script. Assicurati di utilizzare un numero di versione corretto. Consulta Controllo delle versioni \| API Maps JavaScript.
`KeyLooksLikeClientId`	Avviso	Potresti aver fornito un ID cliente come parametro `key`. Specifica l'ID cliente come parametro `client` anziché come parametro `key` oppure utilizza un parametro `key` con una chiave API valida. Consulta la guida alle chiavi API e agli ID client.
`KeyLooksLikeCryptoKey`	Avviso	Potresti aver fornito una chiave di crittografia o un secret di firma come parametro `key`. Specifica il tuo ID client come parametro `client` e rimuovi il parametro `key` dall'elemento script. La chiave di crittografia non è richiesta per l'API Maps JavaScript. In alternativa, puoi ottenere una chiave API nella console Cloud e utilizzare un parametro `key`. Consulta la guida per specificare un ID client durante il caricamento dell'API.
`KeyLooksLikeProjectNumber`	Avviso	Potresti aver fornito un numero di progetto come parametro `key`. Assicurati di utilizzare una chiave API corretta. Puoi generare una nuova chiave API nella console Cloud. Scopri come ottenere una chiave API.
`NoApiKeys`	Avviso	L'elemento script che carica l'API non ha una chiave API. Assicurati di includere una chiave API valida come parametro `key`. Puoi generare una nuova chiave API nella console Cloud. Per ottenere una chiave API, fai clic sul pulsante di seguito per iniziare. Inizia Se carichi l'API Maps JavaScript dal percorso v2 deprecato, riceverai l'avviso `NoApiKeys`, anche se hai specificato il parametro `key`. Consulta la guida all'upgrade dalla v2 alla v3 ed esegui la migrazione della tua applicazione all'API Maps JavaScript v3.
`RetiredVersion`	Avviso	Potresti aver fornito una versione ritirata nell'elemento dello script. Aggiorna l'applicazione per utilizzare una delle versioni disponibili. Consulta Controllo delle versioni \| API Maps JavaScript.
`SensorNotRequired`	Avviso	Il parametro `sensor` non è più obbligatorio per l'API Maps JavaScript. Ciò non impedirà il corretto funzionamento dell'API Maps JavaScript, ma ti consigliamo di rimuovere il parametro `sensor` dall'elemento script.
`SignatureNotRequired`	Avviso	Il parametro `signature` non è obbligatorio per l'API Maps JavaScript. Ciò non impedirà il corretto funzionamento dell'API Maps JavaScript, ma potrebbe introdurre rischi per la sicurezza. Rimuovilo dall'elemento script.
`SignedInNotSupported`	Avviso	Il parametro `signed_in` è stato ritirato e non è supportato nella versione dell'API Maps JavaScript che stai utilizzando. Ciò non impedirà il funzionamento dell'API Maps JavaScript, ma il comportamento dell'applicazione potrebbe cambiare se utilizzi funzionalità di accesso.
`UrlAuthenticationCommonError`	Errore	Si è verificato un errore che non rientra nelle altre categorie di questa pagina. Questo problema potrebbe essere temporaneo. Riprova a inviare la richiesta dopo un breve ritardo. Se il problema persiste, consulta la guida per gli sviluppatori per assicurarti che la richiesta abbia il formato corretto.

Controllo degli errori nel browser

L'API Maps JavaScript scrive i messaggi di errore in window.console. Questa sezione spiega come controllare l'output di window.console in Google Chrome. Se utilizzi altri browser, consulta la documentazione per lo sviluppo del tuo browser. Per tua informazione, questo è un elenco di strumenti per controllare l'output di window.console in altri browser.

Console web per Firefox.
Debug remoto per Android.
Web Inspector per iOS.

In Chrome, puoi utilizzare la console JavaScript per controllare l'output di window.console come segue.

Per aprire gli Strumenti per sviluppatori, seleziona l'icona del menu > Altri strumenti > Strumenti per sviluppatori.
Per aprire la console JavaScript, premi il tasto Esc sulla tastiera. Il tasto Esc attiva/disattiva la console JavaScript. Se chiudi la console, premi di nuovo il tasto Esc per aprirla.

Se si sono verificati errori o avvisi durante il caricamento dell'API Maps JavaScript, questi vengono visualizzati come una o più righe nella console. Un messaggio di errore o avviso ha il seguente formato:

Google Maps API error: [ERROR CODE] [Link to API document]
o
Google Maps API warning: [ERROR CODE] [Link to API document]

Puoi consultare la tabella dei codici di errore riportata sopra per trovare il codice di errore nel messaggio di errore. Puoi anche trovare i dettagli sul messaggio di errore nel documento API collegato al messaggio.

Nota:puoi ascoltare gli errori di autenticazione in modo programmatico.

Gestione dei browser non supportati

Assicurati che la versione del browser che stai utilizzando sia attualmente supportata dall'API Maps JavaScript.

Se stai sviluppando un'applicazione Windows nativa che viene eseguita in un componente WebView, assicurati di utilizzare WebView2 basato su Edge. Le versioni precedenti di WebView, basate su Internet Explorer, non sono più supportate.

Se il codice continua a non funzionare

Per aiutarti a configurare il codice delle mappe, Brendan Kenny e Mano Marks indicano alcuni errori comuni e come risolvere il problema in questo video.

Cerca errori di battitura. Ricorda che JavaScript è un linguaggio sensibile alle maiuscole.
Controlla le nozioni di base: alcuni dei problemi più comuni si verificano con la creazione iniziale della mappa. Ad esempio:
- Verifica di aver specificato le proprietà zoom e center nelle opzioni della mappa.
- Assicurati di aver dichiarato un elemento div in cui la mappa verrà visualizzata sullo schermo.
- Assicurati che l'elemento div per la mappa abbia un'altezza. Per impostazione predefinita, gli elementi div vengono creati con un'altezza pari a 0 e sono quindi invisibili.
Consulta i nostri esempi per un'implementazione di riferimento.
Utilizza un debugger JavaScript per identificare i problemi, ad esempio quello disponibile negli Strumenti per sviluppatori di Chrome. Inizia cercando gli errori nella console JavaScript.
Pubblica domande su Stack Overflow. Le linee guida su come pubblicare domande efficaci sono disponibili nella pagina Assistenza.