Wytyczne Map Google na Androida

Aplikacja Mapy Google na Androida udostępnia kilka intencji, które pozwalają uruchomić Mapy Google w trybie wyświetlania, wyszukiwania, nawigacji i Street View. Jeśli chcesz umieścić mapę w swojej aplikacji, zapoznaj się z Przewodnikiem dla początkujących.

Omówienie

Intencje umożliwiają uruchomienie działania w innej aplikacji przez opisanie prostego działania, które chcesz wykonać (np. „Wyświetl mapę” lub „Pokaż trasę na lotnisko”) w obiekcie Intent. Aplikacja Mapy Google na Androida obsługuje kilka różnych intencji. Dzięki niej możesz uruchomić aplikację Mapy Google i wykonać jedną z tych czynności:

1. Wyświetlanie mapy w określonej lokalizacji i na powiększenia.
2. Możesz wyszukiwać lokalizacje i miejsca, a następnie wyświetlać je na mapie.
3. Możliwość wysyłania wskazówek dojazdu z jednej lokalizacji do drugiej. Wskazówki dojazdu można wyświetlić dla trzech środków transportu: samochodowych, spacerowych lub rowerowych.
4. Wyświetlaj zdjęcia panoramiczne w Google Street View.

Na tej stronie opisujemy intencje, których możesz użyć w aplikacji Mapy Google na Androida. Więcej informacji na temat intencji i filtrów intencji oraz intencji często używanych na platformie Android znajdziesz w dokumentacji dla deweloperów aplikacji na Androida.

Żądania intencji

Aby uruchomić Mapy Google z intencją, musisz najpierw utworzyć obiekt Intent, w którym określono jego działanie, identyfikator URI i pakiet.

• Działanie: wszystkie intencje w Mapach Google są nazywane działaniami w wyszukiwarce ACTION_VIEW.
• Identyfikator URI: intencje Map Google używają zakodowanego adresu URL, który określa żądane działanie wraz z pewnymi danymi, na podstawie których ma zostać wykonane.
• Pakiet: wywołanie setPackage("com.google.android.apps.maps") gwarantuje, że aplikacja Mapy Google na Androida obsługuje intencję. Jeśli ten pakiet nie jest ustawiony, system określa, które aplikacje obsługują Intent. Jeśli dostępnych jest wiele aplikacji, użytkownik może zobaczyć pytanie o to, której chce użyć.

Po utworzeniu obiektu Intent możesz zażądać uruchomienia powiązanej aplikacji na kilka sposobów. Popularną metodą jest przekazywanie Intent do metody startActivity(). System uruchomi niezbędne aplikacje – w tym przypadku Mapy Google – i zainicjuje odpowiadające im połączenie 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)

Jeśli system nie rozpozna aplikacji, która może zareagować na intencję, może ona ulec awarii. Z tego powodu należy sprawdzić, czy aplikacja odbierająca jest zainstalowana, zanim przedstawisz użytkownikowi jedną z tych intencji.

Aby zweryfikować, czy aplikacja może odebrać intencję, wywołaj jej obiekt resolveActivity() za pomocą obiektu Intent. Jeśli wynik nie jest pusty, istnieje co najmniej 1 aplikacja, która może obsłużyć intencję, i można bezpiecznie ją wywołać startActivity(). Jeśli efekt to null, nie należy używać intencji, a w miarę możliwości wyłączyć funkcję wywołującą intencję.

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

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

Aby na przykład wyświetlić mapę San Francisco, możesz użyć tego kodu:

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)
}

ciągi zapytań zakodowanych na potrzeby adresu URL,

Wszystkie ciągi przekazywane do intencji Map Google muszą być zakodowane na podstawie identyfikatora URI. Na przykład ciąg znaków „1st & Pike, Seattle” powinien zmienić się na 1st%20%26%20Pike%2C%20Seattle. Spacje w ciągu znaków mogą być zakodowane znakiem %20 lub zastępowane znakiem plusa (+).

Aby zakodować ciągi znaków, możesz użyć metody android.net.Uri parse(). Na przykład:

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"))

