Google Maps Intents per Android

L'app Google Maps per Android espone diversi intent che puoi utilizzare per avviare Google Maps in modalità di visualizzazione, ricerca, navigazione o Street View. Per incorporare una mappa nella tua app, consulta la Guida rapida di Maps SDK for Android.

Per le piattaforme Android Automotive OS (AAOS), esistono considerazioni specifiche e intent aggiuntivi disponibili. Per maggiori dettagli, consulta la documentazione relativa agli intent di Google Maps for Android Automotive.

Panoramica

Gli intent ti consentono di avviare un'attività in un'altra app descrivendo un'azione che vuoi eseguire (ad esempio "visualizza una mappa" o "mostra le indicazioni stradali per l' aeroporto") in un Intent oggetto. L'app Google Maps per Android supporta diversi intent,che ti consentono di avviare l'app Google Maps ed eseguire una delle quattro azioni seguenti:

1. Visualizzare una mappa in una posizione e a un livello di zoom specifici.
2. Cercare località o luoghi e visualizzarli su una mappa.
3. Richiedere indicazioni stradali da una località a un'altra. Le indicazioni stradali possono essere restituite per tre modalità di trasporto: auto, a piedi, in bicicletta.
4. Visualizzare immagini panoramiche in Google Street View.

Questa pagina descrive gli intent che puoi utilizzare con l'app Google Maps per Android. Per ulteriori informazioni sugli intent, consulta Intent e filtri di intent e Intent comuni.

Richieste di intent

Per avviare Google Maps con un intent, devi prima creare un Intent oggetto, specificandone l'azione, l'URI e il pacchetto.

• Azione: tutti gli intent di Google Maps vengono chiamati come azione di visualizzazione — ACTION_VIEW.
• URI: gli intent di Google Maps utilizzano URI con codifica URL che specificano un'azione selezionata, insieme ad alcuni dati con cui eseguire l'azione.

• Pacchetto: la chiamata di setPackage("com.google.android.apps.maps") garantisce che l'app Google Maps per Android gestisca l'intent. Se il pacchetto non è impostato, il sistema determina quali app possono gestire il Intent. Se sono disponibili più app, all'utente potrebbe essere chiesto quale app vuole utilizzare.

  consulta la documentazione relativa agli intent di Google Maps per Android Automotive.

Dopo aver creato il Intent, puoi richiedere al sistema di avviare l'app correlata in diversi modi. Un metodo comune consiste nel passare il Intent al startActivity() metodo. Il sistema avvia l'app necessaria — in questo caso Google Maps — e avvia il corrispondente Activity.

// Create a Uri from an intent string. Use the result to create an Intent.
Uri gmmIntentUri = Uri.parse("google.streetview:cbll=46.414382,10.013988");
// Create an Intent from gmmIntentUri. Set the action to ACTION_VIEW
Intent mapIntent = new Intent(Intent.ACTION_VIEW, gmmIntentUri);
// Make the Intent explicit by setting the Google Maps package
mapIntent.setPackage("com.google.android.apps.maps");
// Attempt to start an activity that can handle the Intent
startActivity(mapIntent);

// Create a Uri from an intent string. Use the result to create an Intent.
val gmmIntentUri = Uri.parse("google.streetview:cbll=46.414382,10.013988")
// Create an Intent from gmmIntentUri. Set the action to ACTION_VIEW
val mapIntent = Intent(Intent.ACTION_VIEW, gmmIntentUri)
// Make the Intent explicit by setting the Google Maps package
mapIntent.setPackage("com.google.android.apps.maps")
// Attempt to start an activity that can handle the Intent
startActivity(mapIntent)

Se il sistema non riesce a identificare un'app in grado di rispondere all'intent, la tua app potrebbe arrestarsi in modo anomalo. Per questo motivo, prima di presentare uno di questi intent a un utente, verifica che sia installata un'applicazione di ricezione.

