Incorporare una mappa

Questa guida mostra come incorporare una mappa interattiva nella tua pagina web.

Crea l'URL dell'API Maps Embed

Di seguito è riportato un URL di esempio che carica l'API Maps Embed:

https://www.google.com/maps/embed/v1/MAP_MODE?key=YOUR_API_KEY&PARAMETERS

Sostituisci:

  • MAP_MODE con la modalità mappa.
  • YOUR_API_KEY con la tua chiave API. Per saperne di più, consulta Ottieni la chiave API.
  • PARAMETERS con i parametri obbligatori e facoltativi per la modalità mappa.

Aggiungi l'URL in un iframe

Per utilizzare l'API Maps Embed nella tua pagina web, imposta l'URL che hai creato come valore dell'attributo src di un iframe. Controlla le dimensioni della mappa con gli attributi height e width dell'iframe, ad esempio:

<iframe
  width="450"
  height="250"
  frameborder="0" style="border:0"
  referrerpolicy="strict-origin-when-cross-origin"
  src="https://www.google.com/maps/embed/v1/MAP_MODE?key=YOUR_API_KEY&PARAMETERS"
  allowfullscreen>
</iframe>

L'esempio di iframe riportato sopra utilizza le proprietà aggiuntive:

  • La proprietà allowfullscreen per consentire la visualizzazione a schermo intero di alcune parti della mappa.
  • Le proprietà frameborder="0" e style="border:0" per rimuovere il bordo standard dell'iframe intorno alla mappa.
  • La proprietà referrerpolicy="strict-origin-when-cross-origin" garantisce che il browser invii il dominio del tuo sito web come intestazione Referer a Google. In questo modo, le restrizioni delle chiavi API possono convalidare la richiesta, mantenendo privati i percorsi delle pagine specifiche.

Puoi ridimensionare l'iframe in base alla struttura e al design del tuo sito web, ma riteniamo che i visitatori di solito trovino più facile interagire con mappe più grandi. Tieni presente che le mappe incorporate non sono supportate se le dimensioni sono inferiori a 200 px.

Informazioni sul referrer e limitazioni relative alle chiavi API

