Nel mondo attuale, in cui la posizione è un elemento fondamentale, gli utenti si aspettano un accesso semplice a informazioni sui luoghi, indicazioni stradali e navigazione. Che si tratti di un'app di messaggistica, di un'app di scoperta del contesto locale, di una piattaforma di logistica e trasporti, di un pianificatore di viaggi o di una piattaforma di annunci immobiliari, gli utenti spesso hanno bisogno di visualizzare rapidamente i dettagli della posizione o trovare il percorso migliore da A a B. Gli sviluppatori possono creare la propria esperienza in-app, ma sfruttare l'interfaccia completa e familiare di Google Maps offre un'esperienza superiore.
Un URL di Google Maps ben strutturato è essenziale per un'esperienza utente ottimale. Gli URL errati compromettono questa esperienza, indirizzando gli utenti alla posizione sbagliata, mostrando una visualizzazione generica della mappa anziché dettagli specifici o addirittura causando un link non funzionante. Ciò frustra gli utenti e impedisce loro di raggiungere il loro obiettivo. Ad esempio, anche con un URL di Maps valido, un utente che si aspetta dettagli su un'attività specifica potrebbe invece visualizzare una mappa generica senza informazioni pertinenti. Di seguito abbiamo riportato un esempio:
https://www.google.com/maps/search/?api=1&query=-33.8567%2C151.2152
Questo URL di Maps è valido per aprire Google Maps e visualizzare una posizione in base a latitudine e longitudine. Tuttavia, non fornisce agli utenti dettagli su un luogo specifico.
Collegare facilmente la tua applicazione a Google Maps tramite URL accurati
Google Maps Platform (GMP) offre due metodi principali per creare URL accurati: l'API Places(nuova), che richiede una chiave API, e gli URL di Maps, che sono senza costi e non richiedono una chiave. Le seguenti soluzioni riguardano diversi scenari e casi d'uso:
Utilizzo del campo googleMapsUri o googleMapsLinks dell'API GMP Places(novità)
L'API GMP Places(nuova) restituisce un insieme completo di informazioni su un luogo specifico. Quando richiedi il campo googleMapsUri o googleMapsLinks
(specificandolo nella maschera del campo), la risposta dell'API include un oggetto luogo.
Questo oggetto contiene URL preformattati, che possono essere utilizzati per aprire direttamente la visualizzazione corrispondente, ad esempio la visualizzazione dei dettagli del luogo, in Google Maps.
Esempio:
Richiesta Place Details
curl -X GET -H 'Content-Type: application/json' \ -H "X-Goog-Api-Key: YOUR_API_KEY" \ -H "X-Goog-FieldMask: googleMapsUri,googleMapsLinks" \ https://places.googleapis.com/v1/places/ChIJ3S-JXmauEmsRUcIaWtf4MzE
Risposta di Place Details:
{
"googleMapsUri": "https://maps.google.com/?cid=3545450935484072529",
"googleMapsLinks": {
"directionsUri": "https://www.google.com/maps/dir//''/data=!4m7!4m6!1m1!4e2!1m2!1m1!1s0x6b12ae665e892fdd:0x3133f8d75a1ac251!3e0",
"placeUri": "https://maps.google.com/?cid=3545450935484072529",
"writeAReviewUri": "https://www.google.com/maps/place//data=!4m3!3m2!1s0x6b12ae665e892fdd:0x3133f8d75a1ac251!12e1",
"reviewsUri": "https://www.google.com/maps/place//data=!4m4!3m3!1s0x6b12ae665e892fdd:0x3133f8d75a1ac251!9m1!1b1",
"photosUri": "https://www.google.com/maps/place//data=!4m3!3m2!1s0x6b12ae665e892fdd:0x3133f8d75a1ac251!10e5"
}
}ChIJ3S-JXmauEmsRUcIaWtf4MzE nell'esempio riportato sopra è l'ID luogo della Sydney Opera House. Un ID luogo è un identificatore testuale che identifica in modo univoco un luogo nel database di Google Places e su Google Maps.
Recupero degli ID luogo senza costi
Per recuperare gli ID luogo in modo programmatico, puoi utilizzare la funzionalità API Places: Text Search(solo ID). Questo è un metodo senza costi per ottenere gli ID luogo. Scopri di più sull'ID luogo e sulla richiesta dell'API Place(nuova).
Richiesta di ricerca di testo dell'API Places(solo ID):
curl -X POST -d '{"textQuery" : "Sydney Opera House"}' \
-H 'Content-Type: application/json' -H 'X-Goog-Api-Key: YOUR_API_KEY' \
-H 'X-Goog-FieldMask: places.id' \
'https://places.googleapis.com/v1/places:searchText'Risposta di Places API Text Search(solo ID):
{
"places": [
{
"id": "ChIJ3S-JXmauEmsRUcIaWtf4MzE"
}
]
}Gli ID luogo possono essere recuperati anche quando un utente fa clic o tocca un PDI sulle mappe. Scopri di più sulle icone dei PDI cliccabili(JavaScript, Android, iOS).
Implementazione
Quando utilizzano l'API Places, gli sviluppatori possono semplicemente estrarre il campo googleMapsUri o googleMapsLinks dalla risposta e utilizzarlo per avviare la visualizzazione corrispondente nell'app Google Maps o in un browser se l'app non è installata.
| Funzionalità | Descrizione |
|---|---|
| directionsUri | Link per aprire Google Maps e visualizzare le indicazioni stradali dalla posizione attuale dell'utente a questo luogo |
| placeUri | Link per aprire Google Maps alla pagina dei dettagli di questo luogo |
| writeAReviewUri | Link per aprire Google Maps nella pagina di scrittura delle recensioni per questo luogo |
| reviewsUri | Link per aprire Google Maps alla pagina delle recensioni di questo luogo |
| photosUri | Link per aprire Google Maps alla pagina delle foto di questo luogo |
Consulta le indicazioni per gli sviluppatori e prova subito la funzionalità.
Utilizzare gli URL di Maps
Utilizzando gli URL di Maps, puoi creare un URL universale e multipiattaforma per avviare Google Maps ed eseguire ricerche, ottenere indicazioni stradali e navigazione e visualizzare viste della mappa 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.
Le azioni disponibili per la mappa sono:
La funzione di ricerca avvia un'app Google Maps o un browser se l'app non è installata, che mostra un segnaposto per un luogo specifico o esegue una ricerca generale e avvia una mappa per visualizzare i risultati.
La funzione Indicazioni stradali avvia un'app Google Maps o un browser se l'app non è installata, che mostra le indicazioni stradali tra i punti o attiva la navigazione passo passo su Google Maps per i dispositivi mobili.
La funzione di panoramica Street View ti consente di avviare un visualizzatore per mostrare le immagini di Street View come panoramiche interattive.
Visita la documentazione per sviluppatori sugli URL di GMP Maps per esplorare altre funzioni ed esempi.
Di seguito analizziamo due funzionalità chiave degli URL di Maps:
Visualizzazione dei dettagli del luogo su Google Maps:questa sezione spiega come costruire URL che mostrino i dettagli di una posizione specifica su Google Maps. Inoltre, spiega in dettaglio come lavorare con i luoghi che hanno nomi non univoci utilizzando gli ID luogo e le query precise.
Fornire indicazioni stradali utilizzando gli URL di Maps:questa sezione spiega come creare URL che forniscono indicazioni stradali tra località, incluse indicazioni con più tappe e navigazione passo passo.
Visualizzazione dei dettagli dei luoghi su Google Maps
La funzione di ricerca richiede due parametri per completare la ricerca di luoghi, ovvero query(obbligatorio) e query_place_id(facoltativo).
Il parametro query è obbligatorio per tutte le richieste di ricerca. Accetta un nome di luogo, coordinate di latitudine/longitudine separate da virgole o un termine di ricerca generico.
Struttura dell'URL di ricerca:
https://www.google.com/maps/search/?api=1¶meters
Scenario 1: visualizzazione dei dettagli del luogo per un nome univoco
https://www.google.com/maps/search/?api=1&query=Sydney%20Opera%20House
Ora considera un luogo con un nome non univoco. Cosa succede quando esegui una ricerca solo in base a questo nome non univoco? Vedi lo scenario successivo.
Scenario 2: cerca luoghi con un nome non univoco
https://www.google.com/maps/search/?api=1&query=7-Eleven
Poiché il nome del luogo non è univoco, questo URL apre un elenco di sedi 7-Eleven nelle vicinanze all'interno del riquadro. Gli utenti possono quindi scegliere un negozio specifico per visualizzarne i dettagli.
Per evitare l'elenco delle posizioni e accedere direttamente a una pagina dei dettagli specifica, puoi utilizzare un metodo più preciso. Vedi l'esempio successivo.
Scenario 3: visualizzazione dei dettagli del luogo per un nome di luogo non univoco
Quando si tratta di nomi di luoghi comuni, una semplice ricerca per nome spesso restituisce un elenco di località. Per creare un link diretto a una pagina dei dettagli specifica, puoi utilizzare uno dei seguenti metodi:
Metodo 1: utilizzare una query precisa con nome e indirizzo del luogo
https://www.google.com/maps/search/?api=1&query=7-Eleven%2C37%20Swanston%20St%2C%20Melbourne%20Australia
In questo URL, il parametro query è formattato come nome del luogo, indirizzo. In questo modo, la ricerca viene ristretta e viene creato un link diretto alla posizione desiderata.
Metodo 2: utilizzo dell'ID luogo
Gli ID luogo identificano in modo univoco un luogo nel database di Google Places e su Google Maps.
https://www.google.com/maps/search/?api=1&query=7-Elevan&query_place_id=ChIJGcmcg7ZC1moRAOacd3HoEwM
In questo caso, ChIJGcmcg7ZC1moRAOacd3HoEwM è l'ID luogo univoco per il luogo specifico. Il parametro query è ancora obbligatorio, ma verrà utilizzato solo se Google
Maps non riesce a trovare l'ID luogo.
Scenario 4: visualizzazione dei dettagli del luogo utilizzando le coordinate di latitudine e longitudine, nonché l'ID luogo
L'utilizzo dell'ID luogo garantisce che Google Maps mostri informazioni dettagliate sul luogo.
https://www.google.com/maps/search/?api=1&query=-33.8567%2C151.2152&query_place_id=ChIJ3S-JXmauEmsRUcIaWtf4MzE
Recupero degli ID luogo senza costi
Per recuperare gli ID luogo in modo programmatico, puoi utilizzare la funzionalità API Places: Text Search(solo ID). Si tratta di un metodo senza costi per ottenere gli ID luogo. Scopri di più sull'ID luogo e sulla richiesta dell'API Places(New).
Richiesta di ricerca di testo dell'API Places(solo ID):
curl -X POST -d '{"textQuery" : "Sydney Opera House"}'
-H 'Content-Type: application/json' -H 'X-Goog-Api-Key: YOUR_API_KEY'
-H 'X-Goog-FieldMask: places.id'
'https://places.googleapis.com/v1/places:searchText'Risposta di Places API Text Search(solo ID):
{
"places": [
{
"id": "ChIJ3S-JXmauEmsRUcIaWtf4MzE"
}
]
}Gli ID luogo possono essere recuperati anche quando un utente fa clic o tocca un PDI sulle mappe. Scopri di più sulle icone dei PDI cliccabili(JavaScript, Android, iOS).
Conclusione
Fornire dettagli accurati sul luogo è fondamentale per un'esperienza positiva. Per assicurarti che gli utenti arrivino alla pagina dei dettagli del luogo corretta, crea gli URL di ricerca utilizzando uno dei seguenti formati consigliati:
query=PLACE_NAME, ADDRESSquery=PLACE_NAME&query_place_id=PLACE_ID
Evita di utilizzare solo le coordinate di latitudine/longitudine nel parametro query quando il tuo obiettivo è visualizzare i dettagli di un luogo specifico. Formati come
query=latitude,longitude, query=PLACE_NAME,latitude,longitude o
query=ADDRESS,latitude,longitude non portano sempre alla pagina dei dettagli del luogo desiderata. Mostrerà invece la latitudine e la longitudine della posizione.
Ricerca per categoria utilizzando gli URL di Maps
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à specificata. Se non viene specificata alcuna località, Google Maps tenta di trovare schede nelle vicinanze della tua posizione attuale.
Scenario 1: ricerca di luoghi nelle vicinanze
https://www.google.com/maps/search/?api=1&query=Cafe%20near%20Sydney%20Opera%20House%20that%20are%20open%20now
Fornire indicazioni stradali utilizzando gli URL di Maps
La funzione Indicazioni stradali mostra il percorso tra due o più punti specificati sulla mappa, nonché la distanza e il tempo di percorrenza. Offre agli sviluppatori un maggiore controllo sulle indicazioni fornite. La documentazione Indicazioni per gli URL di Maps di GMP fornisce istruzioni dettagliate sulla creazione di URL per indicazioni personalizzate.
Struttura dell'URL delle indicazioni stradali:
https://www.google.com/maps/dir/?api=1¶meters
Scenario 1: trovare il percorso migliore dalla posizione attuale dell'utente a una destinazione
https://www.google.com/maps/dir/?api=1&destination=Flinders%20Station%20Melbourne&travelmode=driving
Questo URL apre Google Maps e mostra le indicazioni stradali dalla posizione attuale dell'utente.
In questo URL, origin è omesso. Se origin viene omesso, il percorso viene impostato
sulla posizione di partenza più pertinente, ad esempio la posizione del dispositivo, se disponibile.
In caso contrario, la mappa risultante fornisce un modulo per consentire a un utente di inserire l'origine.
Il valore di origine e destinazione può essere un toponimo, un indirizzo o coordinate di latitudine/longitudine separate da virgole.
travelmode è un parametro facoltativo. Definisce il mezzo di trasporto.
Questo parametro può essere impostato come:
- alla guida
- passeggiate
- bicicletta
- motociclo
- trasporto pubblico
Se non viene specificata alcuna modalità di viaggio, Google Maps mostra una o più delle modalità più pertinenti per il percorso specificato e/o le preferenze dell'utente.
Gli sviluppatori possono anche specificare gli ID luogo utilizzando il parametro origin_place_id e
destination_place_id. L'utilizzo di un ID luogo è la migliore garanzia di collegamento al luogo giusto.
Recupero degli ID luogo senza costi
Per recuperare gli ID luogo in modo programmatico, puoi utilizzare la funzionalità API Places: Text Search(solo ID). Si tratta di un metodo senza costi per ottenere gli ID luogo. Scopri di più sull'ID luogo e sulla richiesta dell'API Places(New).
Richiesta di ricerca di testo dell'API Places(solo ID):
curl -X POST -d '{"textQuery" : "Sydney Opera House"}'
-H 'Content-Type: application/json' -H 'X-Goog-Api-Key: YOUR_API_KEY'
-H 'X-Goog-FieldMask: places.id'
'https://places.googleapis.com/v1/places:searchText'Risposta di Places API Text Search(solo ID):
{
"places": [
{
"id": "ChIJ3S-JXmauEmsRUcIaWtf4MzE"
}
]
}Gli ID luogo possono essere recuperati anche quando un utente fa clic o tocca un PDI sulle mappe. Scopri di più sulle icone dei PDI cliccabili(JavaScript, Android, iOS).
Scenario 3: fornire la navigazione passo passo
https://www.google.com/maps/dir/?api=1&destination=Flinders%20Station%20Melbourne&travelmode=driving&dir_action=navigate
Se imposti dir_action=navigate nell'URL, Google Maps si avvia in modalità di navigazione
guidata se la posizione attuale dell'utente(posizione del dispositivo) è disponibile e
viene utilizzata come punto di partenza (fornito esplicitamente o utilizzato implicitamente quando il parametro
di partenza viene omesso). In caso contrario, verrà visualizzata un'anteprima dell'itinerario.
La navigazione passo passo viene avviata quando dir_action=navigate è impostato e:
- L'origine è specificata ed è vicina alla posizione attuale dell'utente
- L'origine viene omessa e la posizione attuale dell'utente è disponibile
L'anteprima del percorso viene avviata quando:
dir_action=navigatenon è impostatodir_action=navigateè impostato e l'origine è specificata e non è vicina alla posizione attuale dell'utentedir_action=navigateè impostato e l'origine è omessa e la posizione attuale dell'utente non è disponibile
Tieni presente che la navigazione non è disponibile su tutti i prodotti Google Maps, come Google Maps Web, e/o tra tutte le destinazioni. In questi casi, questo parametro verrà ignorato.
 |
 |
