Incorporamento di mappe

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

Creazione dell'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ù, vedi Recupero della chiave API.
  • PARAMETERS con i parametri obbligatori e facoltativi per la modalità della mappa.

Aggiunta dell'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="no-referrer-when-downgrade"
  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 determinate parti della mappa.
  • Le proprietà frameborder="0" e style="border:0" per rimuovere il bordo dell'iframe standard dalla mappa.
  • La proprietà referrerpolicy="no-referrer-when-downgrade" per consentire al browser di inviare l'URL completo come intestazione Referer con la richiesta, in modo che le limitazioni relative alle chiavi API possano funzionare correttamente.

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

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. Di conseguenza, la restrizione della chiave API potrebbe rifiutare le richieste. Per consentire il corretto funzionamento della limitazione, aggiungi una proprietà referrerpolicy all'iframe, come nell'esempio precedente, per consentire esplicitamente l'invio delle intestazioni Referer a Google.

Pubblicità sulla mappa

L'API Maps Embed può includere pubblicità su mappa. Il formato e l'insieme di annunci mostrati in una determinata mappa possono cambiare senza preavviso.

Scelta delle modalità della mappa

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

  • place: mostra un segnaposto sulla mappa in corrispondenza di 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: visualizza il percorso tra due o più punti specificati sulla mappa, nonché la distanza e il tempo di percorrenza.
  • streetview: mostra le viste panoramiche interattive da luoghi designati.
  • search: mostra i risultati di una ricerca nell'area geografica visibile della mappa.

Modalità place

Il seguente URL utilizza la modalità mappa place per visualizzare un indicatore sulla 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. Nome luogo, indirizzo, Plus Code o ID luogo con caratteri di escape tramite URL. L'API Maps Embed supporta sia + che %20 durante l'escape degli spazi. Ad esempio, converti "Municipio, New York, NY" in City+Hall,New+York,NY o i codici Plus "849VCWC8+R9" in 849VCWC8%2BR9.
center Facoltativo Definisce il centro della visualizzazione mappa. Accetta valori di latitudine e longitudine separati da virgole, ad esempio: 37.4218,-122.0840.
zoom Facoltativo Imposta il livello di zoom iniziale della mappa. Valori che vanno da 0 (tutto il mondo) a 21 (singoli edifici). Il limite superiore può variare a seconda dei dati mappa disponibili nella posizione selezionata.
maptype Facoltativo Definisce il tipo di riquadri della mappa da caricare. roadmap (valore predefinito) o satellite
language Facoltativo Definisce la lingua da utilizzare per gli elementi dell'interfaccia utente e per la visualizzazione delle etichette sui riquadri della mappa. Per impostazione predefinita, i visitatori vedranno una mappa nella propria lingua. Questo parametro è supportato solo per alcuni riquadri del paese; se la lingua specifica richiesta non è supportata per il set di riquadri, verrà utilizzata la lingua predefinita di quel set.
region Facoltativo Definisce i confini e le etichette appropriati da visualizzare, in base alle sensibilità geo-politiche. Accetta un codice regione specificato come sottotag di regione Unicode a due caratteri (non numerico) che mappa a valori a due caratteri ccTLD ("dominio di primo livello") familiari. Vedi i dettagli sulla copertura di Google Maps Platform per le regioni supportate.

Modalità view

L'esempio seguente utilizza la modalità view e il parametro maptype facoltativo 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 virgole, ad esempio: 37.4218,-122.0840.
zoom Facoltativo Imposta il livello di zoom iniziale della mappa. Valori che vanno da 0 (tutto il mondo) a 21 (singoli edifici). Il limite superiore può variare a seconda dei dati mappa disponibili nella posizione selezionata.
maptype Facoltativo Definisce il tipo di riquadri della mappa da caricare. roadmap (valore predefinito) o satellite
language Facoltativo Definisce la lingua da utilizzare per gli elementi dell'interfaccia utente e per la visualizzazione delle etichette sui riquadri della mappa. Per impostazione predefinita, i visitatori vedranno una mappa nella propria lingua. Questo parametro è supportato solo per alcuni riquadri del paese; se la lingua specifica richiesta non è supportata per il set di riquadri, verrà utilizzata la lingua predefinita di quel set.
region Facoltativo Definisce i confini e le etichette appropriati da visualizzare, in base alle sensibilità geo-politiche. Accetta un codice regione specificato come sottotag di regione Unicode a due caratteri (non numerico) che mappa a valori a due caratteri ccTLD ("dominio di primo livello") familiari. Vedi i dettagli sulla copertura di Google Maps Platform per le regioni supportate.