Se il sito web di hosting ha un meta tag referrer impostato su no-referrer o same-origin, il browser non invierà l'intestazione Referer a Google. Ciò potrebbe causare il rifiuto delle richieste da parte della restrizione della chiave API. Affinché la limitazione funzioni correttamente, aggiungi una proprietà referrerpolicy all'iframe, come nell'esempio precedente, per consentire esplicitamente l'invio delle intestazioni Referer a Google.

  • strict-origin-when-cross-origin (consigliato): invia a Google solo il tuo dominio di base (ad es. https://example.com/). In questo modo, i percorsi pagina specifici rimangono privati, consentendo comunque il funzionamento delle restrizioni delle chiavi API.
  • no-referrer-when-downgrade (legacy): invia l'intero URL, inclusi i percorsi pagina specifici e i parametri di query (ad es. https://example.com/contact?user=123).

Scopri di più sull'intestazione Referrer-Policy.

Scegli le modalità mappa

Puoi specificare una delle seguenti modalità mappa da utilizzare nell'URL della richiesta:

  • place: mostra un segnaposto sulla mappa in un luogo o indirizzo specifico, ad esempio un punto di riferimento, un'attività, un elemento geografico o una città.
  • view: restituisce una mappa senza indicatori o indicazioni stradali.
  • directions: mostra il percorso tra due o più punti specificati sulla mappa, nonché la distanza e il tempo di percorrenza.
  • streetview: mostra viste panoramiche interattive da località designate.
  • search: mostra i risultati di una ricerca nell'area della mappa visibile.

Modalità place

Il seguente URL utilizza la modalità mappa place per visualizzare un indicatore sulla mappa in corrispondenza della Torre Eiffel:

https://www.google.com/maps/embed/v1/place
  ?key=YOUR_API_KEY
  &q=Eiffel+Tower,Paris+France

Puoi utilizzare i seguenti parametri:

Parametro Tipo Descrizione Valori accettati
q Obbligatorio Definisce la posizione dell'indicatore sulla mappa. Nome del luogo, indirizzo, Plus Code o ID luogo con escape URL. L'API Maps Embed supporta sia + sia %20 per l'escape degli spazi. Ad esempio, converti "City Hall, New York, NY" in City+Hall,New+York,NY o i Plus Code "849VCWC8+R9" in 849VCWC8%2BR9.
center Facoltativo Definisce il centro della visualizzazione mappa. Accetta valori di latitudine e longitudine separati da virgola, ad esempio: 37.4218,-122.0840.
zoom Facoltativo Imposta il livello di zoom iniziale della mappa. I valori vanno da 0 (il mondo intero) a 21 (singoli edifici). Il limite massimo può variare a seconda dei dati della mappa disponibili nella località selezionata.
maptype Facoltativo Definisce il tipo di riquadri della mappa da caricare. roadmap (predefinito) o satellite
language Facoltativo Definisce la lingua da utilizzare per gli elementi UI e per la visualizzazione delle etichette sui riquadri della mappa. Per impostazione predefinita, i visitatori vedranno una mappa nella loro lingua. Questo parametro è supportato solo per alcuni riquadri dei paesi. Se la lingua specifica richiesta non è supportata per il set di riquadri, verrà utilizzata la lingua predefinita per quel set di riquadri.
region Facoltativo Definisce i confini e le etichette appropriati da visualizzare, in base alle sensibilità geopolitiche. Accetta un codice regione specificato come sottotag di regione Unicode di due caratteri (non numerici) che corrisponde ai valori di due caratteri ccTLD ("dominio di primo livello") familiari. Per le regioni supportate, consulta i dettagli sulla copertura di Google Maps Platform.

Modalità view

L'esempio seguente utilizza la modalità view e il parametro facoltativo maptype per visualizzare una vista satellitare della mappa:

https://www.google.com/maps/embed/v1/view
  ?key=YOUR_API_KEY
  &center=-33.8569,151.2152
  &zoom=18
  &maptype=satellite

Puoi utilizzare i seguenti parametri:

Parametro Tipo Descrizione Valori accettati
center Obbligatorio Definisce il centro della visualizzazione mappa. Accetta valori di latitudine e longitudine separati da virgola, ad esempio: 37.4218,-122.0840.
zoom Facoltativo Imposta il livello di zoom iniziale della mappa. I valori vanno da 0 (il mondo intero) a 21 (singoli edifici). Il limite massimo può variare a seconda dei dati della mappa disponibili nella località selezionata.
maptype Facoltativo Definisce il tipo di riquadri della mappa da caricare. roadmap (predefinito) o satellite
language Facoltativo Definisce la lingua da utilizzare per gli elementi UI e per la visualizzazione delle etichette sui riquadri della mappa. Per impostazione predefinita, i visitatori vedranno una mappa nella loro lingua. Questo parametro è supportato solo per alcuni riquadri dei paesi. Se la lingua specifica richiesta non è supportata per il set di riquadri, verrà utilizzata la lingua predefinita per quel set di riquadri.
region Facoltativo Definisce i confini e le etichette appropriati da visualizzare, in base alle sensibilità geopolitiche. Accetta un codice regione specificato come sottotag di regione Unicode di due caratteri (non numerici) che corrisponde ai valori di due caratteri ccTLD ("dominio di primo livello") familiari. Per le regioni supportate, consulta i dettagli sulla copertura di Google Maps Platform.

Modalità directions

L'esempio seguente utilizza la modalità directions per visualizzare il percorso tra Oslo e Telemark, in Norvegia, la distanza e il tempo di percorrenza evitando pedaggi e autostrade.

https://www.google.com/maps/embed/v1/directions
  ?key=YOUR_API_KEY
  &origin=Oslo+Norway
  &destination=Telemark+Norway
  &avoid=tolls|highways

Puoi utilizzare i seguenti parametri:

Parametro Tipo Descrizione Valori accettati
origin Obbligatorio Definisce il punto di partenza da cui visualizzare le indicazioni stradali. Nome del luogo, indirizzo, Plus Code, coordinate di latitudine/longitudine o ID luogo con escape URL. L'API Maps Embed supporta sia + sia %20 per l'escape degli spazi. Ad esempio, converti "City Hall, New York, NY" in City+Hall,New+York,NY o i Plus Code "849VCWC8+R9" in 849VCWC8%2BR9.
destination Obbligatorio Definisce il punto di arrivo delle indicazioni stradali. Nome del luogo, indirizzo, Plus Code, coordinate di latitudine/longitudine o ID luogo con escape URL. L'API Maps Embed supporta sia + sia %20 per l'escape degli spazi. Ad esempio, converti "City Hall, New York, NY" in City+Hall,New+York,NY o i Plus Code "849VCWC8+R9" in 849VCWC8%2BR9.
waypoints Facoltativo Specifica uno o più luoghi intermedi per calcolare il percorso tra l'origine e la destinazione. Nome, indirizzo o ID luogo. È possibile specificare più tappe utilizzando il carattere barra verticale (|) per separare i luoghi (ad es. Berlin,Germany|Paris,France). Puoi specificare fino a 20 tappe.
mode Facoltativo Definisce il metodo di viaggio. Se non viene specificata alcuna modalità, l'API Maps Embed mostrerà una o più delle modalità più pertinenti per il percorso specificato. driving, walking (che preferisce i percorsi pedonali e i marciapiedi, se disponibili), bicycling (che preferisce i percorsi che utilizzano piste ciclabili e strade preferite, se disponibili), transit o flying.
avoid Facoltativo Specifica le caratteristiche da evitare nelle indicazioni stradali. Tieni presente che ciò non preclude i percorsi che includono le funzionalità limitate, ma indirizza il risultato verso percorsi più favorevoli. tolls, ferries e/o highways. Separa più valori con la barra verticale (ad es. avoid=tolls|highways).
units Facoltativo Specifica il metodo di misurazione, metrico o imperiale, quando vengono visualizzate le distanze nei risultati. Se non specifichi units, le unità da utilizzare vengono determinate dal paese origin della query. metric o imperial
center Facoltativo Definisce il centro della visualizzazione mappa. Accetta valori di latitudine e longitudine separati da virgola, ad esempio: 37.4218,-122.0840.
zoom Facoltativo Imposta il livello di zoom iniziale della mappa. I valori vanno da 0 (il mondo intero) a 21 (singoli edifici). Il limite massimo può variare a seconda dei dati della mappa disponibili nella località selezionata.
maptype Facoltativo Definisce il tipo di riquadri della mappa da caricare. roadmap (predefinito) o satellite
language Facoltativo Definisce la lingua da utilizzare per gli elementi UI e per la visualizzazione delle etichette sui riquadri della mappa. Per impostazione predefinita, i visitatori vedranno una mappa nella loro lingua. Questo parametro è supportato solo per alcuni riquadri dei paesi. Se la lingua specifica richiesta non è supportata per il set di riquadri, verrà utilizzata la lingua predefinita per quel set di riquadri.
region Facoltativo Definisce i confini e le etichette appropriati da visualizzare, in base alle sensibilità geopolitiche. Accetta un codice regione specificato come sottotag di regione Unicode di due caratteri (non numerici) che corrisponde ai valori di due caratteri ccTLD ("dominio di primo livello") familiari. Per le regioni supportate, consulta i dettagli sulla copertura di Google Maps Platform.

Modalità streetview

L'API Maps Embed ti consente di visualizzare le immagini di Street View come panoramiche interattive da località designate in tutta la sua area di copertura. Sono disponibili anche foto sferiche fornite dagli utenti e collezioni speciali di Street View.

Ogni panoramica in Street View offre una visuale completa a 360° da un'unica posizione. Le immagini contengono una visuale orizzontale a 360 gradi (una panoramica completa) e una visuale verticale a 180 gradi (dall'alto verso il basso). La modalità streetview fornisce un visualizzatore che esegue il rendering della panoramica risultante come una sfera con una fotocamera al centro. Puoi manipolare la videocamera per controllarne lo zoom e l'orientamento.