Per verificare che un'app sia disponibile per ricevere l'intent, chiama resolveActivity() sull'oggetto Intent. Se il risultato non è null, esiste almeno un'app in grado di gestire l'intent ed è sicuro chiamare startActivity(). Se il risultato è null, non utilizzare l'intent e, se possibile, disattiva la funzionalità che lo richiama.

if (mapIntent.resolveActivity(getPackageManager()) != null) {
    ...
}

mapIntent.resolveActivity(packageManager)?.let {
    ...
}

Ad esempio, per visualizzare una mappa di San Francisco, puoi utilizzare il seguente codice:

Uri gmmIntentUri = Uri.parse("geo:37.7749,-122.4194");
Intent mapIntent = new Intent(Intent.ACTION_VIEW, gmmIntentUri);
mapIntent.setPackage("com.google.android.apps.maps");
if (mapIntent.resolveActivity(getPackageManager()) != null) {
    startActivity(mapIntent);
}

val gmmIntentUri = Uri.parse("geo:37.7749,-122.4194")
val mapIntent = Intent(Intent.ACTION_VIEW, gmmIntentUri)
mapIntent.setPackage("com.google.android.apps.maps")
mapIntent.resolveActivity(packageManager)?.let {
    startActivity(mapIntent)
}

Stringhe di query con codifica URL

Tutte le stringhe passate agli intent di Google Maps devono essere codificate come URI. Ad esempio, la stringa 1st & Pike, Seattle deve diventare 1st%20%26%20Pike%2C%20Seattle. Gli spazi nella stringa possono essere codificati con %20 o sostituiti con il segno più (+).

Puoi utilizzare il metodo android.net.Uri encode() per codificare le stringhe. Ad esempio:

Uri gmmIntentUri =
    Uri.parse("geo:37.7749,-122.4192?q=" + Uri.encode("1st & Pike, Seattle"));

val gmmIntentUri =
    Uri.parse("geo:37.7749,-122.4192?q=" + Uri.encode("1st & Pike, Seattle"))

Visualizzare una mappa

Utilizza l'intent geo: per visualizzare una mappa in una posizione e a un livello di zoom specifici.

geo:latitude,longitude?z=zoom

Parametri

• latitude e longitude impostano il punto centrale della mappa.
• z imposta facoltativamente il livello di zoom iniziale della mappa. I valori accettati vanno da 0 (il mondo intero) a 21 (singoli edifici). Il limite superiore può variare a seconda dei dati della mappa disponibili nella località selezionata.

Esempi

// Creates an Intent that loads a map of San Francisco
Uri gmmIntentUri = Uri.parse("geo:37.7749,-122.4194");
Intent mapIntent = new Intent(Intent.ACTION_VIEW, gmmIntentUri);
mapIntent.setPackage("com.google.android.apps.maps");
startActivity(mapIntent);

// Creates an Intent that loads a map of San Francisco
val gmmIntentUri = Uri.parse("geo:37.7749,-122.4194")
val mapIntent = Intent(Intent.ACTION_VIEW, gmmIntentUri)
mapIntent.setPackage("com.google.android.apps.maps")
startActivity(mapIntent)

Cercare una località

Utilizza questo intent per visualizzare le query di ricerca all'interno di un'area visibile specificata. Quando la query ha un solo risultato, puoi utilizzare questo intent per visualizzare un segnaposto in un luogo o indirizzo specifico, ad esempio un punto di riferimento, un'attività, una caratteristica geografica, o una città.

geo:latitude,longitude?q=query
geo:0,0?q=my+street+address
geo:0,0?q=latitude,longitude(label)

Parametri

Oltre ai parametri utilizzati per visualizzare una mappa, la ricerca supporta i seguenti parametri:

• q definisce i luoghi da evidenziare sulla mappa. Il parametro q è obbligatorio per tutte le richieste di ricerca. Accetta una località come nome del luogo o indirizzo. La stringa deve essere codificata come URL, quindi un indirizzo come City Hall, New York, NY deve essere convertito in City+Hall,New+York,NY.

