Szczegóły miejsc

Pakiet SDK Miejsc na Androida dostarcza aplikacji rozbudowane informacje o miejscach, w tym ich nazwę i adres, położenie geograficzne określone we współrzędnych szerokości i długości geograficznej, rodzaj miejsca (np. klub nocny, sklep zoologiczny, muzeum) itp. Aby uzyskać dostęp do informacji o konkretnym miejscu, możesz użyć identyfikatora miejsca – stałego identyfikatora, który jednoznacznie identyfikuje to miejsce.

Informacje o miejscu

Obiekt Place dostarcza informacji o konkretnym miejscu. Aby uzyskać dostęp do obiektu Place, wykonaj te czynności:

• Zadzwoń pod numer PlacesClient.fetchPlace() – zapoznaj się z przewodnikiem, aby ustalić miejsce na podstawie identyfikatora.
• Zadzwoń pod numer PlacesClient.findCurrentPlace() – zobacz przewodnik uzyskania bieżącego miejsca.

Przy wysyłaniu prośby o miejsce musisz określić, które dane o miejscu chcesz zwrócić. Aby to zrobić, przekaż listę wartości Place.Field, określając dane do zwrócenia. Ta lista należy wziąć pod uwagę, ponieważ wpływa na koszty każdego żądania.

Wyniki z danymi o miejscach nie mogą być puste, dlatego zwracane są tylko te wyniki z danymi (np. jeśli żądane miejsce nie zawiera zdjęć, w wyniku nie będzie pola photos).

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

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

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

Dostęp do pól danych obiektu Place

Po uzyskaniu obiektu Place użyj powiązanych z nim metod, aby uzyskać dostęp do pól danych określonych w żądaniu. Jeśli tego pola nie ma w obiekcie Place, powiązana metoda zwraca wartość null. Poniżej przedstawiamy kilka przykładów 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. Komponenty te służą do wyodrębniania uporządkowanych informacji o adresie miejsca, np. w znalezieniu miasta, w którym się ono znajduje. Nie używaj tych komponentów do formatowania adresu. Zamiast tego użyj metody getAddress(), która udostępnia zlokalizowany adres.
• getId() – tekstowy identyfikator miejsca. Więcej informacji o identyfikatorach miejsc znajdziesz w dalszej części tej strony.
• getLatLng() – lokalizacja geograficzna miejsca podana 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 OpeningHours.getPeriods(), aby zwrócić listę obiektów period z bardziej szczegółowymi informacjami, które odpowiadają danym dostarczonym przez getWeekdayText().

  Obiekt Place zawiera też metodę getCurrentOpeningHours(), która zwraca godziny pracy danego miejsca w ciągu najbliższych 7 dni, i getSecondaryOpeningHours(), która zwraca dodatkowe godziny otwarcia tego miejsca w ciągu najbliższych 7 dni.

• isOpen() – wartość logiczna wskazująca, czy miejsce jest obecnie otwarte. Jeśli nie określisz godziny, domyślnie zostanie użyta wartość domyślna. Zwracana jest wartość isOpen tylko wtedy, gdy dostępne są zarówno funkcje Place.Field.UTC_OFFSET, jak i Place.Field.OPENING_HOURS. Aby zapewnić dokładne wyniki, w pierwotnej prośbie o miejsce trzeba wypełnić pola Place.Field.BUSINESS_STATUS i Place.Field.UTC_OFFSET. Jeśli nie prześlesz tego żądania, uznamy, że firma działa. Obejrzyj ten film, aby dowiedzieć się, jak używać właściwości isOpen z informacjami o miejscu.

Kilka prostych przykładów:

val name = place.name
val address = place.address
val location = place.latLng

      

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

      

Znajdź miejsce na podstawie identyfikatora

Identyfikator miejsca to tekstowy identyfikator, który jednoznacznie identyfikuje miejsce. Identyfikator miejsca możesz pobrać z pakietu Places SDK na Androida, wywołując metodę Place.getId(). Usługa Autouzupełnianie miejsca 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 do ponownego pobrania obiektu Place.

Aby znaleźć miejsce na podstawie identyfikatora, wywołaj PlacesClient.fetchPlace(), przekazując kod FetchPlaceRequest.

Interfejs API zwraca FetchPlaceResponse w Task. FetchPlaceResponse zawiera obiekt Place pasujący do podanego identyfikatora miejsca.

Poniższy przykładowy kod przedstawia wywołanie metody fetchPlace() w celu pobrania szczegółów dotyczących określonego miejsca.

// 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")
        }
    }

      

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

      

Sprawdź stan otwarty

Metoda PlacesClient.isOpen(IsOpenRequest request) zwraca obiekt IsOpenResponse wskazujący, czy miejsce jest obecnie otwarte na podstawie czasu podanego 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 z zakresu 1970-01-01T00:00:00Z. Jeśli nie określisz godziny, domyślnie zostanie użyta wartość domyślna.

Ta metoda wymaga, aby obiekt Place zawierał 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 przekazujesz identyfikator miejsca, metoda używa do ich pobrania PlacesClient.fetchPlace(). Więcej informacji o tworzeniu obiektu Place wraz z wymaganymi polami znajdziesz w artykule Szczegóły miejsca.

Z przykładu poniżej dowiesz się, czy miejsce jest obecnie otwarte. W tym przykładzie przekazujesz identyfikator miejsca tylko do funkcji 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
}
// ...

      

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

      

Następny przykład przedstawia wywołanie isOpen() w miejscu, w którym przekazujesz obiekt Place. Obiekt Place musi zawierać prawidłowy identyfikator miejsca:

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

      

@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

Jeśli aplikacja wyświetla informacje o miejscach, w tym opinie o nich, musi też wyświetlać wszelkie informacje o nich. Więcej informacji znajdziesz w artykule o atrybucjach.

Więcej informacji o identyfikatorach miejsc

Identyfikator miejsca używany w pakiecie Places SDK na Androida to ten sam identyfikator, który jest używany w Places API. Każdy identyfikator miejsca może odnosić się tylko do jednego miejsca, ale dane miejsce może mieć więcej niż 1 identyfikator. Istnieją też inne okoliczności, które mogą spowodować, że miejsce otrzyma nowy identyfikator miejsca. Może się tak na przykład zdarzyć, jeśli firma przeprowadzi się w inne miejsce.

Gdy poprosisz o podanie miejsca, podając identyfikator miejsca, możesz mieć pewność, że w odpowiedzi zawsze wyświetli się to samo miejsce (o ile miejsce nadal istnieje). Pamiętaj jednak, że odpowiedź może zawierać inny identyfikator miejsca niż ten podany w Twoim żądaniu.

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