Modalità directions

L'esempio seguente utilizza la modalità directions per visualizzare il percorso tra Oslow e Telemark, 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 URL con caratteri di escape o ID luogo. L'API Maps Embed supporta sia + che %20 durante l'escape degli spazi. Ad esempio, converti "Municipio, New York, NY" in City+Hall,New+York,NY o i codici Plus "849VCWC8+R9" in 849VCWC8%2BR9.
destination Obbligatorio Definisce il punto finale delle indicazioni stradali. Nome del luogo, indirizzo, Plus Code, coordinate di latitudine/longitudine URL con caratteri di escape o ID luogo. L'API Maps Embed supporta sia + che %20 durante l'escape degli spazi. Ad esempio, converti "Municipio, New York, NY" in City+Hall,New+York,NY o i codici Plus "849VCWC8+R9" in 849VCWC8%2BR9.
waypoints Facoltativo Specifica uno o più luoghi intermedi per instradare le indicazioni stradali tra il luogo di partenza e la destinazione. Nome, indirizzo o ID luogo del 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 la route specificata. driving, walking (che preferisce percorsi pedonali e marciapiedi, se disponibili), bicycling (che percorre piste ciclabili e strade preferite, se disponibili), transit o flying.
avoid Facoltativo Specifica le funzionalità da evitare nelle indicazioni stradali. Tieni presente che ciò non preclude le route che includono le funzionalità limitate; polarizza il risultato verso route più favorevoli. tolls, ferries e/o highways. Separa più valori con una barra verticale (ad es. avoid=tolls|highways).
units Facoltativo Specifica il metodo di misurazione, metrico o imperiale, quando visualizzi le distanze nei risultati. Se units non sono specificati, il origin paese della query determina le unità da utilizzare. metric o imperial
center Facoltativo Definisce il centro della visualizzazione mappa. Accetta valori di latitudine e longitudine separati da virgole, ad esempio: 37.4218,-122.0840.
zoom Facoltativo Imposta il livello di zoom iniziale della mappa. Valori che vanno da 0 (tutto il mondo) a 21 (singoli edifici). Il limite superiore può variare a seconda dei dati mappa disponibili nella posizione selezionata.
maptype Facoltativo Definisce il tipo di riquadri della mappa da caricare. roadmap (valore predefinito) o satellite
language Facoltativo Definisce la lingua da utilizzare per gli elementi dell'interfaccia utente e per la visualizzazione delle etichette sui riquadri della mappa. Per impostazione predefinita, i visitatori vedranno una mappa nella propria lingua. Questo parametro è supportato solo per alcuni riquadri del paese; se la lingua specifica richiesta non è supportata per il set di riquadri, verrà utilizzata la lingua predefinita di quel set.
region Facoltativo Definisce i confini e le etichette appropriati da visualizzare, in base alle sensibilità geo-politiche. Accetta un codice regione specificato come sottotag di regione Unicode a due caratteri (non numerico) che mappa a valori a due caratteri ccTLD ("dominio di primo livello") familiari. Vedi i dettagli sulla copertura di Google Maps Platform per le regioni supportate.

Modalità streetview

L'API Maps Embed ti consente di mostrare le immagini di Street View come panorami interattivi da località designate in tutta la sua area di copertura. Sono inoltre disponibili le foto sferiche fornite dagli utenti e le raccolte speciali di Street View.

Ogni panoramica Street View fornisce una visione completa a 360 gradi da un'unica posizione. Le immagini contengono una visualizzazione orizzontale a 360 gradi (tutto intorno a sé) e 180 gradi di visualizzazione verticale (dall'alto verso il basso). La modalità streetview mette a disposizione un visualizzatore che mostra il panorama risultante come una sfera con una fotocamera al centro. Puoi manipolare la fotocamera per controllare lo zoom e l'orientamento.