Vedi la seguente panoramica della modalità streetview:

https://www.google.com/maps/embed/v1/streetview
  ?key=YOUR_API_KEY
  &location=46.414382,10.013988
  &heading=210
  &pitch=10
  &fov=35

Uno dei seguenti parametri URL è obbligatorio:

  • location accetta una latitudine e una longitudine come valori separati da virgola (46.414382,10.013988). L'API mostra la panoramica fotografata più vicina a questa posizione. Poiché le immagini di Street View vengono aggiornate periodicamente e le fotografie possono essere scattate ogni volta da posizioni leggermente diverse, è possibile che la tua posizione venga agganciata a una panoramica diversa quando le immagini vengono aggiornate.

  • pano è un ID panorama specifico. Se specifichi un pano, puoi anche specificare un location. location viene utilizzato solo se l'API non riesce a trovare l'ID panorama.

I seguenti parametri URL sono facoltativi:

Parametro Tipo Descrizione Valori accettati
heading Facoltativo Indica la direzione della bussola della fotocamera in gradi in senso orario rispetto al nord. Valore in gradi da -180° a 360°
pitch Facoltativo specifica l'angolazione, verso l'alto o verso il basso, della videocamera. I valori positivi inclinano la videocamera verso l'alto, mentre i valori negativi la inclinano verso il basso. L'inclinazione predefinita di 0° viene impostata in base alla posizione della videocamera al momento dell'acquisizione dell'immagine. Per questo motivo, un'inclinazione di 0° è spesso, ma non sempre, orizzontale. Ad esempio, un'immagine scattata su una collina probabilmente mostrerà un'inclinazione predefinita non orizzontale. Valore in gradi da -90° a 90°
fov Facoltativo determina il campo visivo orizzontale dell'immagine. Il valore predefinito è 90°. Quando si utilizza un'area visibile di dimensioni fisse, il campo visivo può essere considerato il livello di zoom, con numeri più piccoli che indicano un livello di zoom più elevato. Valore in gradi, con un intervallo compreso tra 10° e 100°
center Facoltativo Definisce il centro della visualizzazione mappa. Accetta valori di latitudine e longitudine separati da virgola, ad esempio: 37.4218,-122.0840.
zoom Facoltativo Imposta il livello di zoom iniziale della mappa. I valori vanno da 0 (il mondo intero) a 21 (singoli edifici). Il limite massimo può variare a seconda dei dati della mappa disponibili nella località selezionata.
maptype Facoltativo Definisce il tipo di riquadri della mappa da caricare. roadmap (predefinito) o satellite
language Facoltativo Definisce la lingua da utilizzare per gli elementi UI e per la visualizzazione delle etichette sui riquadri della mappa. Per impostazione predefinita, i visitatori vedranno una mappa nella loro lingua. Questo parametro è supportato solo per alcuni riquadri dei paesi. Se la lingua specifica richiesta non è supportata per il set di riquadri, verrà utilizzata la lingua predefinita per quel set di riquadri.
region Facoltativo Definisce i confini e le etichette appropriati da visualizzare, in base alle sensibilità geopolitiche. Accetta un codice regione specificato come sottotag di regione Unicode di due caratteri (non numerici) che corrisponde ai valori di due caratteri ccTLD ("dominio di primo livello") familiari. Per le regioni supportate, consulta i dettagli sulla copertura di Google Maps Platform.