• label ti consente di impostare un'etichetta personalizzata in un luogo identificato sulla mappa. La label deve essere specificata come stringa.

Ricerca per categoria

Se passi un termine di ricerca generale, Google Maps tenta di trovare una località vicino a latitudine e longitudine specificate che corrisponda ai tuoi criteri. Se non viene specificata alcuna località, Google Maps tenta di trovare le schede nelle vicinanze. Ad esempio:

// Search for restaurants nearby
Uri gmmIntentUri = Uri.parse("geo:0,0?q=restaurants");
Intent mapIntent = new Intent(Intent.ACTION_VIEW, gmmIntentUri);
mapIntent.setPackage("com.google.android.apps.maps");
startActivity(mapIntent);
// Search for restaurants in San Francisco.
Uri gmmIntentUri = Uri.parse("geo:37.7749,-122.4194?q=restaurants");
Intent mapIntent = new Intent(Intent.ACTION_VIEW, gmmIntentUri);
mapIntent.setPackage("com.google.android.apps.maps");
startActivity(mapIntent);

// Search for restaurants nearby.
val gmmIntentUri = Uri.parse("geo:0,0?q=restaurants")
val mapIntent = Intent(Intent.ACTION_VIEW, gmmIntentUri)
mapIntent.setPackage("com.google.android.apps.maps")
startActivity(mapIntent)
// Search for restaurants in San Francisco.
val gmmIntentUri =
    Uri.parse("geo:37.7749,-122.4194?q=restaurants")
val mapIntent = Intent(Intent.ACTION_VIEW, gmmIntentUri)
mapIntent.setPackage("com.google.android.apps.maps")
startActivity(mapIntent)

Puoi influenzare ulteriormente i risultati di ricerca specificando un parametro di zoom insieme alla stringa di query. Nell'esempio seguente, l'aggiunta di uno zoom di 10 tenta di trovare ristoranti a livello di città anziché nelle vicinanze.

Uri gmmIntentUri = Uri.parse("geo:37.7749,-122.4194?z=10&q=restaurants");
Intent mapIntent = new Intent(Intent.ACTION_VIEW, gmmIntentUri);
mapIntent.setPackage("com.google.android.apps.maps");
startActivity(mapIntent);

val gmmIntentUri =
    Uri.parse("geo:37.7749,-122.4194?z=10&q=restaurants")
val mapIntent = Intent(Intent.ACTION_VIEW, gmmIntentUri)
mapIntent.setPackage("com.google.android.apps.maps")
startActivity(mapIntent)

Ricerca di località

La ricerca di un indirizzo specifico visualizza un segnaposto in quella località.

Uri gmmIntentUri = Uri.parse("geo:0,0?q=1600 Amphitheatre Parkway, Mountain+View, California");
Intent mapIntent = new Intent(Intent.ACTION_VIEW, gmmIntentUri);
mapIntent.setPackage("com.google.android.apps.maps");
startActivity(mapIntent);

val gmmIntentUri =
    Uri.parse("geo:0,0?q=1600 Amphitheatre Parkway, Mountain+View, California")
val mapIntent = Intent(Intent.ACTION_VIEW, gmmIntentUri)
mapIntent.setPackage("com.google.android.apps.maps")
startActivity(mapIntent)

L'esempio precedente imposta una latitudine e una longitudine di 0,0, ma passa un indirizzo come stringa di query. Quando cerchi una località specifica, la latitudine e la longitudine non sono obbligatorie. Tuttavia, se non conosci l'indirizzo esatto, puoi tentare di influenzare i risultati della ricerca specificando una coordinata. Ad esempio, l'esecuzione di una ricerca di indirizzi per "Via Roma" potrebbe restituire troppi risultati.

// Searching for 'Main Street' returns too many results.
Uri gmmIntentUri = Uri.parse("geo:0,0?q=101+main+street");

// Searching for 'Main Street' returns too many results.
val gmmIntentUri = Uri.parse("geo:0,0?q=101+main+street")