Wyświetlanie mapy

Użyj intencji geo:, aby wyświetlić mapę w określonej lokalizacji i na powiększenia.

geo:latitude,longitude?z=zoom

Parametry

• latitude i longitude ustawiają centralny punkt mapy.
• Opcjonalnie z ustawia początkowy poziom powiększenia mapy. Akceptowane są wartości z zakresu od 0 (cały świat) do 21 (pojedyncze budynki). Górny limit może się różnić w zależności od danych mapy dostępnych w wybranej lokalizacji.

Przykłady

// Creates an Intent that will load 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 will load 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)

Wyszukiwanie lokalizacji

Użyj tej intencji, aby wyświetlać wyszukiwane hasła w określonym widocznym obszarze. Gdy zapytanie ma jeden wynik, możesz użyć tej intencji, aby wyświetlić pinezkę w określonym miejscu lub adresie, takim jak punkt orientacyjny, firma, obiekt geograficzny lub miasto.

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

Parametry

Oprócz parametrów używanych do wyświetlania mapy wyszukiwarka obsługuje te parametry:

• q wskazuje miejsca do wyróżnienia na mapie. Parametr q jest wymagany w przypadku wszystkich żądań wyszukiwania. Jako lokalizację lub nazwę miejsca przyjmuje nazwę. Ciąg powinien być zakodowany na potrzeby adresu URL, więc adres taki jak „City Hall, New York, NY” powinien zostać przekonwertowany na adres City+Hall,New+York,NY.

• label umożliwia ustawienie własnej etykiety w miejscu wskazanym na mapie. label musi być określony ciągiem znaków.

Wyszukiwanie kategorii

Jeśli przekażesz ogólne wyszukiwane hasło, aplikacja Mapy Google spróbuje znaleźć lokalizację, która znajduje się w pobliżu podanej szerokości lub długości spełniającej Twoje kryteria. Jeśli nie podasz lokalizacji, Mapy Google spróbują znaleźć wizytówki w pobliżu. Na przykład:

// 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)

Możesz jeszcze bardziej odchylić wyniki wyszukiwania, określając parametr zoom wraz z ciągiem zapytania. W przykładzie poniżej powiększenie 10 powoduje, że zamiast restauracji w pobliżu próbuje znaleźć restauracje na poziomie miasta.

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)

Wyszukiwanie lokalizacji

Po wyszukaniu konkretnego adresu pojawi się pinezka w tej lokalizacji.

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)

W powyższym przykładzie ustawiamy szerokość i szerokość 0 0, ale przekazujemy adres jako ciąg zapytania. Jeśli szukasz konkretnej lokalizacji, szerokość i długość geograficzna nie jest wymagana. Jeśli jednak nie znasz dokładnego adresu, możesz spróbować poprawić odchylenie wyników wyszukiwania, określając współrzędne. Na przykład wyszukiwanie adresu „Główna” zwróci zbyt wiele wyników.

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

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

Dodanie szerokości/długości geograficznej identyfikatora URI intencji spowoduje promowanie wyników pod kątem konkretnego obszaru:

// 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)

Jeśli wiesz, że wyszukiwanie zwróci jedną wartość, możesz przekazać opcjonalną etykietę. Etykiety muszą być określone jako ciągi znaków i będą wyświetlane pod znacznikiem mapy. Pamiętaj, że etykiety są dostępne tylko wtedy, gdy q jest wartością współrzędnej.

// Display a label at the location of Google's Sydney office
Uri gmmIntentUri = Uri.parse("geo:0,0?q=Google+Sydney@-33.8666,151.1957");
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)

Zamiast podawania adresu lub szerokości i długości geograficznej możesz wyświetlić pinezkę w znanej lokalizacji, używając kodu plusa.

// 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 examples above

// 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 examples above

Uruchamiam nawigację zakręt po zakręcie

Skorzystaj z tej opcji, aby uruchomić nawigację w Mapach Google ze szczegółowymi wskazówkami dojazdu do podanego adresu lub współrzędnej. Wskazówki są zawsze podawane przez bieżącą lokalizację użytkownika.

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