Visualizza la panoramica in modalità streetview riportata di seguito:

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 la latitudine e la longitudine come valori separati da virgole (46.414382,10.013988). L'API mostrerà il panorama fotografato più vicino a questa località. Poiché le immagini di Street View vengono aggiornate periodicamente ed è possibile scattare foto da posizioni leggermente diverse ogni volta, è possibile che la posizione possa agganciarsi a una panoramica diversa quando le immagini vengono aggiornate.

  • pano è un ID panorama specifico. Se specifichi un pano, puoi anche specificare un location. location verrà 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 l'orientamento della fotocamera in gradi in senso orario da 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 indicano che l'angolazione della videocamera è rivolta verso l'alto, mentre i valori negativi indicano l'angolazione della videocamera verso il basso. L'inclinazione predefinita di 0° viene impostata in base alla posizione della fotocamera quando è stata acquisita l'immagine. Per questo motivo, l'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°. Nel caso di un'area visibile a 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 virgole, ad esempio: 37.4218,-122.0840.
zoom Facoltativo Imposta il livello di zoom iniziale della mappa. Valori che vanno da 0 (tutto il mondo) a 21 (singoli edifici). Il limite superiore può variare a seconda dei dati mappa disponibili nella posizione selezionata.
maptype Facoltativo Definisce il tipo di riquadri della mappa da caricare. roadmap (valore predefinito) o satellite
language Facoltativo Definisce la lingua da utilizzare per gli elementi dell'interfaccia utente e per la visualizzazione delle etichette sui riquadri della mappa. Per impostazione predefinita, i visitatori vedranno una mappa nella propria lingua. Questo parametro è supportato solo per alcuni riquadri del paese; se la lingua specifica richiesta non è supportata per il set di riquadri, verrà utilizzata la lingua predefinita di quel set.
region Facoltativo Definisce i confini e le etichette appropriati da visualizzare, in base alle sensibilità geo-politiche. Accetta un codice regione specificato come sottotag di regione Unicode a due caratteri (non numerico) che mappa a valori a due caratteri ccTLD ("dominio di primo livello") familiari. Vedi i dettagli sulla copertura di Google Maps Platform per le regioni supportate.

Modalità search

La modalità Search mostra i risultati di una ricerca nell'area visibile della mappa. Ti consigliamo di definire una località per la ricerca, includendo una località nel termine di ricerca (record+stores+in+Seattle) o includendo un parametro center e zoom per associare 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 restrizione geografica, come in+Seattle o near+98033.
center Facoltativo Definisce il centro della visualizzazione mappa. Accetta valori di latitudine e longitudine separati da virgole, ad esempio: 37.4218,-122.0840.
zoom Facoltativo Imposta il livello di zoom iniziale della mappa. Valori che vanno da 0 (tutto il mondo) a 21 (singoli edifici). Il limite superiore può variare a seconda dei dati mappa disponibili nella posizione selezionata.
maptype Facoltativo Definisce il tipo di riquadri della mappa da caricare. roadmap (valore predefinito) o satellite
language Facoltativo Definisce la lingua da utilizzare per gli elementi dell'interfaccia utente e per la visualizzazione delle etichette sui riquadri della mappa. Per impostazione predefinita, i visitatori vedranno una mappa nella propria lingua. Questo parametro è supportato solo per alcuni riquadri del paese; se la lingua specifica richiesta non è supportata per il set di riquadri, verrà utilizzata la lingua predefinita di quel set.
region Facoltativo Definisce i confini e le etichette appropriati da visualizzare, in base alle sensibilità geo-politiche. Accetta un codice regione specificato come sottotag di regione Unicode a due caratteri (non numerico) che mappa a valori a due caratteri ccTLD ("dominio di primo livello") familiari. Vedi i dettagli sulla copertura di Google Maps Platform per le regioni supportate.

Parametri ID luogo

L'API Maps Embed supporta l'utilizzo di ID luogo anziché fornire un nome o un indirizzo. Gli ID luogo sono un modo stabile per identificare un luogo in modo univoco. Per ulteriori informazioni, consulta la documentazione relativa all'API Google Places.

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, centrato 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 origini selezionate. I valori validi sono:

    • default utilizza le origini predefinite per Street View; le ricerche non sono limitate a fonti specifiche.
    • outdoor limita le ricerche alle raccolte all'aperto. Le raccolte di contenuti di interni non sono incluse nei risultati di ricerca. Tieni presente che i panorami esterni potrebbero non esistere per la località specificata. Inoltre, la ricerca restituisce solo le panoramiche in cui è possibile determinare se gli ambienti sono all'interno o all'esterno. Ad esempio, le foto sferiche non vengono restituite perché non è noto se siano al chiuso o all'aperto.