Informacje o miejscu (starsza wersja)

Deweloperzy z Europejskiego Obszaru Gospodarczego (EOG)

Pakiet Places SDK na Androida (starsza wersja) udostępnia 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ć dostęp do tych informacji w przypadku konkretnego miejsca, możesz użyć identyfikatora miejsca, czyli stałego identyfikatora, który jednoznacznie identyfikuje 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 na temat pobierania 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.

.
  • 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 tekstowych reprezentujących godziny otwarcia i zamknięcia w poszczególnych dniach tygodnia. Wywołaj OpeningHours.getPeriods(), aby zwrócić listę obiektówperiod z bardziej szczegółowymi informacjami, które są równoważne danym dostarczanym przez getWeekdayText().

    Obiekt Place zawiera też 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 czasu, domyślnie zostanie użyty czas bieżący. isOpen zostanie zwrócony tylko wtedy, gdy dostępne są 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 otrzymamy takiej prośby, przyjmiemy, że firma działa. W tym filmie dowiesz się, jak używać isOpen z informacjami o miejscu.

Oto kilka przykładów:

Kotlin

        val name = place.displayName
        val address = place.formattedAddress
        val location = place.location

Java

    final CharSequence name = place.getDisplayName();
    final CharSequence address = place.getFormattedAddress();
    final LatLng location = place.getLocation();

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 funkcję Place.getId(). Usługa Autouzupełnianie miejsc 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, 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. Obiekt FetchPlaceResponse zawiera obiekt Place pasujący do podanego identyfikatora 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 = PlaceIdProvider.getRandomPlaceId()

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

// 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

        val name = place.displayName
        val address = place.formattedAddress
        val location = place.location

        binding.placeName.text = name
        binding.placeAddress.text = address
        if (location != null) {
            binding.placeLocation.text = getString(
                R.string.place_location, location.latitude, location.longitude
            )
        } else {
            binding.placeLocation.text = null
        }
        Log.i(TAG, "Place found: ${place.displayName}")
    }.addOnFailureListener { exception: Exception ->
        if (exception is ApiException) {
            val message = getString(R.string.place_not_found, exception.message)
            binding.placeName.text = message
            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 = PlaceIdProvider.getRandomPlaceId();

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

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

    final CharSequence name = place.getDisplayName();
    final CharSequence address = place.getFormattedAddress();
    final LatLng location = place.getLocation();

    binding.placeName.setText(name);
    binding.placeAddress.setText(address);
    if (location != null) {
        binding.placeLocation.setText(
                getString(R.string.place_location, location.latitude, location.longitude)
        );
    } else {
        binding.placeLocation.setText(null);
    }

    Log.i(TAG, "Place found: " + place.getDisplayName());
}).addOnFailureListener((exception) -> {
    if (exception instanceof ApiException apiException) {
        final String message = getString(R.string.place_not_found, apiException.getMessage());
        binding.placeName.setText(message);
        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, domyślnie zostanie użyty czas bieżący.

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 niezbędnymi polami znajdziesz w artykule Szczegóły miejsca.

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

Kotlin

val isOpenCalendar: Calendar = Calendar.getInstance()
val placeId = PlaceIdProvider.getRandomPlaceId()

val request: IsOpenRequest = try {
    IsOpenRequest.newInstance(placeId, isOpenCalendar.timeInMillis)
} catch (e: IllegalArgumentException) {
    Log.e("PlaceIsOpen", "Error: " + e.message)
    return
}
val isOpenTask: Task<IsOpenResponse> = placesClient.isOpen(request)
isOpenTask.addOnSuccessListener { response ->
    val isOpen = response.isOpen ?: false
    binding.isOpenByIdResult.text = getString(R.string.is_open_by_id, isOpen.toString())
    Log.d("PlaceIsOpen", "Is open by ID: $isOpen")
}
// ...

Java

@NonNull
Calendar isOpenCalendar = Calendar.getInstance();
String placeId = PlaceIdProvider.getRandomPlaceId();
IsOpenRequest isOpenRequest;

try {
    isOpenRequest = IsOpenRequest.newInstance(placeId, isOpenCalendar.getTimeInMillis());
} catch (IllegalArgumentException e) {
    Log.e("PlaceIsOpen", "Error: " + e.getMessage());
    return;
}

Task<IsOpenResponse> placeTask = placesClient.isOpen(isOpenRequest);

placeTask.addOnSuccessListener(
        (response) -> {
            final boolean isOpen = Boolean.TRUE.equals(response.isOpen());
            binding.isOpenByIdResult.setText(getString(R.string.is_open_by_id, String.valueOf(isOpen)));
            Log.d("PlaceIsOpen", "Is open by ID: " + isOpen);
        });
placeTask.addOnFailureListener((exception) -> {
    binding.isOpenByIdResult.setText(getString(R.string.is_open_by_id, "Error: " + exception.getMessage()));
    Log.e("PlaceIsOpen", "Error: " + exception.getMessage());
});

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 = PlaceIdProvider.getRandomPlaceId()
// 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.DISPLAY_NAME
)

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) {
        Log.e("PlaceIsOpen", "Error: " + e.message)
        return@addOnSuccessListener
    }
    val isOpenTask: Task<IsOpenResponse> = placesClient.isOpen(isOpenRequest)
    isOpenTask.addOnSuccessListener { isOpenResponse ->
        val isOpen = when (isOpenResponse.isOpen) {
            true -> getString(R.string.is_open)
            else -> getString(R.string.is_closed)
        }
        binding.isOpenByObjectResult.text = getString(
            R.string.is_open_by_object,
            place.displayName,
            isOpen
        )
        Log.d("PlaceIsOpen", "Is open by object: $isOpen")
    }
    // ...
}
// ...

Java

@NonNull
Calendar isOpenCalendar = Calendar.getInstance();
String placeId = PlaceIdProvider.getRandomPlaceId();
// 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.DISPLAY_NAME
));

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) {
                Log.e("PlaceIsOpen", "Error: " + e.getMessage());
                return;
            }
            Task<IsOpenResponse> isOpenTask = placesClient.isOpen(isOpenRequest);

            isOpenTask.addOnSuccessListener(
                    (isOpenResponse) -> {
                        final boolean isOpen = Boolean.TRUE.equals(isOpenResponse.isOpen());
                        binding.isOpenByObjectResult.setText(getString(R.string.is_open_by_object, place.getDisplayName(), String.valueOf(isOpen)));
                        Log.d("PlaceIsOpen", "Is open by object: " + isOpen);
                    });
            isOpenTask.addOnFailureListener(
                    (exception) -> { // also update the result text field
                        binding.isOpenByObjectResult.setText(getString(R.string.is_open_by_object, place.getDisplayName(), "Error: " + exception.getMessage()));
                        Log.e("PlaceIsOpen", "Error: " + exception.getMessage());
                    });
        });
placeTask.addOnFailureListener(
        (exception) -> {
            binding.isOpenByObjectResult.setText("Error: " + exception.getMessage());
            Log.e("PlaceIsOpen", "Error: " + exception.getMessage());

Wyświetlanie atrybucji w aplikacji

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

Więcej informacji o identyfikatorach miejsc

Identyfikator miejsca używany w pakiecie SDK Miejsc na Androida (starsza wersja) jest taki sam jak w interfejsie Places API (starsza wersja). 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 identyfikatora miejsca.