Conclusione
Costruendo correttamente gli URL di Maps, puoi assicurarti che gli utenti ricevano le informazioni giuste di cui hanno bisogno in modo rapido ed efficiente.
Specifica sempre la destinazione e utilizza l'ID luogo, se possibile, per garantire la precisione
Quando l'obiettivo è fornire una navigazione immediata, includi il parametro dir_action=navigate per attivare la navigazione passo passo. La navigazione inizierà dalla posizione attuale dell'utente se la posizione del dispositivo è disponibile e viene utilizzata come origine (impostata in modo esplicito o omessa).
Scegliere l'approccio giusto per la tua applicazione
Hai due opzioni principali: utilizzare gli URL preformattati forniti dall'API Places o creare manualmente gli URL di Maps nella tua applicazione. Ogni approccio presenta una serie di vantaggi e svantaggi.
API Places:
I campi
googleMapsUriegoogleMapsLinksnella risposta Dettagli luogo forniscono URL pronti all'uso. Ciò riduce i tempi di sviluppo e minimizza il rischio di errori nella formattazione degli URL.Offre un controllo minore sulla configurazione delle indicazioni. Sebbene
googleMapsLinksoffra indicazioni di base, non supporta i waypoint o la personalizzazione avanzata. Inoltre, è relativamente meno semplice attivare direttamente la navigazione passo passo.
URL di Maps:
Offre maggiore flessibilità e controllo. Gli sviluppatori possono creare URL per visualizzare i dettagli dei luoghi e configurare vari aspetti delle indicazioni stradali, tra cui l'aggiunta di waypoint, la specifica delle modalità di viaggio e l'avvio della navigazione passo passo.
Richiede una comprensione più approfondita dei parametri e della struttura degli URL. La creazione manuale aumenta il potenziale di errori se non viene eseguita con attenzione.
Migliorare gli URL di Maps con i parametri UTM
Per aiutare Google a comprendere meglio in che modo gli sviluppatori integrano gli URL di Maps e per garantire prestazioni ottimali, ti consigliamo di includere i parametri di monitoraggio UTM nella creazione degli URL. Aggiungendo i parametri utm_source e utm_campaign, fornisci dati preziosi che ci consentono di analizzare i pattern di utilizzo e migliorare il prodotto URL di Maps.
Per il parametro utm_source, utilizza il nome dell'applicazione. Il parametro
utm_campaign deve riflettere l'azione che l'utente intende eseguire, ad esempio
"location_sharing", "place_details_search" o "directions_request".
Ad esempio, un URL con parametri UTM potrebbe avere il seguente aspetto:
https://www.google.com/maps/search/?api=1&query=Sydney+Opera+House&query_place_id=ChIJ3S-JXmauEmsRUcIaWtf4MzE&utm_source=YourAppName&utm_campaign=place_details_search
L'utilizzo coerente di questi parametri ci aiuta a identificare le aree da migliorare, a risolvere i problemi in modo più efficace e, in definitiva, a offrire un'esperienza migliore per tutti gli utenti.
Passaggi successivi
Letture consigliate:
Collaboratori
Autori principali:
Teresa Qin | Google Maps Solutions Engineer della piattaforma