Per iniziare

Introduzione

Con gli URL di Maps, puoi creare un URL universale per più piattaforme per avviare Google Maps ed eseguire ricerche, ricevere indicazioni stradali e navigare, nonché visualizzare visualizzazioni di mappe e immagini panoramiche. La sintassi dell'URL è la stessa, indipendentemente dalla piattaforma in uso.

Non è necessaria una chiave API di Google per utilizzare gli URL di Maps.

Sintassi multipiattaforma universale

In qualità di sviluppatore di un'app per Android, per iOS o per un sito web, puoi creare un URL comune che aprirà Google Maps ed eseguirà l'azione richiesta, indipendentemente dalla piattaforma in uso quando la mappa viene aperta.

  • Su un dispositivo Android:
    • Se l' app Google Maps per Android è installata e attiva, l'URL avvia Google Maps nell'app Maps 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 Maps 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 avviare 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 funzionanti solo su una piattaforma mobile (ad esempio, la navigazione passo passo), potreste preferire un'opzione specifica della piattaforma per Android o iOS. Consulta la seguente documentazione:

Avvio di Google Maps ed esecuzione di un'azione specifica

Per avviare Google Maps ed eseguire facoltativamente una delle funzioni supportate, utilizza uno schema URL in uno dei seguenti formati, a seconda dell'azione richiesta:

  • Cerca: lancia una mappa Google che mostra un segnaposto per un luogo specifico oppure esegui una ricerca generale e avvia 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
  • Visualizzare una mappa: avvia Google Maps senza indicatori o indicazioni stradali:
    https://www.google.com/maps/@?api=1&map_action=map&parameters
  • Visualizza un panorama di Street View: lancia 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 questo 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 l'app Google Maps predefinita viene avviata in un browser o nell'app per dispositivi mobili 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 una barra verticale (|) come separatore, che devi codificare come %7C nell'URL finale. Altri parametri utilizzano valori separati da virgola, come coordinate di latitudine/longitudine o città, stato. Devi codificare la virgola come %2C. Codifica gli spazi con %20 o 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 disponibili per la mappa sono: ricerca, indicazioni stradali, visualizzazione di una mappa e visualizzazione di una panoramica di Street View. Specifica l'azione nell'URL della richiesta, insieme ai parametri obbligatori e facoltativi. Come avviene negli URL, separa i parametri utilizzando la e commerciale (&). Per ogni azione, l'elenco dei parametri e i relativi valori possibili sono elencati nella sezione Parametri di ricerca.

Cerca

L'azione di ricerca mostra i risultati di una ricerca nell'area della mappa visibile. Quando cerchi un luogo specifico, la mappa risultante inserisce un segnaposto nella località specificata e mostra i dettagli del luogo disponibile.

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 di ricerca è obbligatorio per tutte le richieste di ricerca.
    • Specifica le località con il nome del luogo, l'indirizzo o le coordinate di latitudine/longitudine separate da virgole. Le stringhe devono essere codificate da 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.
  • (Facoltativo) query_place_id: 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 stabilire un collegamento definitivo a una struttura specifica, l'ID luogo è la miglior garanzia di creare un link al luogo giusto. È inoltre consigliabile inviare un query_place_id quando si cerca una località specifica utilizzando le coordinate di latitudine/longitudine.

Esempi di ricerche:

Ricerca di località

In una ricerca di località, cerchi una località specifica utilizzando un nome, un indirizzo o coordinate di latitudine/longitudine separate da virgole e la mappa risultante mostra un segnaposto in tale località. Questi tre esempi illustrano le ricerche per la stessa località, il CenturyLink Field (uno stadio sportivo a Seattle, WA), utilizzando valori di località diversi.

Esempio 1: la ricerca del nome del luogo "CenturyLink Field" restituisce la seguente mappa:

https://www.google.com/maps/search/?api=1&query=centurylink+field

Esempio 2: la ricerca del campo CenturyLink utilizzando le coordinate di latitudine/longitudine e l'ID luogo risulta nella seguente mappa:

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

Esempio 3: la ricerca del campo CenturyLink utilizzando solo le coordinate di latitudine/longitudine restituisce la seguente mappa. Tieni presente che sulla mappa è presente un segnaposto, ma non vengono fornite informazioni aggiuntive sul luogo o nel riquadro laterale:

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

Ricerca categoriale

In una ricerca per categoria, passi un termine di ricerca generale e Google Maps tenta di trovare schede che corrispondono ai tuoi criteri vicino alla località da te specificata. Se non viene specificata alcuna località, Google Maps tenta di trovare schede di attività commerciali nelle vicinanze della tua posizione attuale. Se preferisci indicare una località per una ricerca categorica, includi la posizione nella stringa della ricerca generale (ad esempio pizza+seattle+wa).

