Szczegóły miejsc

Deweloperzy z Europejskiego Obszaru Gospodarczego (EOG)

Jeśli Twój adres rozliczeniowy znajduje się w Europejskim Obszarze Gospodarczym, od 8 lipca 2025 r. do korzystania z usług będą miały zastosowanie Warunki korzystania z usługi Google Maps Platform w EOG. Funkcje różnią się w zależności od regionu. Więcej informacji

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.

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

  Uwaga: jeśli miejsce jest zawsze otwarte, okres jest reprezentowany jako niedziela o północy, a closeEvent ma wartość null.

  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.

  Uwaga: ta metoda została wycofana. Zamiast niego użyj polecenia PlacesClient.isOpen(IsOpenRequest request). Więcej informacji znajdziesz w artykule Sprawdzanie stanu otwarcia.

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 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 = 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.
    }
});

      

Uwaga: więcej informacji o inicjowaniu PlacesClient znajdziesz w artykule Inicjowanie klienta interfejsu Places API.

Możesz użyć CancellationToken, aby spróbować anulować żądanie w dowolnej klasie żądań (np. FetchPlaceRequest). Anulowanie jest wykonywane w miarę możliwości. Po wysłaniu prośby o anulowanie nie otrzymasz odpowiedzi. Wydanie tokena anulowania NIE gwarantuje, że konkretne żądanie zostanie anulowane, i możesz nadal ponosić opłaty za żądanie, nawet jeśli nie otrzymasz odpowiedzi.

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.
  Uwaga: obiekt Place musi zawierać prawidłowy 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.

Uwaga: za wywołania funkcji fetchPlace() w przypadku Place.Field.UTC_OFFSET i Place.Field.BUSINESS_STATUS naliczana jest opłata za podstawowy SKU danych usługi Miejsca. Za połączenia z fetchPlace() w przypadku Place.Field.CURRENT_OPENING_HOURS i Place.Field.OPENING_HOURS naliczana jest opłata za SKU danych kontaktowych Miejsc.

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 = 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ć 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.