Introduzione
Con gli URL di Maps puoi creare un URL universale multipiattaforma per avviare Google Maps ed eseguire ricerche, ottenere indicazioni stradali e navigazione e mostrare visualizzazioni mappa e immagini panoramiche. La sintassi dell'URL è la stessa indipendentemente dalla piattaforma in uso.
Non occorre una chiave API di Google per utilizzare gli URL di Maps.
Sintassi multipiattaforma universale
In qualità di sviluppatore di un'app per Android, di un'app per iOS o di un sito web, puoi creare un URL comune, che aprirà Google Maps ed eseguirà l'azione richiesta, a prescindere dalla piattaforma in uso all'apertura della mappa.
- Su un dispositivo Android:
- Se l' app Google Maps per Android è installata e attiva, l'URL avvia Google Maps nell'app ed esegue l'azione richiesta.
- Se l'app Google Maps non è installata o è disattivata, l'URL avvia Google Maps in un browser ed esegue l'azione richiesta.
- Su un dispositivo iOS:
- Se l'app Google Maps per iOS è installata, l'URL avvia Google Maps nell'app ed esegue l'azione richiesta.
- Se l'app Google Maps non è installata, l'URL avvia Google Maps in un browser ed esegue l'azione richiesta.
- Su qualsiasi altro dispositivo, l'URL avvia Google Maps in un browser ed esegue l'azione richiesta.
Ti consigliamo di utilizzare un URL multipiattaforma per lanciare Google Maps dalla tua app o dal tuo sito web, poiché questi URL universali consentono una gestione più ampia delle richieste di mappe indipendentemente dalla piattaforma in uso. Per le funzionalità che potrebbero essere funzionali solo su una piattaforma mobile (ad esempio la navigazione passo passo), potresti preferire utilizzare un'opzione specifica per la piattaforma per Android o iOS. Consulta la seguente documentazione:
- Google Maps Intents per Android, in particolare per il lancio dell' app Google Maps per Android
- Schema URL di Google Maps per iOS, specifico per lanciare l'app Google Maps per iOS
Avviare Google Maps ed eseguire un'azione specifica
Per avviare Google Maps ed eseguire facoltativamente una delle funzioni supportate, utilizza uno schema URL di uno dei seguenti moduli, a seconda dell'azione richiesta:
- Cerca: avvia una mappa Google che mostra un segnaposto per un luogo specifico oppure esegui una ricerca generale e lancia una mappa per visualizzare i risultati:
https://www.google.com/maps/search/?api=1¶meters
- Indicazioni stradali: richiedi indicazioni stradali e avvia Google Maps con i risultati:
https://www.google.com/maps/dir/?api=1¶meters
- Visualizza una mappa
— avvia Google Maps senza indicatori o indicazioni stradali:
https://www.google.com/maps/@?api=1&map_action=map¶meters
- Visualizza una panoramica in Street View
: avvia un'immagine panoramica interattiva:
https://www.google.com/maps/@?api=1&map_action=pano¶meters
Importante: il parametro api=1
identifica la versione degli URL di Maps a cui è destinato l'URL. Questo parametro è obbligatorio in ogni richiesta. L'unico valore valido è 1. Se api=1
NON è presente nell'URL,
tutti i parametri vengono ignorati e verrà avviata l'app Google Maps predefinita, in un browser o nell'app mobile Google Maps, a seconda della piattaforma in uso
(ad esempio, https://www.google.com/maps).
Creare URL validi
Devi codificare correttamente gli URL.
Ad esempio, alcuni parametri utilizzano un carattere barra verticale (|
) come separatore, che devi codificare come %7C
nell'URL finale. Altri parametri utilizzano valori separati da virgole, ad esempio coordinate di latitudine/longitudine o città, stato. Devi codificare la virgola come %2C
. Codifica gli spazi con
%20
oppure sostituiscili con un segno più (+
).
Inoltre, gli URL sono limitati a 2048 caratteri per ogni richiesta. Tieni presente questo limite quando crei gli URL.
Azioni sulla mappa
Le azioni sulla mappa disponibili sono: ricerca, indicazioni stradali, visualizzazione di una mappa e visualizzazione di una panoramica in Street View. Specifica l'azione nell'URL della richiesta, insieme ai parametri obbligatori e facoltativi. Come standard per gli URL, puoi separare i parametri utilizzando la e commerciale (&
). Per ogni azione, l'elenco dei parametri e i relativi valori possibili sono enumerati nella sezione Parametri di ricerca.
Cerca
L'azione di ricerca mostra i risultati di una ricerca nella regione visibile della mappa. Quando cerchi un luogo specifico, la mappa risultante inserisce un segnaposto in corrispondenza della posizione specificata e mostra i dettagli disponibili sul luogo.
Formare l'URL di ricerca
https://www.google.com/maps/search/?api=1¶meters
Parametri
query
(obbligatorio): definisce i luoghi da evidenziare sulla mappa. Il parametro della query è obbligatorio per tutte le richieste di ricerca.- Specifica le località come nome del luogo, indirizzo o coordinate di latitudine/longitudine separate da virgole. Le stringhe devono essere
con codifica URL, quindi un indirizzo
come "City Hall, New York, NY" deve essere convertito in
City+Hall%2C+New+York%2C+NY
. - Specifica i termini di ricerca generali come stringa con codifica URL, ad esempio
grocery+stores
orestaurants+in+seattle+wa
.
- Specifica le località come nome del luogo, indirizzo o coordinate di latitudine/longitudine separate da virgole. Le stringhe devono essere
con codifica URL, quindi un indirizzo
come "City Hall, New York, NY" deve essere convertito in
query_place_id
(facoltativo): un ID luogo è un identificatore testuale che identifica in modo univoco un luogo. Per l'azionesearch
, devi specificare unquery
, ma puoi anche specificare unquery_place_id
. Se specifichi entrambi i parametri,query
viene utilizzato solo se Google Maps non riesce a trovare l'ID luogo. Se stai cercando di collegarti in modo definitivo a un'attività specifica, l'ID del luogo è la garanzia migliore per consentirti di collegarti alla posizione giusta. Ti consigliamo inoltre di inviare unquery_place_id
quando esegui una query su una località specifica utilizzando le coordinate di latitudine/longitudine.
Esempi di ricerche:
Ricerca di località
Con una ricerca di località, cerchi una località specifica utilizzando il nome di un luogo, un indirizzo o le coordinate di latitudine e longitudine separate da virgole, e la mappa risultante mostra un segnaposto in quel luogo. Questi tre esempi illustrano le ricerche della stessa località, CenturyLink Field (uno stadio a Seattle, WA), utilizzando valori di località diversi.
Esempio 1: la ricerca del nome del luogo "Campo CenturyLink" si traduce nella seguente mappa:
https://www.google.com/maps/search/?api=1&query=centurylink+field
Esempio 2: ricerca del campo CenturyLink utilizzando le coordinate di latitudine/longitudine e i risultati dell'ID del luogo nella seguente mappa:
Esempio 3: ricerca del campo CenturyLink utilizzando solo le coordinate di latitudine e longitudine nella seguente mappa. Nota che sulla mappa è presente un segnaposto, ma non vengono fornite informazioni aggiuntive sul luogo sulla mappa o nel riquadro laterale:
https://www.google.com/maps/search/?api=1&query=47.5951518%2C-122.3316393
Ricerca per categoria
In una ricerca in categorie, passi un termine di ricerca generale e Google Maps
tenta di trovare schede che corrispondono ai tuoi criteri vicino alla località specificata.
Se non viene specificata alcuna posizione, Google Maps tenta di trovare schede nelle vicinanze della tua posizione corrente. Se preferisci fornire una posizione per una ricerca categorica, includi la posizione nella stringa di ricerca generica (ad esempio, pizza+seattle+wa
).
In questo esempio, la ricerca di pizzerie a Seattle, WA, restituisce la seguente mappa:
https://www.google.com/maps/search/?api=1&query=pizza+seattle+wa
Directions
L'azione Indicazioni stradali visualizza il percorso tra due o più punti specificati sulla mappa, nonché la distanza e il tempo di percorrenza.
Forma l'URL delle indicazioni stradali
https://www.google.com/maps/dir/?api=1¶meters
Parametri
origin
: definisce il punto di partenza da cui visualizzare le indicazioni stradali. Il valore predefinito è la posizione di partenza più pertinente, ad esempio la posizione del dispositivo, se disponibile. Se nessuno, la mappa risultante potrebbe fornire un modulo vuoto per consentire a un utente di inserire l'origine. Il valore può essere il nome di un luogo, un indirizzo o coordinate di latitudine/longitudine separate da virgole. Una stringa deve essere con codifica URL, quindi un indirizzo come "City Hall, New York, NY" deve essere convertito inCity+Hall%2C+New+York%2C+NY
.Nota: questo parametro è facoltativo, a meno che non specifichi un
origin_place_id
nell'URL. Se scegli di specificare un valoreorigin_place_id
, devi includere anche unorigin
nell'URL.origin_place_id
(facoltativo): un ID luogo è un identificatore testuale che identifica in modo univoco un luogo. Se stai cercando di specificare in modo definitivo un'attività, l'utilizzo di un ID luogo è la garanzia migliore per il collegamento al luogo giusto. Gli URL che utilizzano questo parametro devono includere anche unorigin
.destination
: definisce l'endpoint delle indicazioni stradali. Se non è presente, la mappa risultante potrebbe fornire un modulo vuoto per consentire all'utente di inserire la destinazione. Il valore può essere il nome di un luogo, un indirizzo o coordinate di latitudine/longitudine separate da virgole. Una stringa deve essere con codifica URL, quindi un indirizzo come "City Hall, New York, NY" deve essere convertito inCity+Hall%2C+New+York%2C+NY
.Nota: questo parametro è facoltativo, a meno che non specifichi un
destination_place_id
nell'URL. Se scegli di specificare un valoredestination_place_id
, devi includere anche undestination
nell'URL.destination_place_id
(facoltativo): un ID luogo è un identificatore testuale che identifica in modo univoco un luogo. Se stai cercando di specificare in modo definitivo un'attività, l'utilizzo di un ID luogo è la garanzia migliore per il collegamento al luogo giusto. Gli URL che utilizzano questo parametro devono includere anche undestination
.travelmode
(facoltativo): definisce il metodo di viaggio. Le opzioni sonodriving
,walking
(che preferisce percorsi pedonali e marciapiedi, se disponibili),bicycling
(che percorsi lungo le piste ciclabili e le strade preferite, se disponibili) otransit
. Setravelmode
non viene specificato, Google Maps mostra una o più delle modalità più pertinenti per il percorso specificato e/o le preferenze utente.dir_action=navigate
(facoltativo): avvia la navigazione passo passo o l'anteprima del percorso verso la destinazione specificata, a seconda della disponibilità dell'origine. Se l'utente specifica un'origine che non è vicina alla posizione attuale dell'utente o se la posizione attuale del dispositivo non è disponibile, la mappa avvia un'anteprima del percorso. Se l'utente non specifica un'origine (in questo caso, per impostazione predefinita l'origine è la posizione attuale del dispositivo) o se l'origine è vicina alla posizione attuale dell'utente, la mappa avvia la navigazione passo passo. Tieni presente che la navigazione non è disponibile in tutti i prodotti Google Maps e/o tra tutte le destinazioni; in questi casi, questo parametro verrà ignorato.waypoints
: specifica uno o più luoghi intermedi da cui indirizzare le indicazioni traorigin
edestination
. È possibile specificare più tappe utilizzando il carattere barra verticale (|
) per separare i luoghi (ad esempio,Berlin,Germany|Paris,France
). Il numero di waypoint consentiti varia a seconda della piattaforma in cui viene aperto il link, con un massimo di tre tappe supportate sui browser mobile, altrimenti è supportato un massimo di nove tappe. I waypoint vengono visualizzati sulla mappa nello stesso ordine in cui sono elencati nell'URL. Ogni waypoint può essere un nome di luogo, un indirizzo o coordinate di latitudine/longitudine separate da virgole. Le stringhe devono essere con codifica URL, quindi i waypoint come "Berlino,Germania|Parigi,Francia" devono essere convertiti inBerlin%2CGermany%7CParis%2CFrance
.Note
- I Waypoint non sono supportati in tutti i prodotti Google Maps; in questi casi questo parametro verrà ignorato.
- Questo parametro è facoltativo, a meno che non specifichi
waypoint_place_ids
nell'URL. Se scegli di specificarewaypoint_place_ids
, devi includere anchewaypoints
nell'URL.
waypoint_place_ids
(facoltativo): un ID luogo è un identificatore testuale che identifica in modo univoco un luogo.Waypoint_place_ids
ti consente di fornire un elenco di ID luogo corrispondenti all'elenco diwaypoints
. Gli ID luogo devono essere elencati nello stesso ordine dei waypoint e devono essere separati dalla barra verticale "|
" ( con codifica URL come%7C
). Se stai cercando di specificare in modo definitivo alcune strutture, gli ID luogo sono la soluzione migliore per collegare le sedi giuste. Gli URL che utilizzano questo parametro devono includere anchewaypoints
.avoid
(facoltativo): imposta le funzionalità che la route dovrebbe cercare di evitare. Può essere impostato su una o più di queste opzioni, separate da una virgola ",
" ( con codifica URL come%2C
):ferries
highways
tolls
Esempi di indicazioni stradali
Il seguente URL avvia una mappa in modalità Indicazioni stradali e fornisce un modulo per consentire all'utente di inserire il luogo di partenza e di destinazione.
https://www.google.com/maps/dir/?api=1
L'esempio seguente lancia una mappa con indicazioni in bicicletta dallo Space Needle al Pike Place Market, a Seattle, WA.
L'esempio seguente avvia una mappa con indicazioni a piedi da Google a Sydney, Australia, al Queen Victoria Building.
Visualizzazione di una mappa
L'azione sulla mappa restituisce una mappa senza indicatori o indicazioni stradali.
Formare l'URL della mappa
https://www.google.com/maps/@?api=1&map_action=map¶meters
Parametri
map_action=map
(obbligatorio): specifica il tipo di visualizzazione della mappa da mostrare. Maps e Street View condividono lo stesso endpoint. Per garantire la visualizzazione di una mappa,map_action
deve essere specificato comemap
.center
(facoltativo): definisce il centro della finestra della mappa e accetta le coordinate di latitudine/longitudine come valori separati da virgole (ad esempio-33.8569,151.2152
).zoom
(facoltativo): imposta il livello di zoom iniziale della mappa. I valori accettati sono numeri interi interi che vanno da 0 (tutto il mondo) a 21 (singoli edifici). Il limite massimo può variare a seconda dei dati della mappa disponibili nella posizione selezionata. Il valore predefinito è 15.basemap
(facoltativo): definisce il tipo di mappa da visualizzare. Il valore può essereroadmap
(predefinito),satellite
oterrain
.layer
(facoltativo): definisce un livello aggiuntivo da visualizzare sulla mappa, se disponibile. Il valore può essere uno dei seguenti:none
(predefinito),transit
,traffic
obicycling
.
Esempi di mappe
Questo URL di esempio avvia una mappa Google predefinita, centrata sulla posizione corrente dell'utente.
https://www.google.com/maps/@?api=1&map_action=map
L'esempio seguente mostra una mappa centrata su Katoomba, Nuovo Galles del Sud, Australia (all'indirizzo -33.712206,150.311941
) e imposta i parametri facoltativi zoom
e basemap
.
Visualizzazione di una panoramica in Street View
L'azione della panoramica consente di avviare un visualizzatore per visualizzare le immagini di Street View come panoramiche interattive. Ogni panoramica in Street View offre una visione completa a 360 gradi da un'unica posizione. Le immagini contengono una vista orizzontale a 360 gradi (tutto a capo) e 180 gradi di vista verticale (dal dritto verso l'alto verso il basso). L'azione del panorama avvia un visualizzatore che esegue il rendering della panoramica risultante come una sfera con una fotocamera al centro. Puoi manipolare la fotocamera per controllare lo zoom e l'orientamento.
Google Street View offre viste panoramiche da luoghi designati in tutta la sua area di copertura. Sono inoltre disponibili foto sferiche fornite dagli utenti e collezioni speciali di Street View.
Creazione dell'URL di Street View
https://www.google.com/maps/@?api=1&map_action=pano¶meters
Parametri
map_action=pano
(obbligatorio): specifica il tipo di visualizzazione da mostrare. Maps e Street View condividono lo stesso endpoint. Per garantire la visualizzazione di una panoramica,action
deve essere specificato comepano
.
È richiesto anche uno dei seguenti parametri URL:
viewpoint
: lo spettatore visualizza la panoramica fotografata più vicina alla localitàviewpoint
, specificata come coordinate di latitudine/longitudine separate da virgole (ad esempio 46.414382,10.013988). Poiché le immagini di Street View vengono aggiornate periodicamente e le fotografie possono essere scattate da posizioni leggermente diverse ogni volta, è possibile che la posizione della tua posizione venga agganciata a una panoramica diversa quando le immagini vengono aggiornate.pano
: l'ID panorama specifico dell'immagine da visualizzare. Se specifichi unpano
, puoi anche specificare unviewpoint
. Ilviewpoint
viene utilizzato solo se Google Maps non riesce a trovare l'ID panorama. Sepano
viene specificato ma non trovato eviewpoint
NON viene specificato, non viene visualizzata alcuna immagine panoramica. Google Maps si apre in modalità predefinita e mostra una mappa centrata sulla posizione corrente dell'utente.
I seguenti parametri URL sono facoltativi:
heading
: indica l'orientamento della fotocamera in gradi in senso orario da nord. I valori accettati sono compresi tra -180 e 360 gradi. Se omesso, viene scelta un'intestazione predefinita in base al punto di vista (se specificato) della query e alla posizione effettiva dell'immagine.pitch
: specifica l'angolazione, verso l'alto o verso il basso, della videocamera. L'inclinazione viene specificata in gradi da -90 a 90. I valori positivi determinano l'angolazione della videocamera verso l'alto, mentre i valori negativi la abbassano. Il tono predefinito pari a 0 viene impostato in base alla posizione della fotocamera quando è stata acquisita l'immagine. Per questo motivo, spesso, ma non sempre, un passo pari a 0 è orizzontale. Ad esempio, un'immagine scattata su una collina probabilmente avrà un'inclinazione predefinita non orizzontale.fov
: determina il campo visivo orizzontale dell'immagine. Il campo visivo è espresso in gradi, con un intervallo compreso tra 10 e 100. Il valore predefinito è 90. In un'area visibile di dimensioni fisse, il campo visivo è considerato il livello di zoom, con numeri più piccoli che indicano un livello di zoom più elevato.
Esempi di Street View
I primi due esempi mostrano un panorama della Torre Eiffel. L'esempio 1 utilizza solo viewpoint
per la località e imposta i parametri facoltativi heading
, pitch
e fov
. Per fare un confronto, nell'esempio 2 vengono utilizzati un ID pano
e lo stesso set di parametri nel primo esempio. Il terzo esempio mostra un'immagine panoramica di interni.
Esempio 1: utilizza solo un valore viewpoint
per specificare la località.
Esempio 2: utilizza un ID pano
e una località viewpoint
.
L'ID pano
ha la precedenza sull'ID viewpoint
.
In questo esempio viene trovato l'ID panoramica, quindi viewpoint
viene ignorato. Tieni presente che l'immagine panoramica visualizzata per l'ID pano
è leggermente diversa e più recente, rispetto all'immagine trovata utilizzando solo l'elemento viewpoint
.
Esempio 3: mostra una panoramica degli interni del ristorante Sarastro a Londra, Regno Unito, specificato con un ID panoramica.
https://www.google.com/maps/@?api=1&map_action=pano&pano=4U-oRQCNsC6u7r8gp02sLA
Individuazione di un ID panoramica
Per trovare l'ID di una specifica immagine panoramica, puoi utilizzare diversi metodi.
- Per JavaScript, utilizza la classe StreetViewPanorama.
- Per Android, utilizza la classe pubblica StreetViewPanoramaLocation.
- Per iOS, utilizza la classe GMSPanorama.
- Puoi anche effettuare richieste di metadati utilizzando l'API Google Street View Image. Le richieste di metadati delle immagini forniscono dati sulle panoramiche di Street View, incluso l'ID panoramica.
Altri esempi
Esempi di indicazioni stradali che utilizzano i waypoint
Gli esempi di indicazioni stradali riportati di seguito mostrano le indicazioni stradali da Parigi, Francia a Cherbourg, in Francia, seguendo i seguenti waypoint:
Città e paese | Nome luogo | ID luogo |
---|---|---|
1. Versailles, Francia | La Reggia di Versailles | ChIJdUyx15R95kcRj85ZX8H8OAU |
2. Chartres, Francia | Cattedrale di Chartres | ChIJKzGHdEgM5EcR_OBTT3nQoEA |
3. Le Mans, Francia | Cattedrale di San Giuliano di Le Mans | ChIJG2LvQNCI4kcRKXNoAsPi1Mc |
4. Caen, Francia | Castello di Caen | ChIJ06tnGbxCCkgRsfNjEQMwUsc |
Negli URL di esempio, i waypoint sono definiti in modi diversi per consentirti di confrontare le differenze nella visualizzazione dei waypoint sulle mappe risultanti.
Esempio 1: Waypoint definiti come città, paese:
Esempio 2: Waypoint definiti come nomi di luoghi specifici:
Esempio 3: Waypoint definiti come città, paese e fornisce anche
waypoint_place_ids
per una struttura specifica in ogni waypoint:
Esempio 4: definisce i waypoint come città e paese, ma elenca i waypoint in un ordine diverso rispetto agli esempi precedenti. Dimostra che la mappa visualizza i waypoint nell'ordine in cui sono elencati nell'URL.
Esempi di mappe
Mostra una mappa con un valore basemap
(satellite) e
layer
(trasporto pubblico) specificati.
Esempi di Street View
Mostra una panoramica in Street View utilizzando una chiave immagine FIFE come ID pano
. Tieni presente che l'ID pano
è preceduto da F:.