Modalità search

La modalità Search mostra i risultati di una ricerca nell'area della mappa visibile. Ti consigliamo di definire una località per la ricerca, includendola nel termine di ricerca (record+stores+in+Seattle) o includendo un parametro center e zoom per limitare la ricerca.

https://www.google.com/maps/embed/v1/search
  ?key=YOUR_API_KEY
  &q=record+stores+in+Seattle

Puoi utilizzare i seguenti parametri:

Parametro Tipo Descrizione Valori accettati
q Obbligatorio Definisce il termine di ricerca. Può includere una limitazione geografica, come in+Seattle o near+98033.
center Facoltativo Definisce il centro della visualizzazione mappa. Accetta valori di latitudine e longitudine separati da virgola, ad esempio: 37.4218,-122.0840.
zoom Facoltativo Imposta il livello di zoom iniziale della mappa. I valori vanno da 0 (il mondo intero) a 21 (singoli edifici). Il limite massimo può variare a seconda dei dati della mappa disponibili nella località selezionata.
maptype Facoltativo Definisce il tipo di riquadri della mappa da caricare. roadmap (predefinito) o satellite
language Facoltativo Definisce la lingua da utilizzare per gli elementi UI e per la visualizzazione delle etichette sui riquadri della mappa. Per impostazione predefinita, i visitatori vedranno una mappa nella loro lingua. Questo parametro è supportato solo per alcuni riquadri dei paesi. Se la lingua specifica richiesta non è supportata per il set di riquadri, verrà utilizzata la lingua predefinita per quel set di riquadri.
region Facoltativo Definisce i confini e le etichette appropriati da visualizzare, in base alle sensibilità geopolitiche. Accetta un codice regione specificato come sottotag di regione Unicode di due caratteri (non numerici) che corrisponde ai valori di due caratteri ccTLD ("dominio di primo livello") familiari. Per le regioni supportate, consulta i dettagli sulla copertura di Google Maps Platform.

Parametri ID luogo

L'API Maps Embed supporta l'utilizzo degli ID luogo anziché fornire un nome o un indirizzo di un luogo. Gli ID luogo sono un modo stabile per identificare in modo univoco un luogo. Per saperne di più, consulta la documentazione dell'API Places (nuova).

L'API Maps Embed accetta gli ID luogo per i seguenti parametri URL:

  • q
  • origin
  • destination
  • waypoints

Per utilizzare un ID luogo, devi prima aggiungere il prefisso place_id:. Il seguente codice specifica il municipio di New York come origine di una richiesta di indicazioni stradali: origin=place_id:ChIJs--MqP1YwokRBwAhjXWIHn8.

  • radius imposta un raggio, specificato in metri, in cui cercare una panoramica, centrata sulla latitudine e sulla longitudine specificate. I valori validi sono numeri interi non negativi. Il valore predefinito è 50.

  • source limita le ricerche di Street View alle fonti selezionate. I valori validi sono:

    • default utilizza le origini predefinite per Street View; le ricerche non sono limitate a origini specifiche.
    • outdoor limita le ricerche alle raccolte all'aperto. Le raccolte indoor non sono incluse nei risultati di ricerca. Tieni presente che le panoramiche esterne potrebbero non esistere per la località specificata. Tieni presente inoltre che la ricerca restituisce solo i panorami per i quali è possibile determinare se sono interni o esterni. Ad esempio, le foto sferiche non vengono restituite perché non è noto se siano state scattate in interni o in esterni.