L'aggiunta di una latitudine e una longitudine all'URI dell'intent influenza i risultati verso una determinata area:

// Searches for 'Main Street' near San Francisco.
Uri gmmIntentUri = Uri.parse("geo:37.7749,-122.4194?q=101+main+street");
Intent mapIntent = new Intent(Intent.ACTION_VIEW, gmmIntentUri);
mapIntent.setPackage("com.google.android.apps.maps");
startActivity(mapIntent);

// Searches for 'Main Street' near San Francisco.
val gmmIntentUri =
    Uri.parse("geo:37.7749,-122.4194?q=101+main+street")
val mapIntent = Intent(Intent.ACTION_VIEW, gmmIntentUri)
mapIntent.setPackage("com.google.android.apps.maps")
startActivity(mapIntent)

Quando sai che la ricerca restituisce un singolo valore, potresti voler passare un etichetta facoltativa. Le etichette devono essere specificate come stringa e visualizzate sotto il segnaposto della mappa. Tieni presente che le etichette sono disponibili solo quando q viene specificato come coordinata di latitudine e longitudine.

// Display a label at the location of Google's Sydney office.
Uri gmmIntentUri = Uri.parse("geo:0,0?q=-33.8666,151.1957(Google+Sydney)");
Intent mapIntent = new Intent(Intent.ACTION_VIEW, gmmIntentUri);
mapIntent.setPackage("com.google.android.apps.maps");
startActivity(mapIntent);

// Display a label at the location of Google's Sydney office.
val gmmIntentUri =
    Uri.parse("geo:0,0?q=-33.8666,151.1957(Google+Sydney)")
val mapIntent = Intent(Intent.ACTION_VIEW, gmmIntentUri)
mapIntent.setPackage("com.google.android.apps.maps")
startActivity(mapIntent)

In alternativa a un indirizzo o a una latitudine e una longitudine, puoi visualizzare un segnaposto in una località nota utilizzando un Plus Code.

// Display the location of Google, San Francisco using a global plus code.
Uri gmmIntentUri = Uri.parse("http://plus.codes/849VQJQ5+XX");
// Equivalently, define the same location using a local plus code.
gmmIntentUri = Uri.parse("https://plus.codes/QJQ5+XX,San%20Francisco");
// Construct and use the Intent as in the preceding examples.

// Display the location of Google, San Francisco using a global plus code.
var gmmIntentUri = Uri.parse("http://plus.codes/849VQJQ5+XX")
// Equivalently, define the same location using a local plus code.
gmmIntentUri = Uri.parse("https://plus.codes/QJQ5+XX,San%20Francisco")
// Construct and use the Intent as in the preceding examples.

Avviare la navigazione passo passo

Utilizza questo URI dell'intent per avviare la navigazione di Google Maps con indicazioni stradali passo passo per l'indirizzo o la coordinata specificati. Le indicazioni stradali vengono sempre fornite dalla posizione attuale dell'utente.

google.navigation:q=a+street+address
google.navigation:q=latitude,longitude  

Parametri

• q: imposta l'endpoint per le ricerche di navigazione. Questo valore può essere una coordinata di latitudine e longitudine o un indirizzo in formato query. Se si tratta di una stringa di query che restituisce più di un risultato, viene selezionato il primo risultato.

• mode imposta il metodo di trasporto. mode è facoltativo e può essere impostato su uno dei seguenti valori:

  • d per la guida (valore predefinito)
  • b per la bicicletta
  • l per il veicolo a due ruote
  • w per la camminata

• avoid imposta le funzionalità che il percorso deve tentare di evitare. avoid è facoltativo e può essere impostato su uno o più dei seguenti valori:

  • t per i pedaggi
  • h per le autostrade
  • f per i traghetti

Esempi

Le seguenti Intent richieste attivano la navigazione passo passo per lo zoo di Taronga, a Sydney, in Australia:

Uri gmmIntentUri = Uri.parse("google.navigation:q=Taronga+Zoo,+Sydney+Australia");
Intent mapIntent = new Intent(Intent.ACTION_VIEW, gmmIntentUri);
mapIntent.setPackage("com.google.android.apps.maps");
startActivity(mapIntent);

