Pakiet Places SDK na Androida dostarcza aplikacji szczegółowe informacje o miejscach, w tym ich nazwę i adres, lokalizację geograficzną określoną za pomocą współrzędnych geograficznych, rodzaj miejsca (np. klub nocny, sklep zoologiczny, muzeum) itd. Aby uzyskać dostęp do informacji o konkretnym miejscu, możesz użyć identyfikatora miejsca – stałego identyfikatora, który jednoznacznie identyfikuje miejsce.
Informacje o miejscu
Obiekt Place
dostarcza informacji o konkretnym miejscu. Aby przejąć obiekt Place
:
- Zadzwoń
PlacesClient.fetchPlace()
– przeczytaj przewodnik o uzyskaniu miejsca na podstawie identyfikatora. - Zadzwoń:
PlacesClient.findCurrentPlace()
– przeczytaj przewodnik jak znaleźć aktualne miejsce.
Zgłaszając prośbę o dane miejsce, musisz określić, które dane o nim mają zostać zwrócone. W tym celu przekaż listę wartości Place.Field, które określają dane do zwrócenia. Warto pamiętać o tej liście, ponieważ wpływa ona na koszt każdego żądania.
Wyniki z danymi o miejscach nie mogą być puste, dlatego zwracane są tylko wyniki miejsc z danymi (jeśli na przykład żądane miejsce nie ma zdjęć, w wyniku nie będzie pola photos
).
Poniższy przykład przekazuje 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 List<Place.Field> placeFields = Arrays.asList(Place.Field.NAME, Place.Field.RATING, Place.Field.OPENING_HOURS);
Dostęp do pól danych obiektów Miejsc
Gdy uzyskasz obiekt Place
, użyj metod obiektu, aby uzyskać dostęp do pól danych określonych w żądaniu. Jeśli w obiekcie Place
brakuje tego pola, powiązana metoda zwraca wartość null. Poniżej przedstawiamy kilka przykładowych metod.
Pełną listę wszystkich metod znajdziesz w dokumentacji interfejsu API Place
.
getAddress()
– adres miejsca w formacie czytelnym dla człowieka.getAddressComponents()
–List
elementów adresu tego miejsca. Te komponenty są udostępniane na potrzeby wyodrębniania uporządkowanych informacji o adresie miejsca, np. w celu znalezienia miasta, w którym ono się znajduje. Nie używaj tych komponentów do formatowania adresu. Zamiast tego wywołaj funkcjęgetAddress()
, która zapewni zlokalizowany sformatowany adres.getId()
– tekstowy identyfikator miejsca. Więcej informacji o identyfikatorach miejsc znajdziesz w dalszej części tej strony.getLatLng()
– lokalizacja geograficzna miejsca podana jako szerokość i długość geograficzna.getName()
– nazwa miejsca.getOpeningHours()
–OpeningHours
miejsca. WywołajOpeningHours.getWeekdayText()
, aby zwrócić listę ciągów tekstowych 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 odpowiadającymi danym dostarczonym przez funkcjęgetWeekdayText()
.Obiekt
Place
zawiera również metodęgetCurrentOpeningHours()
, która zwraca godziny otwarcia miejsca w ciągu najbliższych 7 dni, oraz metodęgetSecondaryOpeningHours()
, która zwraca dodatkowe godziny otwarcia miejsca w ciągu najbliższych 7 dni.isOpen()
– wartość logiczna wskazująca, czy miejsce jest obecnie otwarte. Jeśli nie podasz żadnej godziny, domyślną wartością będzie teraz. WartośćisOpen
zostanie zwrócona tylko wtedy, gdy dostępne są zarówno wartościPlace.Field.UTC_OFFSET
, jak iPlace.Field.OPENING_HOURS
. Aby wyniki były poprawne, 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łada się, że firma działa. Aby dowiedzieć się, jak korzystać z elementuisOpen
w informacjach o miejscu, obejrzyj ten film.
Oto 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();
Znajdź miejsce na podstawie identyfikatora
Identyfikator miejsca to identyfikator tekstowy jednoznacznie identyfikujący miejsce. W pakiecie SDK Places na Androida możesz pobrać identyfikator miejsca, wywołując metodę Place.getId()
.
Usługa Autouzupełnianie miejsca zwraca też identyfikator miejsca dla każdego miejsca pasującego do podanego zapytania i filtra. Możesz zapisać identyfikator miejsca i użyć go do późniejszego pobrania obiektu Place
.
Aby uzyskać 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 pokazuje wywołanie fetchPlace()
w celu uzyskania informacji o określonym miejscu.
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. } });
Uzyskaj stan „Otwarty”
Metoda PlacesClient.isOpen(IsOpenRequest request)
zwraca obiekt IsOpenResponse
wskazujący, czy miejsce jest obecnie otwarte w godzinach określonych 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 żadnej godziny, domyślną wartością będzie teraz.
Ta metoda wymaga, aby w obiekcie Place
znajdowały się 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 jeśli przekazujesz identyfikator miejsca, metoda używa PlacesClient.fetchPlace()
do ich pobrania. Więcej informacji o tworzeniu obiektu Place z wymaganymi polami znajdziesz w artykule Szczegóły miejsca.
Poniższy przykład pokazuje, czy miejsce jest obecnie otwarte. W tym przykładzie do isOpen()
przekazujesz
identyfikator miejsca tylko:
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 pokazuje wywoływanie funkcji 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świetl atrybucję w swojej aplikacji
Gdy aplikacja wyświetla informacje o miejscu, w tym opinie o nim, musi też wyświetlać informacje o źródłach. Więcej informacji znajdziesz w sekcji Atrybucje.
Więcej informacji o identyfikatorach miejsc
Identyfikator miejsca używany w pakiecie SDK Places 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 pojedyncze miejsce może mieć więcej niż 1 identyfikator miejsca. Istnieją też inne okoliczności, które mogą spowodować, że dane miejsce otrzyma nowy identyfikator. Może się tak na przykład zdarzyć, gdy firma przeprowadzi się w nowe miejsce.
Jeśli poprosisz o dane miejsce, podając jego identyfikator, możesz mieć pewność, że w odpowiedzi zawsze otrzymasz to samo miejsce (jeśli nadal istnieje). Pamiętaj jednak, że odpowiedź może zawierać identyfikator miejsca inny niż w żądaniu.
Więcej informacji znajdziesz w omówieniu identyfikatora miejsca.