Inizia

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:

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&parameters
  • Indicazioni stradali: richiedi indicazioni stradali e avvia Google Maps con i risultati:
    https://www.google.com/maps/dir/?api=1&parameters
  • Visualizza una mappa — avvia Google Maps senza indicatori o indicazioni stradali:
    https://www.google.com/maps/@?api=1&map_action=map&parameters
  • Visualizza una panoramica in Street View : avvia un'immagine panoramica interattiva:
    https://www.google.com/maps/@?api=1&map_action=pano&parameters

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&parameters

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 o restaurants+in+seattle+wa.
  • query_place_id (facoltativo): un ID luogo è un identificatore testuale che identifica in modo univoco un luogo. Per l'azione search, devi specificare un query, ma puoi anche specificare un query_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 un query_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:

https://www.google.com/maps/search/?api=1&query=47.5951518%2C-122.3316393&query_place_id=ChIJKxjxuaNqkFQR3CK6O1HNNqY

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&parameters

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 in City+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 valore origin_place_id, devi includere anche un origin 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 un origin.
  • 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 in City+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 valore destination_place_id, devi includere anche un destination 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 un destination.
  • travelmode (facoltativo): definisce il metodo di viaggio. Le opzioni sono driving, walking (che preferisce percorsi pedonali e marciapiedi, se disponibili), bicycling (che percorsi lungo le piste ciclabili e le strade preferite, se disponibili) o transit. Se travelmode 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 tra origin e destination. È 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 in Berlin%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 specificare waypoint_place_ids, devi includere anche waypoints 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 di waypoints. 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 anche waypoints.
  • 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.

https://www.google.com/maps/dir/?api=1&origin=Space+Needle+Seattle+WA&destination=Pike+Place+Market+Seattle+WA&travelmode=bicycling

L'esempio seguente avvia una mappa con indicazioni a piedi da Google a Sydney, Australia, al Queen Victoria Building.

https://www.google.com/maps/dir/?api=1&origin=Google+Pyrmont+NSW&destination=QVB&destination_place_id=ChIJISz8NjyuEmsRFTQ9Iw7Ear8&travelmode=walking

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&parameters

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 come map.
  • 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ò essere roadmap (predefinito), satellite o terrain.
  • layer (facoltativo): definisce un livello aggiuntivo da visualizzare sulla mappa, se disponibile. Il valore può essere uno dei seguenti: none (predefinito), transit, traffic o bicycling.

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.

https://www.google.com/maps/@?api=1&map_action=map&center=-33.712206%2C150.311941&zoom=12&basemap=terrain

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&parameters

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 come pano.

È 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 un pano, puoi anche specificare un viewpoint. Il viewpoint viene utilizzato solo se Google Maps non riesce a trovare l'ID panorama. Se pano viene specificato ma non trovato e viewpoint 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à.

https://www.google.com/maps/@?api=1&map_action=pano&viewpoint=48.857832%2C2.295226&heading=-45&pitch=38&fov=80

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.

https://www.google.com/maps/@?api=1&map_action=pano&pano=tu510ie_z4ptBZYo2BGEJg&viewpoint=48.857832%2C2.295226&heading=-45&pitch=38&fov=80

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.

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 paeseNome luogoID 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:

https://www.google.com/maps/dir/?api=1&origin=Paris%2CFrance&destination=Cherbourg%2CFrance&travelmode=driving&waypoints=Versailles%2CFrance%7CChartres%2CFrance%7CLe+Mans%2CFrance%7CCaen%2CFrance

Esempio 2: Waypoint definiti come nomi di luoghi specifici:

https://www.google.com/maps/dir/?api=1&origin=Paris%2CFrance&destination=Cherbourg%2CFrance&travelmode=driving&waypoints=Palace+of+Versailles%7CChartres+Cathedral%7CCathedral+of+Saint+Julian+of+Le+Mans%7CCaen+Castle

Esempio 3: Waypoint definiti come città, paese e fornisce anche waypoint_place_ids per una struttura specifica in ogni waypoint:

https://www.google.com/maps/dir/?api=1&origin=Paris%2CFrance&destination=Cherbourg%2CFrance&travelmode=driving&waypoints=Versailles%2CFrance%7CChartres%2CFrance%7CLe+Mans%2CFrance%7CCaen%2CFrance&waypoint_place_ids=ChIJdUyx15R95kcRj85ZX8H8OAU%7CChIJKzGHdEgM5EcR_OBTT3nQoEA%7CChIJG2LvQNCI4kcRKXNoAsPi1Mc%7CChIJ06tnGbxCCkgRsfNjEQMwUsc

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.

https://www.google.com/maps/dir/?api=1&origin=Paris%2CFrance&destination=Cherbourg%2CFrance&travelmode=driving&waypoints=Versailles%2CFrance%7CCaen%2CFrance%7CLe+Mans%2CFrance%7CChartres%2CFrance

Esempi di mappe

Mostra una mappa con un valore basemap (satellite) e layer (trasporto pubblico) specificati.

https://www.google.com/maps/@?api=1&map_action=map&center=37.7992940%2C-122.3976113&zoom=15&basemap=satellite&layer=transit

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:.

https://www.google.com/maps/@?api=1&map_action=pano&pano=F:-ud6AZSB-sQg/V0cfCSV3OWI/AAAAAAAAG1U/UQEoc5sXPQEIP7zzD6SWzmKb8Vbug47uQCLIB&heading=22&pitch=-5&fov=55