val gmmIntentUri =
    Uri.parse("google.navigation:q=Taronga+Zoo,+Sydney+Australia")
val mapIntent = Intent(Intent.ACTION_VIEW, gmmIntentUri)
mapIntent.setPackage("com.google.android.apps.maps")
startActivity(mapIntent)

Se preferisci non pagare i pedaggi o prendere un traghetto, puoi richiedere un percorso che tenti di evitare queste funzionalità.

Uri gmmIntentUri = Uri.parse("google.navigation:q=Taronga+Zoo,+Sydney+Australia&avoid=tf");
Intent mapIntent = new Intent(Intent.ACTION_VIEW, gmmIntentUri);
mapIntent.setPackage("com.google.android.apps.maps");
startActivity(mapIntent);

val gmmIntentUri =
    Uri.parse("google.navigation:q=Taronga+Zoo,+Sydney+Australia&avoid=tf")
val mapIntent = Intent(Intent.ACTION_VIEW, gmmIntentUri)
mapIntent.setPackage("com.google.android.apps.maps")
startActivity(mapIntent)

Se preferisci fare un po' di esercizio, puoi richiedere indicazioni stradali per la bicicletta.

Uri gmmIntentUri = Uri.parse("google.navigation:q=Taronga+Zoo,+Sydney+Australia&mode=b");
Intent mapIntent = new Intent(Intent.ACTION_VIEW, gmmIntentUri);
mapIntent.setPackage("com.google.android.apps.maps");
startActivity(mapIntent);

val gmmIntentUri =
    Uri.parse("google.navigation:q=Taronga+Zoo,+Sydney+Australia&mode=b")
val mapIntent = Intent(Intent.ACTION_VIEW, gmmIntentUri)
mapIntent.setPackage("com.google.android.apps.maps")
startActivity(mapIntent)

Se preferisci prendere un veicolo a due ruote motorizzato, puoi richiedere che le indicazioni stradali includano strade e sentieri stretti non disponibili per le auto. Il seguente intent restituisce un percorso in India.

Uri gmmIntentUri = Uri.parse("google.navigation:q=Connaught+Place,+New+Delhi,Delhi&mode=l");
Intent mapIntent = new Intent(Intent.ACTION_VIEW, gmmIntentUri);
mapIntent.setPackage("com.google.android.apps.maps");
startActivity(mapIntent);

val gmmIntentUri =
    Uri.parse("google.navigation:q=Connaught+Place,+New+Delhi,Delhi&mode=l")
val mapIntent = Intent(Intent.ACTION_VIEW, gmmIntentUri)
mapIntent.setPackage("com.google.android.apps.maps")
startActivity(mapIntent)

Visualizzare una panoramica di Street View

Utilizza l'intent google.streetview per avviare Google Street View. Google Street View offre viste panoramiche da località designate all'interno della sua area di copertura. Sono disponibili anche le foto sferiche contribuite dagli utenti, e le raccolte speciali di Street View.

google.streetview:cbll=latitude,longitude&cbp=0,bearing,0,zoom,tilt
google.streetview:panoid=id&cbp=0,bearing,0,zoom,tilt

Parametri

Tutti gli URI google.streetview devono includere un parametro cbll o panoid:

• cbll accetta una latitudine e una longitudine come valori separati da virgola (46.414382,10.013988). L'app mostra la panoramica fotografata più vicina a questa località. Poiché le immagini di Street View vengono aggiornate periodicamente e le fotografie potrebbero essere scattate da posizioni leggermente diverse ogni volta, è possibile che la tua località venga spostata su una panoramica diversa quando le immagini vengono aggiornate.

• panoid è un ID panoramico specifico. Google Maps utilizza l'ID panoramico se vengono specificati sia un panoid sia un cbll. Gli ID panoramici sono disponibili per un' app Android dall'oggetto StreetViewPanoramaLocation.