In questo esempio, la ricerca di pizzerie a Seattle, WA mostra la seguente mappa:

https://www.google.com/maps/search/?api=1&query=pizza+seattle+wa


Directions

L'azione Indicazioni stradali mostra il percorso tra due o più punti specificati sulla mappa, nonché la distanza e il tempo di percorrenza.

Formare l'URL di 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 località iniziale più pertinente, ad esempio la località dell'utente, se disponibile. In caso contrario, la mappa risultante potrebbe fornire un modulo vuoto per consentire all'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 valore origin_place_id nell'URL. Se scegli di specificare origin_place_id, devi includere anche un origin nell'URL.

  • (Facoltativo) origin_place_id: un ID luogo è un identificatore testuale che identifica in modo univoco un luogo. Se stai tentando di specificare in modo definitivo una struttura, l'utilizzo di un ID luogo è la migliore garanzia di collegamento alla sede giusta. Gli URL che utilizzano questo parametro devono includere anche origin.
  • destination: definisce l'endpoint delle indicazioni stradali. In caso contrario, 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 destination_place_id, devi includere anche un destination nell'URL.

  • (Facoltativo) destination_place_id: un ID luogo è un identificatore testuale che identifica in modo univoco un luogo. Se stai tentando di specificare in modo definitivo una struttura, l'utilizzo di un ID luogo è la migliore garanzia di collegamento alla sede giusta. Gli URL che utilizzano questo parametro devono includere anche destination.
  • (Facoltativo) travelmode: definisce il metodo di viaggio. Le opzioni sono driving, walking (che preferisce percorsi pedonali e marciapiedi, dove disponibili), bicycling (che includono percorsi ciclabili e strade preferite, se disponibili) oppure transit. Se travelmode non è specificato, Google Maps mostra una o più delle modalità più pertinenti per il percorso specificato e/o le preferenze dell'utente.
  • (Facoltativo) dir_action=navigate: avvia la navigazione passo passo o l'anteprima del percorso verso la destinazione specificata, in base alla disponibilità dell'origine. Se l'utente specifica un'origine e non si trova vicino alla posizione attuale dell'utente o se la sua posizione attuale non è disponibile, la mappa avvia un'anteprima del percorso. Se l'utente non specifica un'origine (in questo caso l'origine predefinita sulla posizione attuale dell'utente) o l'origine si trova vicino 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 per la routing delle indicazioni stradali tra origin e destination. È possibile specificare più tappe utilizzando la barra verticale (|) per separare i luoghi (ad esempio, Berlin,Germany|Paris,France). Il numero di tappe consentito varia in base alla piattaforma in cui si apre il link, con un massimo di tre tappe supportate nei browser mobile e un massimo di nove tappe supportate altrimenti. I tappe vengono visualizzati sulla mappa nello stesso ordine in cui sono elencati nell'URL. Ogni punto di via può essere un nome di luogo, un indirizzo o coordinate di latitudine/longitudine separate da virgole. Le stringhe devono essere codificate nell'URL, quindi i tappe come "Berlino,Germania|Parigi,Francia" devono essere convertite in Berlin%2CGermany%7CParis%2CFrance.

    Note

    • I tappe non sono supportati su 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.
  • (Facoltativo) waypoint_place_ids: un ID luogo è un identificatore testuale che identifica in modo univoco un luogo. Waypoint_place_ids consente di fornire un elenco di ID luogo corrispondente all'elenco di waypoints. Gli ID luogo devono essere elencati nello stesso ordine dei tappe e separati tramite il carattere barra verticale "|" (codificato in URL come %7C). Se stai cercando di specificare definitivamente determinati luoghi, gli ID luogo sono la miglior garanzia di collegamento ai luoghi giusti. Gli URL che utilizzano questo parametro devono includere anche waypoints.

Esempi di indicazioni stradali

L'URL seguente avvia una mappa in modalità indicazioni stradali e fornisce un modulo per consentire all'utente di inserire l'origine e la destinazione.

https://www.google.com/maps/dir/?api=1

L'esempio seguente avvia una mappa con indicazioni in bicicletta dallo Space Needle a Pike Place Market, a Seattle, in 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, in 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 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 mappa da visualizzare. Maps e Street View condividono lo stesso endpoint. Per mostrare una mappa, è necessario specificare map_action come map.
  • (Facoltativo) center: definisce il centro della finestra della mappa e accetta le coordinate di latitudine/longitudine come valori separati da virgola (ad esempio -33.8569,151.2152).
  • (Facoltativo) zoom: imposta il livello di zoom iniziale della mappa. I valori accettati sono numeri interi interi compresi tra 0 (tutto il mondo) e 21 (singoli edifici). Il limite massimo può variare a seconda dei dati della mappa disponibili nella località selezionata. Il valore predefinito è 15.
  • (Facoltativo) basemap: definisce il tipo di mappa da visualizzare. Il valore può essere roadmap (predefinito), satellite o terrain.
  • (Facoltativo) layer: definisce un livello aggiuntivo da visualizzare sulla mappa, se presente. 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, NSW, 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 di Street View

