Pakiet SDK Miejsc na Androida dostarcza aplikacji rozbudowane informacje o miejscach, w tym ich nazwę i adres, położenie geograficzne określone we współrzędnych szerokości i długości geograficznej, rodzaj miejsca (np. klub nocny, sklep zoologiczny, muzeum) itp. 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 ustalić miejsce na podstawie identyfikatora. - Zadzwoń pod numer
PlacesClient.findCurrentPlace()
– zobacz przewodnik uzyskania bieżącego miejsca.
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, określając dane do zwrócenia. Ta lista należy wziąć pod uwagę, ponieważ wpływa na koszty każdego żądania.
Wyniki z danymi o miejscach nie mogą być puste, dlatego zwracane są tylko te wyniki z danymi (np. jeśli żądane miejsce nie zawiera zdjęć, w wyniku nie będzie pola photos
).
W tym przykładzie przekazujemy 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 powiązanych z nim metod, 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 tego miejsca. Komponenty te służą do wyodrębniania uporządkowanych informacji o adresie miejsca, np. w znalezieniu miasta, w którym się ono znajduje. Nie używaj tych komponentów do formatowania adresu. Zamiast tego użyj metodygetAddress()
, która udostępnia zlokalizowany adres.getId()
– tekstowy identyfikator miejsca. Więcej informacji o identyfikatorach miejsc znajdziesz w dalszej części tej strony.getLatLng()
– lokalizacja geograficzna miejsca podana za pomocą współrzędnych geograficznych.getName()
– nazwa miejsca.getOpeningHours()
–OpeningHours
miejsca. WywołajOpeningHours.getWeekdayText()
, aby zwrócić listę ciągów znaków reprezentujących godziny otwarcia i zamknięcia w poszczególnych dniach 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, igetSecondaryOpeningHours()
, która zwraca dodatkowe godziny otwarcia tego miejsca w ciągu najbliższych 7 dni.isOpen()
– wartość logiczna wskazująca, czy miejsce jest obecnie otwarte. Jeśli nie określisz godziny, domyślnie zostanie użyta wartość domyślna. Zwracana jest wartośćisOpen
tylko wtedy, gdy dostępne są zarówno funkcjePlace.Field.UTC_OFFSET
, jak iPlace.Field.OPENING_HOURS
. Aby zapewnić dokładne wyniki, w pierwotnej prośbie o miejsce trzeba wypełnić polaPlace.Field.BUSINESS_STATUS
iPlace.Field.UTC_OFFSET
. Jeśli nie prześlesz tego żądania, uznamy, ż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 danym miejscem.
- Opinie: maksymalnie 5 opinii o danym miejscu.
- Kod języka nazwy: kod języka nazwy miejsca.
Aby uzyskać dostęp do tych danych, musisz włączyć pakiet Places SDK dla Androida (nowego). Różnice między kluczami występującymi między 2 wersjami pakietu SDK znajdziesz w artykule Wybieranie wersji pakietu SDK.
Poniżej opisujemy, jak uzyskać dostęp do tych danych.
Dostęp do nowych typów miejsc
Z każdym miejscem może być powiązana co najmniej 1 wartość typu. Pakiet SDK Miejsc 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 SDK Miejsc na Androida w wersji 3.2.0 lub starszej użyto metody Place.getTypes()
, aby uzyskać dostęp do wartości typu powiązanych z miejscem. Place.getTypes()
zwraca listę typów jako wartości enum zdefiniowane przez Place.Types
.
Metoda Place.getPlaceTypes()
zwraca wartości typu w formie listy wartości ciągów. Zwrócone 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 zasadę
Place.Types
, która nie obejmuje nowych typów dodanych w wersji 3.3.0.
Najważniejsze różnice między tymi 2 wersjami pakietu SDK znajdziesz w artykule Wybieranie wersji pakietu SDK.
Dostęp do opinii o miejscach
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ż podać wszelkie informacje o 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.
- W prośbie o szczegóły miejsca dodaj
Place.Field.REVIEWS
. - 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 prośbie o szczegóły miejsca.
Obiekt Place
zawiera teraz kod języka ciągu znaków 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
była uwzględniana zarówno nazwa miejsca, jak i kod języka. - Zadzwoń pod numer
PlacesClient.fetchPlace()
.PlacesClient.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 SDK Miejsc na Androida (nowy) dodaje do informacji o miejscu parametr żądania kodu regionu. Kod regionu jest używany do formatowania odpowiedzi, określony jako wartość dwuznakowego kodu CLDR. Ten parametr może też mieć wpływ na wyniki 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 identyczna z kodami ISO 3166-1 z kilkoma wyjątkami. Na przykład domena ccTLD w Wielkiej Brytanii to „uk” (.co.uk), a kod ISO 3166-1 to „gb” (technicznie oznacza to podmiot należący do „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 identyfikatora
Identyfikator miejsca to tekstowy identyfikator, który jednoznacznie identyfikuje miejsce. Identyfikator miejsca możesz pobrać z pakietu Places SDK na Androida, wywołując metodę Place.getId()
.
Usługa Autouzupełnianie miejsca zwraca też identyfikator każdego miejsca, które 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 kod 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 z zakresu 1970-01-01T00:00:00Z. Jeśli nie określisz godziny, domyślnie zostanie użyta wartość domyślna.
Ta metoda wymaga, aby obiekt Place
zawierał te 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 przekazujesz identyfikator miejsca, metoda używa do ich pobrania PlacesClient.fetchPlace()
. Więcej informacji o tworzeniu obiektu Place wraz z wymaganymi polami znajdziesz w artykule Szczegóły miejsca.
Z przykładu poniżej dowiesz się, czy miejsce jest obecnie otwarte. W tym przykładzie przekazujesz identyfikator miejsca tylko do funkcji 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świetlanie atrybucji w aplikacji
Jeśli aplikacja wyświetla informacje o miejscach, w tym opinie o nich, musi też wyświetlać wszelkie informacje o nich. 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, który jest używany w Places API. Każdy identyfikator miejsca może odnosić się tylko do jednego miejsca, ale dane 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 na przykład zdarzyć, jeśli firma przeprowadzi się w inne miejsce.
Gdy poprosisz o podanie miejsca, podając identyfikator miejsca, możesz mieć pewność, że w odpowiedzi zawsze wyświetli się to samo miejsce (o ile miejsce nadal istnieje). Pamiętaj jednak, że odpowiedź może zawierać inny identyfikator miejsca niż ten podany w Twoim żądaniu.
Więcej informacji znajdziesz w omówieniu identyfikatorów miejsc.