• cbp è un parametro facoltativo che regola l'orientamento iniziale di la videocamera. Il parametro cbp accetta 5 valori separati da virgola, tutti facoltativi. I valori più significativi sono il secondo, il quarto e il quinto che impostano rispettivamente la direzione, lo zoom e l'inclinazione. Il primo e il terzo valori non sono supportati e devono essere impostati su 0.

  • bearing: indica la direzione della bussola della videocamera in gradi in senso orario da nord. Il nord vero è 0, l'est è 90, il sud è 180, l'ovest è
    1. I valori passati alla direzione vengono riportati; ovvero, 0°, 360° e 720° puntano tutti nella stessa direzione. La direzione è definita come il secondo dei cinque valori separati da virgola.
  • zoom: imposta il livello di zoom della videocamera. Il livello di zoom predefinito è impostato su 0. Uno zoom di 1 raddoppierebbe l'ingrandimento. Lo zoom è limitato tra 0 e il livello di zoom massimo per la panoramica corrente. Ciò significa che qualsiasi valore al di fuori di questo intervallo viene impostato sull'estremo più vicino che rientra nell'intervallo. Ad esempio, un valore di -1 viene impostato su 0. Lo zoom è il quarto dei cinque valori separati da virgola.
  • tilt: specifica l'angolo, verso l'alto o verso il basso, della videocamera. L'intervallo va da -90 a 0 a 90, con 90 che guarda dritto verso il basso, 0 centrato sull' orizzonte e -90 che guarda dritto verso l'alto.

Esempi

Di seguito sono riportati alcuni esempi di utilizzo dell'intent di Street View.

// Displays an image of the Swiss Alps.
Uri gmmIntentUri = Uri.parse("google.streetview:cbll=46.414382,10.013988");
Intent mapIntent = new Intent(Intent.ACTION_VIEW, gmmIntentUri);
mapIntent.setPackage("com.google.android.apps.maps");
startActivity(mapIntent);
// Uses a PanoID to show an image from Maroubra beach in Sydney, Australia.
Uri gmmIntentUri = Uri.parse("google.streetview:panoid=Iaa2JyfIggYAAAQfCZU9KQ");
Intent mapIntent = new Intent(Intent.ACTION_VIEW, gmmIntentUri);
mapIntent.setPackage("com.google.android.apps.maps");
startActivity(mapIntent);
// Opens Street View between two Pyramids in Giza. The values passed to the
// cbp parameter angles the camera slightly up, and towards the east.
Uri gmmIntentUri = Uri.parse("google.streetview:cbll=29.9774614,31.1329645&cbp=0,30,0,0,-15");
Intent mapIntent = new Intent(Intent.ACTION_VIEW, gmmIntentUri);
mapIntent.setPackage("com.google.android.apps.maps");
startActivity(mapIntent);

// Displays an image of the Swiss Alps.
val gmmIntentUri =
    Uri.parse("google.streetview:cbll=46.414382,10.013988")
val mapIntent = Intent(Intent.ACTION_VIEW, gmmIntentUri)
mapIntent.setPackage("com.google.android.apps.maps")
startActivity(mapIntent)
// Uses a PanoID to show an image from Maroubra beach in Sydney, Australia.
val gmmIntentUri =
    Uri.parse("google.streetview:panoid=Iaa2JyfIggYAAAQfCZU9KQ")
val mapIntent = Intent(Intent.ACTION_VIEW, gmmIntentUri)
mapIntent.setPackage("com.google.android.apps.maps")
startActivity(mapIntent)
// Opens Street View between two Pyramids in Giza. The values passed to the
// cbp parameter angles the camera slightly up, and towards the east.
val gmmIntentUri =
    Uri.parse("google.streetview:cbll=29.9774614,31.1329645&cbp=0,30,0,0,-15")
val mapIntent = Intent(Intent.ACTION_VIEW, gmmIntentUri)
mapIntent.setPackage("com.google.android.apps.maps")
startActivity(mapIntent)