Pakiet SDK Miejsc na Androida zapewnia Twojej aplikacji szczegółowe informacje o miejscach, w tym ich nazwę i adres, lokalizację geograficzną określoną jako współrzędne geograficzne, typ miejsca (np. klub nocny, sklep zoologiczny, muzeum) i wiele innych. Aby uzyskać dostęp do informacji o konkretnym miejscu, możesz użyć identyfikatora miejsca – stałego identyfikatora, który jednoznacznie identyfikuje to miejsce.
Szczegóły miejsca
Obiekt Place
dostarcza informacji o konkretnym miejscu. Aby uzyskać dostęp do obiektu Place
, wykonaj te czynności:
- Zadzwoń pod numer
PlacesClient.fetchPlace()
– zapoznaj się z przewodnikiem, aby umieścić miejsce na podstawie identyfikatora. - Zadzwoń pod numer
PlacesClient.findCurrentPlace()
– zapoznaj się z przewodnikiem, aby uzyskać informacje o bieżącym miejscu.
Przy wysyłaniu prośby o miejsce musisz określić, które dane o miejscu chcesz zwrócić. Aby to zrobić, przekaż listę wartości Place.Field, które określają dane do zwrócenia. Ta lista należy rozważyć, ponieważ wpływa na koszt każdego żądania.
Ponieważ dane o miejscach nie mogą być puste, zwracane są tylko te wyniki z danymi (jeśli na przykład żądane miejsce nie zawiera zdjęć, pole photos
nie będzie widoczne).
W przykładzie poniżej przesyłamy listę 3 wartości Place.Field, aby określić dane zwracane przez żądanie:
Kotlin
// Specify the fields to return. val placeFields = listOf(Place.Field.NAME, Place.Field.RATING, Place.Field.OPENING_HOURS)
Java
// Specify the fields to return. final ListplaceFields = Arrays.asList(Place.Field.NAME, Place.Field.RATING, Place.Field.OPENING_HOURS);
Dostęp do pól danych obiektu Place
Po uzyskaniu obiektu Place
użyj go, aby uzyskać dostęp do pól danych określonych w żądaniu. Jeśli tego pola nie ma w obiekcie Place
, powiązana metoda zwraca wartość null. Poniżej przedstawiamy kilka przykładów dostępnych metod.
Pełną listę wszystkich metod znajdziesz w dokumentacji interfejsu API Place
.
getAddress()
– adres miejsca w formacie czytelnym dla człowieka.getAddressComponents()
–List
komponentów adresu dla tego miejsca. Komponenty te służą do wyodrębniania uporządkowanych informacji o adresie miejsca (np. w znalezieniu miasta, w którym znajduje się dane miejsce). Nie używaj tych komponentów do formatowania adresów. Zamiast tego użyj metodygetAddress()
, która udostępnia zlokalizowany adres.getId()
– identyfikator tekstowy miejsca. Więcej informacji o identyfikatorach miejsc znajdziesz w pozostałej części tej strony.getLatLng()
– lokalizacja geograficzna miejsca określona jako szerokość i długość geograficzna.getName()
– nazwa miejsca.getOpeningHours()
–OpeningHours
miejsca. WywołajOpeningHours.getWeekdayText()
, aby zwrócić listę ciągów znaków, które reprezentują godziny otwarcia i zamknięcia dla każdego dnia tygodnia. WywołajOpeningHours.getPeriods()
, aby zwrócić listę obiektówperiod
z bardziej szczegółowymi informacjami, które odpowiadają danym dostarczonym przezgetWeekdayText()
.Obiekt
Place
zawiera też metodęgetCurrentOpeningHours()
, która zwraca godziny pracy danego miejsca w ciągu najbliższych 7 dni, orazgetSecondaryOpeningHours()
, która zwraca dodatkowe godziny pracy tego miejsca w ciągu najbliższych 7 dni.isOpen()
– wartość logiczna wskazująca, czy miejsce jest obecnie otwarte. Jeśli nie podasz godziny, domyślnie zostanie użyta wartość bieżąca. Zwracana jest wartośćisOpen
tylko wtedy, gdy dostępne są zarówno wartościPlace.Field.UTC_OFFSET
, jak iPlace.Field.OPENING_HOURS
. Aby zapewnić dokładność wyników, poproś o polaPlace.Field.BUSINESS_STATUS
iPlace.Field.UTC_OFFSET
w pierwotnej prośbie o miejsce. Jeśli prośba nie zostanie wysłana, zakładamy, że firma działa. Obejrzyj ten film, aby dowiedzieć się, jak używać właściwościisOpen
z informacjami o miejscu.
Kilka prostych przykładów:
Kotlin
val name = place.name val address = place.address val location = place.latLng
Java
final CharSequence name = place.getName(); final CharSequence address = place.getAddress(); final LatLng location = place.getLatLng();
Dostęp do danych Miejsc dodanych w wersji 3.3.0
Pakiet SDK Miejsc na Androida w wersji 3.3.0 dodaje nowe dane do Place
:
- Typy miejsc: nowe wartości typu powiązane z miejscem.
- Opinie: maksymalnie 5 opinii o miejscu.
- Name language code (Kod języka nazwy): kod języka nazwy miejsca.
W sekcjach poniżej dowiesz się, jak uzyskać dostęp do tych nowych danych.
Dostęp do nowych typów miejsc
Z każdym miejscem może być powiązana co najmniej 1 wartość typu. Pakiet Miejsca SDK na Androida w wersji 3.3.0 dodaje wiele nowych wartości typów. Pełną listę znajdziesz w sekcji Rozwinięte typy miejsc.
W pakiecie Miejsca SDK na Androida w wersji 3.2.0 i wcześniejszych została użyta metoda Place.getTypes()
, która pozwala uzyskać dostęp do wartości typu powiązanych z miejscem. Place.getTypes()
zwraca listę typów w postaci wartości wyliczeniowych zdefiniowanych przez Place.Types
.
Metoda Place.getPlaceTypes()
zwraca wartości typu w formie listy wartości ciągu znaków. Zwracane wartości zależą od wersji pakietu Places SDK dla Androida:
- Pakiet SDK Miejsc na Androida (nowy): zwraca ciągi znaków zdefiniowane w tabelach A i B w typach miejsc (nowe), z uwzględnieniem wszystkich dodanych typów miejsc dodanych w wersji 3.3.0.
- Pakiet SDK Miejsc na Androida: zwraca wyliczenia zdefiniowane przez
Place.Types
, które nie obejmują nowych typów dodanych w wersji 3.3.0.
Najważniejsze różnice między tymi wersjami pakietu SDK znajdziesz w artykule Wybieranie wersji pakietu SDK.
Dostęp do opinii o miejscu
Pakiet SDK Miejsc na Androida (nowy) dodaje klasę Review
, która zawiera opinię o danym miejscu. Obiekt Place
może zawierać maksymalnie 5 opinii.
Klasa Review
może też zawierać informacje o autorze. Jeśli wyświetlasz opinię w aplikacji, musisz też uwzględnić wszelkie informacje o ich źródle i autorze.
Więcej informacji znajdziesz w artykule Wyświetlanie opinii.
Aby wypełnić obiekt Place
opiniami, musisz:
- Włącz nowy pakiet SDK podczas konfigurowania projektu Google Cloud.
- Zainicjuj nowy pakiet SDK w aktywności lub fragmencie.
- Uwzględnij
Place.Field.REVIEWS
w liście pól w prośbie o szczegóły miejsca. - Zadzwoń pod numer
PlacesClient.fetchPlace()
. Pole opinii nie jest obsługiwane przezPlacesClient.findCurrentPlace()
. - Aby uzyskać dostęp do pola danych opinii w obiekcie
Place
, użyj metodyPlace.getReviews()
.
Dostęp do kodu języka nazwy miejsca
Istniejąca metoda Place.getName()
zwraca ciąg tekstowy zawierający nazwę miejsca. Aby wypełnić obiekt Place
nazwą miejsca, musisz uwzględnić pole Place.Field.NAME
na liście pól w żądaniu informacji o miejscu.
Obiekt Place
zawiera teraz kod języka ciągu nazwy. Aby wypełnić obiekt Place
kodem języka, musisz:
- Włącz nowy pakiet SDK podczas konfigurowania projektu Google Cloud.
- Zainicjuj nowy pakiet SDK w aktywności lub fragmencie.
- Dodaj
Place.Field.NAME
do listy pól żądania. Ta wartość pozwala skonfigurować odpowiedź tak, aby w obiekciePlace
uwzględniła zarówno nazwę miejsca, jak i kod języka. - Zadzwoń pod numer
PlacesClient.fetchPlace()
. PolePlacesClient.findCurrentPlace()
nie obsługuje pola kodu języka. - Aby uzyskać dostęp do pola kodu języka w obiekcie
Place
, użyj metodyPlace.getNameLanguageCode()
.
Ustaw kod regionu w wersji 3.3.0
Pakiet Miejsca SDK na Androida (nowy) dodaje parametr żądania kodu regionu do właściwości Place Details. Kod regionu służy do formatowania odpowiedzi, określanej jako wartość dwuznakowego kodu CLDR. Ten parametr może też mieć wpływ na odchylenie wyników wyszukiwania. Brak wartości domyślnej. Aby ustawić kod regionu, musisz włączyć nowy pakiet SDK.
Jeśli nazwa kraju w polu adresu w odpowiedzi jest zgodna z kodem regionu, kod kraju jest pomijany w adresie.
Większość kodów CLDR jest taka sama jak kody ISO 3166-1, z pewnymi istotnymi wyjątkami. Na przykład krajowa domena w Wielkiej Brytanii to „uk” (.co.uk), a kod ISO 3166-1 to „gb” (technicznie rzecz biorąc, podmiot należący do „Wielkiej Brytanii Wielkiej Brytanii i Irlandii Północnej”). Parametr może wpływać na wyniki w zależności od obowiązującego prawa.
Znajdź miejsce na podstawie dokumentu tożsamości
Identyfikator miejsca to identyfikator tekstowy, który jednoznacznie identyfikuje miejsce. W pakiecie SDK Miejsc na Androida możesz pobrać identyfikator miejsca, wywołując metodę Place.getId()
.
Usługa Autouzupełnianie miejsca zwraca też identyfikator każdego miejsca, który pasuje do podanego zapytania i filtra. Możesz zapisać identyfikator miejsca i użyć go później do ponownego pobrania obiektu Place
.
Aby znaleźć miejsce na podstawie identyfikatora, wywołaj PlacesClient.fetchPlace()
, przekazując FetchPlaceRequest
.
Interfejs API zwraca FetchPlaceResponse
w Task
.
FetchPlaceResponse
zawiera obiekt Place
pasujący do podanego identyfikatora miejsca.
Poniższy przykładowy kod przedstawia wywołanie metody fetchPlace()
w celu pobrania szczegółów dotyczących określonego miejsca.
Kotlin
// Define a Place ID. val placeId = "INSERT_PLACE_ID_HERE" // Specify the fields to return. val placeFields = listOf(Place.Field.ID, Place.Field.NAME) // Construct a request object, passing the place ID and fields array. val request = FetchPlaceRequest.newInstance(placeId, placeFields) placesClient.fetchPlace(request) .addOnSuccessListener { response: FetchPlaceResponse -> val place = response.place Log.i(PlaceDetailsActivity.TAG, "Place found: ${place.name}") }.addOnFailureListener { exception: Exception -> if (exception is ApiException) { Log.e(TAG, "Place not found: ${exception.message}") val statusCode = exception.statusCode TODO("Handle error with given status code") } }
Java
// Define a Place ID. final String placeId = "INSERT_PLACE_ID_HERE"; // Specify the fields to return. final List<Place.Field> placeFields = Arrays.asList(Place.Field.ID, Place.Field.NAME); // Construct a request object, passing the place ID and fields array. final FetchPlaceRequest request = FetchPlaceRequest.newInstance(placeId, placeFields); placesClient.fetchPlace(request).addOnSuccessListener((response) -> { Place place = response.getPlace(); Log.i(TAG, "Place found: " + place.getName()); }).addOnFailureListener((exception) -> { if (exception instanceof ApiException) { final ApiException apiException = (ApiException) exception; Log.e(TAG, "Place not found: " + exception.getMessage()); final int statusCode = apiException.getStatusCode(); // TODO: Handle error with given status code. } });
Sprawdź stan otwarty
Metoda PlacesClient.isOpen(IsOpenRequest request)
zwraca obiekt IsOpenResponse
wskazujący, czy miejsce jest obecnie otwarte na podstawie czasu podanego w wywołaniu.
Ta metoda przyjmuje pojedynczy argument typu IsOpenRequest
, który zawiera:
- Obiekt
Place
lub ciąg znaków określający identyfikator miejsca. - Opcjonalna wartość czasu określająca czas w milisekundach od 1970-01-01T00:00:00Z. Jeśli nie podasz godziny, domyślnie zostanie użyta wartość bieżąca.
Ta metoda wymaga, aby w obiekcie Place
znajdowały się następujące pola:
Place.Field.BUSINESS_STATUS
Place.Field.CURRENT_OPENING_HOURS
Place.Field.OPENING_HOURS
Place.Field.UTC_OFFSET
Jeśli te pola nie są podane w obiekcie Place
lub jeśli przekazujesz identyfikator miejsca, metoda pobiera identyfikator, korzystając z PlacesClient.fetchPlace()
. Więcej informacji o tworzeniu obiektu Place z odpowiednimi polami znajdziesz w artykule Szczegóły miejsca.
Z poniższego przykładu dowiesz się, czy miejsce jest obecnie otwarte. W tym przykładzie przekazujesz tylko identyfikator miejsca do isOpen()
:
Kotlin
val isOpenCalendar: Calendar = Calendar.getInstance() val placeId = "ChIJD3uTd9hx5kcR1IQvGfr8dbk" val request: IsOpenRequest = try { IsOpenRequest.newInstance(placeId, isOpenCalendar.timeInMillis) } catch (e: IllegalArgumentException) { e.printStackTrace() return } val isOpenTask: Task<IsOpenResponse> = placesClient.isOpen(request) isOpenTask.addOnSuccessListener { response -> val isOpen = response.isOpen } // ...
Java
@NonNull Calendar isOpenCalendar = Calendar.getInstance(); String placeId = "ChIJD3uTd9hx5kcR1IQvGfr8dbk"; IsOpenRequest isOpenRequest; try { isOpenRequest = IsOpenRequest.newInstance(placeId, isOpenCalendar.getTimeInMillis()); } catch (IllegalArgumentException e) { e.printStackTrace(); return; } Task<IsOpenResponse> placeTask = placesClient.isOpen(isOpenRequest); placeTask.addOnSuccessListener( (response) -> isOpen = response.isOpen()); // ...
Następny przykład przedstawia wywołanie isOpen()
w miejscu, w którym przekazujesz obiekt Place
.
Obiekt Place
musi zawierać prawidłowy identyfikator miejsca:
Kotlin
val isOpenCalendar: Calendar = Calendar.getInstance() var place: Place val placeId = "ChIJD3uTd9hx5kcR1IQvGfr8dbk" // Specify the required fields for an isOpen request. val placeFields: List<Place.Field> = listOf( Place.Field.BUSINESS_STATUS, Place.Field.CURRENT_OPENING_HOURS, Place.Field.ID, Place.Field.OPENING_HOURS, Place.Field.UTC_OFFSET ) val placeRequest: FetchPlaceRequest = FetchPlaceRequest.newInstance(placeId, placeFields) val placeTask: Task<FetchPlaceResponse> = placesClient.fetchPlace(placeRequest) placeTask.addOnSuccessListener { placeResponse -> place = placeResponse.place val isOpenRequest: IsOpenRequest = try { IsOpenRequest.newInstance(place, isOpenCalendar.timeInMillis) } catch (e: IllegalArgumentException) { e.printStackTrace() return@addOnSuccessListener } val isOpenTask: Task<IsOpenResponse> = placesClient.isOpen(isOpenRequest) isOpenTask.addOnSuccessListener { isOpenResponse -> val isOpen = isOpenResponse.isOpen } // ... } // ...
Java
@NonNull Calendar isOpenCalendar = Calendar.getInstance(); String placeId = "ChIJD3uTd9hx5kcR1IQvGfr8dbk"; // Specify the required fields for an isOpen request. List<Place.Field> placeFields = new ArrayList<>(Arrays.asList( Place.Field.BUSINESS_STATUS, Place.Field.CURRENT_OPENING_HOURS, Place.Field.ID, Place.Field.OPENING_HOURS, Place.Field.UTC_OFFSET )); FetchPlaceRequest request = FetchPlaceRequest.newInstance(placeId, placeFields); Task<FetchPlaceResponse> placeTask = placesClient.fetchPlace(request); placeTask.addOnSuccessListener( (placeResponse) -> { Place place = placeResponse.getPlace(); IsOpenRequest isOpenRequest; try { isOpenRequest = IsOpenRequest.newInstance(place, isOpenCalendar.getTimeInMillis()); } catch (IllegalArgumentException e) { e.printStackTrace(); return; } Task<IsOpenResponse> isOpenTask = placesClient.isOpen(isOpenRequest); isOpenTask.addOnSuccessListener( (isOpenResponse) -> isOpen = isOpenResponse.isOpen()); // ... }); // ...
Wyświetlaj atrybucje w swojej aplikacji
Jeśli aplikacja wyświetla informacje o miejscach, w tym opinie o nich, musi też wyświetlać informacje o ich źródle. Więcej informacji znajdziesz w artykule o atrybucjach.
Więcej informacji o identyfikatorach miejsc
Identyfikator miejsca używany w pakiecie Places SDK na Androida to ten sam identyfikator co w Places API. Każdy identyfikator miejsca może odnosić się tylko do jednego miejsca, ale jedno miejsce może mieć więcej niż 1 identyfikator. Istnieją też inne okoliczności, które mogą spowodować, że miejsce otrzyma nowy identyfikator miejsca. Może się tak np. zdarzyć, gdy firma przeprowadzi się w inne miejsce.
Jeśli podasz identyfikator miejsca, w odpowiedzi wyświetli się zawsze to samo miejsce (o ile miejsce nadal istnieje). Pamiętaj jednak, że odpowiedź może zawierać identyfikator miejsca inny niż ten podany w Twoim żądaniu.
Więcej informacji znajdziesz w omówieniu identyfikatorów miejsc.