Parametry

• q: określa punkt końcowy wyszukiwania. Wartością mogą być szerokość i długość geograficzna lub adres w formacie zapytania. Jeśli jest to ciąg zapytania, który zwraca więcej niż jeden wynik, wybierany jest pierwszy.

• mode określa metodę transportu. Tryb jest opcjonalny i można go ustawić jako:

  • d podczas jazdy (domyślnie)
  • b na rowerze
  • l motocyklem
  • w na spacery

• avoid określa cechy, których powinna unikać trasa. Opcja „Unikaj” jest opcjonalna i można ją ustawić jako:

  • t za przejazd płatny
  • h na autostradach
  • f dla promów

Przykłady

Intent poniżej poprosi o szczegółową nawigację do zoo Taronga w Australii:

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)

Jeśli nie chcesz płacić za przejazd lub korzystać z promu, możesz poprosić o trasę, aby tego uniknąć.

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)

Możesz też poprosić o wskazówki dojazdu rowerem.

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)

Jeśli wolisz korzystać z motocykla, możesz poprosić o wyznaczenie w nich wąskich dróg i szlaków niedostępnych dla samochodów. Poniższy atrybut intent zwraca trasę w Indiach.

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)

Wyświetlanie panoramy Street View

Użyj intencji google.streetview, aby uruchomić Google Street View. Google Street View udostępnia panoramiczne widoki z wybranych miejsc na obszarze pokrycia. Dostępne są również zdjęcia sferyczne dodane przez użytkowników oraz specjalne kolekcje Street View.

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

Parametry

Wszystkie identyfikatory URI google.streetview muszą zawierać parametr cbll lub panoid.

• cbll akceptuje szerokość i długość geograficzną jako wartości oddzielone przecinkami (46.414382,10.013988). Aplikacja wyświetli panoramę sfotografowaną w pobliżu tej lokalizacji. Zdjęcia Street View są okresowo odświeżane, a za każdym razem mogą być wykonywane z nieco innych pozycji, więc po ich zaktualizowaniu lokalizacja może zostać sfotografowana w inny sposób.

• panoid to konkretny identyfikator panoramy. Jeśli podano zarówno identyfikator panoid, jak i cbll, Mapy Google będą używać identyfikatora panoramy. Identyfikatory panoram są dostępne dla aplikacji na Androida z obiektu StreetViewPanoramaLocation.

• cbp to opcjonalny parametr, który koryguje początkową orientację kamery. Parametr cbp przyjmuje 5 wartości rozdzielonych przecinkami, z których wszystkie są opcjonalne. Najważniejsze wartości to odpowiednio druga, czwarta i piąta ustawienie, które odpowiednio określają położenie, powiększenie i przechylenie. Pierwsza i trzecia wartość nie są obsługiwane i powinny być ustawione na 0.

  • bearing: kierunek względem kompasu w stopniach od północy od góry. Prawdziwa północ to 0, wschód – 90, południe – 180, zachód – 270. Wartości przekazywane do złącza są zawijane, czyli czyli 0°, 360° i 720°. Znak jest zdefiniowany jako drugi z 5 wartości rozdzielonych przecinkami.
  • zoom: ustawia poziom powiększenia aparatu. Domyślny poziom powiększenia to 0. Powiększenie 1 spowoduje podwojenie powiększenia. Powiększenie jest ograniczone do wartości 0 – maksymalny poziom bieżącej orientacji. Oznacza to, że każda wartość spoza tego zakresu zostanie ustawiona na najbliższą skrajną granicę. Na przykład wartość -1 zostanie ustawiona na 0. Powiększenie to czwarta z 5 wartości rozdzielonych przecinkami.
  • tilt: określa kąt obrotu kamery w górę lub w dół. Zakres wynosi od -90 do 0-90, 90 jest skierowany w dół, 0 na środku horyzontu, a -90 patrzy prosto w górę.

Przykłady

Oto kilka przykładów użycia intencji 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 will angle 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 will angle 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)