Szczegóły miejsc

Deweloperzy z Europejskiego Obszaru Gospodarczego (EOG)

Pakiet Places SDK na Androida udostępnia Twojej aplikacji szczegółowe informacje o miejscach, w tym nazwę i adres miejsca, lokalizację geograficzną określoną jako współrzędne geograficzne, typ miejsca (np. klub nocny, sklep zoologiczny, muzeum) i inne dane. Aby uzyskać te informacje o konkretnym miejscu, możesz użyć identyfikatora miejsca, czyli stałego identyfikatora, który jednoznacznie określa miejsce.

Informacje o miejscu

Obiekt Place zawiera informacje o konkretnym miejscu. Obiekt Place możesz uzyskać, wywołując PlacesClient.fetchPlace(). Więcej informacji znajdziesz w przewodniku po uzyskiwaniu miejsca według identyfikatora.

Gdy wysyłasz prośbę o miejsce, musisz określić, które dane o miejscu mają zostać zwrócone. Aby to zrobić, przekaż listę wartości Place.Field określających dane do zwrócenia. Ta lista jest ważna, ponieważ wpływa na koszt każdego żądania.

Wyniki danych o miejscach nie mogą być puste, dlatego zwracane są tylko wyniki miejsc zawierające dane. Jeśli na przykład w przypadku żądanego miejsca nie ma zdjęć, w wyniku nie będzie pola photos.

W tym przykładzie przekazywana jest lista 3 wartości Place.Field, aby określić dane zwracane przez żądanie:

Kotlin

// Specify the fields to return.
val placeFields = listOf(Place.Field.DISPLAY_NAME, Place.Field.RATING)

Java

// Specify the fields to return.
final List<Place.Field> placeFields = Arrays.asList(Place.Field.DISPLAY_NAME, Place.Field.RATING);

Dostęp do pól danych obiektu Place

Po uzyskaniu obiektu Place użyj jego metod, aby uzyskać dostęp do pól danych określonych w żądaniu. Jeśli pole nie występuje w obiekcie Place, powiązana metoda zwraca wartość null. Poniżej znajdziesz przykłady kilku dostępnych metod.

Place.
  • getAddress() – adres miejsca w formacie czytelnym dla człowieka.
  • getAddressComponents() – List komponentów adresu tego miejsca. Te komponenty służą do wyodrębniania uporządkowanych informacji o adresie miejsca, np. do znajdowania miasta, w którym się ono znajduje. Nie używaj tych komponentów do formatowania adresu. Zamiast tego wywołaj funkcję getAddress(), która zwraca sformatowany adres w odpowiednim języku.
  • getId() – identyfikator tekstowy miejsca. Więcej informacji o identyfikatorach miejsc znajdziesz w dalszej części tej strony.
  • getLatLng() – lokalizacja geograficzna miejsca określona za pomocą współrzędnych geograficznych.
  • getName() – nazwa miejsca.

  • getOpeningHours() – OpeningHours miejsca. Wywołaj OpeningHours.getWeekdayText(), aby zwrócić listę ciągów znaków reprezentujących godziny otwarcia i zamknięcia w poszczególnych dniach tygodnia. Wywołaj metodę OpeningHours.getPeriods(), aby zwrócić listę obiektów period zawierających bardziej szczegółowe informacje, które są równoważne danym dostarczanym przez metodę getWeekdayText().

    Obiekt Place zawiera też metody getCurrentOpeningHours(), która zwraca godziny otwarcia miejsca w ciągu najbliższych 7 dni, oraz 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 czasu, zostanie użyta wartość domyślna „teraz”. Wartość isOpen zostanie zwrócona tylko wtedy, gdy dostępne będą zarówno Place.Field.UTC_OFFSET, jak i Place.Field.OPENING_HOURS. Aby uzyskać dokładne wyniki, w pierwotnym żądaniu dotyczącym miejsca poproś o pola Place.Field.BUSINESS_STATUS i Place.Field.UTC_OFFSET. Jeśli nie poprosisz o to, założymy, że firma działa. Z tego filmu dowiesz się, jak używać isOpen ze szczegółami miejsca.

Oto kilka 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();

Pobieranie miejsca według identyfikatora

Identyfikator miejsca to tekstowy identyfikator, który jednoznacznie identyfikuje miejsce. W pakiecie SDK Miejsc na Androida możesz pobrać identyfikator miejsca, wywołując Place.getId(). Usługa Autouzupełnianie miejsc zwraca też identyfikator miejsca dla każdego miejsca, które pasuje do podanego zapytania i filtra. Możesz zapisać identyfikator miejsca i użyć go później, aby ponownie pobrać obiekt Place.

Aby uzyskać miejsce według identyfikatora, wywołaj PlacesClient.fetchPlace(), przekazując FetchPlaceRequest.

Interfejs API zwraca wartość FetchPlaceResponse w Task. Element FetchPlaceResponse zawiera obiekt Place zgodny z podanym identyfikatorem miejsca.

Poniższy przykład kodu pokazuje wywołanie funkcji fetchPlace() w celu uzyskania szczegółowych 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.
    }
});

Pobieranie stanu otwarcia

Metoda PlacesClient.isOpen(IsOpenRequest request) zwraca obiekt IsOpenResponse, który wskazuje, czy miejsce jest obecnie otwarte na podstawie czasu określonego w wywołaniu.

Ta metoda przyjmuje jeden 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 czasu, zostanie użyta wartość domyślna „teraz”.

Ta metoda wymaga, aby w obiekcie Place istniały 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 przekażesz identyfikator miejsca, metoda użyje PlacesClient.fetchPlace(), aby je pobrać. Wi��cej informacji o tworzeniu obiektu Place z wymaganymi polami znajdziesz w artykule Szczegóły miejsca.

Poniższy przykład pokazuje, jak sprawdzić, czy miejsce jest obecnie otwarte. W tym przykładzie do isOpen() przekazujesz tylko identyfikator miejsca:

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());
// ...

W następnym przykładzie pokazujemy wywołanie funkcji isOpen(), w którym przekazujemy 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

Gdy aplikacja wyświetla informacje o miejscu, w tym opinie o nim, musi też wyświetlać wszelkie atrybucje. Więcej informacji znajdziesz w sekcji Atrybucje.

Więcej informacji o identyfikatorach miejsc

Identyfikator miejsca używany w pakiecie SDK Miejsc na Androida jest taki sam jak identyfikator używany 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. Istnieją inne okoliczności, które mogą spowodować, że miejsce otrzyma nowy identyfikator. Może się tak zdarzyć na przykład wtedy, gdy firma przeniesie się do nowej lokalizacji.

Gdy wysyłasz prośbę o 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, który różni się od identyfikatora w Twojej prośbie.

Więcej informacji znajdziesz w omówieniu identyfikatorów miejsc.