Szczegóły miejsc

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:

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

// 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łaj getAddress(), 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łaj OpeningHours.getWeekdayText(), aby wyświetlić listę ciągów znaków reprezentujących godziny otwarcia i zamknięcia każdego dnia tygodnia. Wywołaj OpeningHours.getPeriods(), aby zwrócić listę obiektów period z bardziej szczegółowymi informacjami odpowiadającymi danym podanym przez getWeekdayText().

  Obiekt Place zawiera też metodę getCurrentOpeningHours(), która zwraca godziny działania miejsca w ciągu najbliższych 7 dni, a także obiekt getSecondaryOpeningHours(), 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 elementy Place.Field.UTC_OFFSET, jak i Place.Field.OPENING_HOURS. Aby uzyskać dokładne wyniki, poproś o pola Place.Field.BUSINESS_STATUS i Place.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ści isOpen ze szczegółami miejsca.

Oto kilka prostych przykładów:

final CharSequence name = place.getName();
final CharSequence address = place.getAddress();
final LatLng location = place.getLatLng();

      

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.

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

      

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

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

      

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:

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

      

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.