Pakiet SDK Miejsc na Androida zapewnia Twojej aplikacji szczegółowe informacje o miejscach, w tym nazwę i adres miejsca, położenie geograficzne podane jako współrzędne geograficzne, rodzaj miejsca (np. klub nocny, sklep zoologiczny, muzeum itd.). Aby uzyskać dostęp do informacji o konkretnym miejscu, możesz użyć identyfikatora miejsca – stabilnego identyfikatora, który jednoznacznie identyfikuje miejsce.
Szczegóły miejsca
Obiekt Place
zawiera informacje o konkretnym miejscu. Obiekt Place
możesz zablokować na kilka sposobów:
- Zadzwoń pod numer
PlacesClient.findCurrentPlace()
– zapoznaj się z przewodnikiem po pobieraniu aktualnego miejsca. - Zadzwoń pod numer
PlacesClient.fetchPlace()
– zapoznaj się z przewodnikiem po uzyskiwaniu dostępu do miejsca według identyfikatora.
Przesyłając prośbę o miejsce, musisz określić, które dane miejsca mają zostać zwrócone. Aby to zrobić, podaj listę wartości Place.Field określających dane do zwrócenia. Ta lista jest ważna, ponieważ ma wpływ na koszt każdego żądania.
Wyniki wyszukiwania miejsc nie mogą być puste, dlatego zwracane są tylko wyniki z danymi (jeśli na przykład w danym miejscu nie ma zdjęć, pole photos
nie pojawi się w wyniku).
W tym przykładzie przekazano listę 3 wartości Place.Field, by określić dane zwracane przez żądanie:
Java
// Specify the fields to return. final ListplaceFields = Arrays.asList(Place.Field.NAME, Place.Field.RATING, Place.Field.OPENING_HOURS);
Kotlin
// Specify the fields to return. val placeFields = listOf(Place.Field.NAME, Place.Field.RATING, Place.Field.OPENING_HOURS)
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 pola, powiązana z nim metoda zwraca wartość null. Poniżej znajdziesz przykłady kilku dostępnych metod.
Pełną listę wszystkich metod znajdziesz w dokumentacji API Place
.
getAddress()
– adres miejsca w formacie czytelnym dla człowieka.getAddressComponents()
–List
komponenty adresu tego miejsca. Komponenty służą do wyodrębniania uporządkowanych informacji o adresie miejsca, na przykład aby znaleźć miasto, w którym się ono znajduje. Nie używaj tych komponentów do formatowania adresu. Zamiast tego wywołajgetAddress()
, aby znaleźć zlokalizowany format adresu.getId()
– tekstowy identyfikator miejsca. Więcej informacji o identyfikatorach miejsc znajdziesz w dalszej części tej strony.getLatLng()
– położenie geograficzne miejsca określone jako współrzędne geograficzne.getName()
– nazwa miejsca.getOpeningHours()
–OpeningHours
miejsca. WywołajOpeningHours.getWeekdayText()
, aby wyświetlić listę ciągów znaków reprezentujących godziny otwarcia i zamknięcia każdego dnia tygodnia. WywołajOpeningHours.getPeriods()
, aby zwrócić listę obiektówperiod
z bardziej szczegółowymi informacjami odpowiadającymi danym podanym przezgetWeekdayText()
.Obiekt
Place
zawiera też metodęgetCurrentOpeningHours()
, która zwraca godziny działania miejsca w ciągu najbliższych 7 dni, a także obiektgetSecondaryOpeningHours()
, który zwraca dodatkowe godziny pracy danego miejsca w ciągu najbliższych 7 dni.isOpen()
– wartość logiczna wskazująca, czy miejsce jest obecnie otwarte. Jeśli nie podasz daty, zostanie użyta wartość domyślna. WartośćisOpen
zostanie zwrócona tylko wtedy, gdy będą dostępne zarówno elementyPlace.Field.UTC_OFFSET
, jak iPlace.Field.OPENING_HOURS
. Aby uzyskać dokładne wyniki, poproś o polaPlace.Field.BUSINESS_STATUS
iPlace.Field.UTC_OFFSET
w pierwotnym żądaniu miejsca. Jeśli nie pojawi się prośba, zakłada się, że firma działa. Obejrzyj ten film, by dowiedzieć się, jak używać właściwościisOpen
ze szczegółami miejsca.
Oto kilka prostych przykładów:
Java
final CharSequence name = place.getName(); final CharSequence address = place.getAddress(); final LatLng location = place.getLatLng();
Kotlin
val name = place.name val address = place.address val location = place.latLng
Znajdź miejsce według identyfikatora
Identyfikator miejsca to identyfikator tekstowy, który jednoznacznie identyfikuje miejsce. W pakiecie SDK Miejsc na Androida możesz pobrać identyfikator miejsca, wywołując funkcję Place.getId()
.
Usługa Autouzupełniaj 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 później do pobrania obiektu Place
.
Aby uzyskać miejsce według identyfikatora, wywołaj obiekt PlacesClient.fetchPlace()
, przekazując FetchPlaceRequest
.
Interfejs API zwraca błąd FetchPlaceResponse
w obiekcie Task
.
FetchPlaceResponse
zawiera obiekt Place
pasujący do podanego identyfikatora miejsca.
Przykład poniżej pokazuje, jak wywołać fetchPlace()
w celu uzyskania szczegółowych informacji o konkretnym miejscu.
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. } });
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") } }
Otwórz stan
Metoda PlacesClient.isOpen(IsOpenRequest request)
zwraca obiekt IsOpenResponse
wskazujący, czy miejsce jest obecnie otwarte, zgodnie z czasem określonym 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 daty, zostanie użyta wartość domyślna.
Ta metoda wymaga, aby w obiekcie Place
były dostępne te pola:
Place.Field.BUSINESS_STATUS
Place.Field.CURRENT_OPENING_HOURS
Place.Field.OPENING_HOURS
Place.Field.UTC_OFFSET
Jeśli nie podasz tych pól w obiekcie Place
lub przekażesz identyfikator miejsca, metoda użyje ich do pobrania danych z PlacesClient.fetchPlace()
. Więcej informacji o tworzeniu obiektu Place z wymaganymi polami znajdziesz w szczegółach miejsca.
Ten przykład określa, czy miejsce jest obecnie otwarte. W tym przykładzie identyfikator miejsca przekazujesz tylko do 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()); // ...
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 } // ...
W następnym przykładzie pokazano wywoływanie isOpen()
, gdzie przekazujesz obiekt Place
.
Obiekt Place
musi zawierać prawidłowy identyfikator miejsca:
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()); // ... }); // ...
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 } // ... } // ...
Wyświetlanie atrybucji w aplikacji
Gdy aplikacja wyświetla informacje o miejscu, musi też wyświetlać atrybucje. Zapoznaj się z dokumentacją dotyczącą atrybucji.
Więcej informacji o identyfikatorach miejsc
Identyfikator miejsca użyty w pakiecie Miejsc na Androida jest taki sam jak identyfikator w interfejsie 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. Są inne okoliczności, które mogą spowodować wygenerowanie nowego identyfikatora miejsca. Może się tak zdarzyć, jeśli firma przeniesie się na nową lokalizację.
Gdy określisz identyfikator miejsca, zyskasz pewność, że w odpowiedzi zawsze otrzymasz to samo miejsce (jeśli dane miejsce nadal istnieje). Pamiętaj jednak, że odpowiedź może zawierać identyfikator miejsca inny niż podany w żądaniu.
Więcej informacji znajdziesz w artykule Omówienie identyfikatorów miejsc.