Con l'azione panoramica puoi lanciare un visualizzatore per mostrare immagini di Street View sotto forma di panoramiche interattive. Ogni panorama di Street View offre una visualizzazione completa a 360 gradi da un'unica posizione. Le immagini contengono una vista orizzontale a 360° (a tutto tondo) e 180° in verticale (dall'alto verso il basso fino al dritto verso il basso). L'azione panoramica avvia un visualizzatore che esegue il rendering del panorama risultante come una sfera con una fotocamera al centro. Puoi controllare la videocamera per controllare lo zoom e l'orientamento.

Google Street View offre viste panoramiche dei luoghi designati in tutta la sua area di copertura. Sono disponibili anche foto sferiche fornite dagli utenti e raccolte speciali di Street View.

Formare l'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 visualizzare. Maps e Street View condividono lo stesso endpoint. Per mostrare un panorama, action deve essere specificato come pano.

È inoltre necessario uno dei seguenti parametri URL:

  • viewpoint: il visualizzatore mostra il panorama fotografato più vicino alla località viewpoint, specificato come coordinate separate da virgole/longitudine (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 tua posizione venga agganciata a un panorama diverso quando le immagini vengono aggiornate.
  • pano: l'ID panoramica specifico dell'immagine da visualizzare. Se specifichi un pano, puoi anche specificare un viewpoint. viewpoint viene utilizzato solo se Google Maps non riesce a trovare l'ID panoramica. Se pano è specificato ma non trovato e viewpoint è NOT specificato, non viene visualizzata alcuna immagine panoramica. Infatti, Google Maps si apre in modalità predefinita e mostra una mappa incentrata sulla posizione attuale dell'utente.

I seguenti parametri URL sono facoltativi:

  • heading: indica l'intestazione della bussola in gradi in senso orario da nord. I valori accettati sono compresi tra -180 e 360 gradi. Se omessa, viene scelta un'intestazione predefinita in base al punto di vista (se specificato) della query e alla posizione effettiva dell'immagine.
  • pitch: consente di specificare l'angolazione, verso l'alto o verso il basso, della videocamera. Il tono è specificato in gradi da -90 a 90. Se si positivi, la posizione della videocamera è verso l'alto, mentre i valori negativi la inclinano verso il basso. Il tono predefinito è 0 in base alla posizione della fotocamera al momento dell'acquisizione dell'immagine. Per questo motivo, spesso una tonalità pari a 0 è orizzontale, ma non sempre. Ad esempio, un'immagine scattata su una collina mostrerà probabilmente un tono predefinito 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. Quando si tratta di un'area visibile con dimensioni fisse, il campo visivo è considerato a 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 utilizza solo viewpoint per la località e imposta i parametri facoltativi heading, pitch e fov. Per fare un confronto, l'esempio due utilizza un ID pano e gli stessi parametri impostati nel primo esempio. Il terzo esempio mostra un'immagine panoramica di interni.

Esempio 1: utilizza solo 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 posizione viewpoint. L'ID pano ha la precedenza su viewpoint. In questo esempio, l'ID panorama è trovato, pertanto viewpoint viene ignorato. Nota che l'immagine panoramica visualizzata per l'ID pano è leggermente diversa e più recente rispetto all'immagine trovata utilizzando solo 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 un panorama degli interni del ristorante Sarastro a Londra, Regno Unito, specificato con un ID panorama.

https://www.google.com/maps/@?api=1&map_action=pano&pano=4U-oRQCNsC6u7r8gp02sLA

Trovare un ID panorama

Per trovare l'ID di un'immagine panoramica specifica, puoi utilizzare più metodi.

Altri esempi

Esempi di indicazioni stradali utilizzando i tappe

Gli esempi di indicazioni seguenti illustrano l'avvio di Google Maps e la visualizzazione delle indicazioni stradali da Parigi, Francia a Cherbourg, in Francia, con i seguenti percorsi:

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 punti di via sono definiti in modi diversi per consentirti di confrontare le differenze nella visualizzazione dei tappe nelle 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 che forniscono 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 tappe come città, paese, ma elenca i tappe in un ordine diverso rispetto agli esempi precedenti. Dimostra che la mappa mostra tappe 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

Visualizza una mappa con i valori basemap (satellite) e layer (transit) 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 di 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