Szczegóły miejsc

Places SDK na Androida dostarcza Twojej aplikacji bogate informacje o miejscach, w tym nazwę i adres miejsca, położenie geograficzne określone jako współrzędne szerokości i długości geograficznej, typ miejsca (np. klub nocny, sklep zoologiczny, muzeum) i inne. Aby uzyskać dostęp do tych informacji w przypadku konkretnego miejsca, możesz użyć identyfikatora miejsca, czyli stabilnego identyfikatora, który jednoznacznie identyfikuje dane miejsce.

Informacje o miejscu

Obiekt Place zawiera informacje o konkretnym miejscu. Obiekt Place możesz uzyskać w następujący sposób:

• Zadzwoń na numer PlacesClient.fetchPlace() – zapoznaj się z przewodnikiem dotyczącym pobierania danych o miejscu na podstawie identyfikatora.
• Zadzwoń PlacesClient.findCurrentPlace() – zapoznaj się z przewodnikiem dotyczącym uzyskiwania bieżącego miejsca.
  Chociaż PlacesClient.fetchPlace() obsługuje wszystkie pola danych o miejscach, PlacesClient.findCurrentPlace() obsługuje tylko podzbiór pól danych o miejscach. Listę pól, których nie obsługuje findCurrentPlace(), znajdziesz w artykule Obsługa pól w pakiecie SDK Miejsc na Androida.

Gdy wysyłasz żądanie dotyczące miejsca, musisz określić, jakie dane o miejscu mają zostać zwrócone. Aby to zrobić, prześlij listę wartości Place.Field określających dane, które mają zostać zwrócone. Ta lista jest ważna, ponieważ wpływa na koszt każdego zapytania.

Wyniki danych o miejscach nie mogą być puste, dlatego zwracane są tylko wyniki z danymi. Jeśli na przykład miejsce, którego dotyczy prośba, nie ma żadnych zdjęć, pole photosnie będzie widoczne w wyniku.

W tym przykładzie lista z 3 wartościami Place.Field służy do określenia danych zwróconych przez żądanie:

KotlinJava

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

Po uzyskaniu obiektu Place możesz używać jego metod, aby uzyskać dostęp do pól danych określonych w żądaniu. Jeśli w obiekcie Place brakuje pola, powiązana metoda zwraca wartość null. Poniżej przedstawiamy kilka przykładów dostępnych metod.

Pełną listę wszystkich metod znajdziesz w Placedokumentacji interfejsu API.

• getAddress() – adres miejsca w czytelnym formacie.
• getAddressComponents() – Listkomponentów adresu tego miejsca. Te komponenty są udostępniane w celu wyodrębniania uporządkowanych informacji o adresie miejsca, na przykład miasta, w którym się ono znajduje. Nie używaj tych komponentów do formatowania adresów. Zamiast tego wywołaj funkcję getAddress(), która zwraca sformatowany adres w języku lokalnym.
• getId() – tekstowy identyfikator miejsca. Więcej informacji o identyfikatorach miejsc znajdziesz w dalszej części tej strony.
• getLatLng() – lokalizacja geograficzna miejsca, określona jako współrzędne geograficzne.
• getName() – nazwa miejsca.

• getOpeningHours() – OpeningHoursmiejsca. Wywołanie OpeningHours.getWeekdayText() zwraca listę ciągów tekstowych reprezentujących godziny otwarcia i zamknięcia w każdym dniu tygodnia. Wywołaj metodę OpeningHours.getPeriods(), aby zwrócić listę obiektów period z bardziej szczegółowymi informacjami, które są równoważne danym z metody getWeekdayText().

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

  Obiekt Place zawiera też metodę getCurrentOpeningHours(), która zwraca godziny otwarcia obiektu w ciągu najbliższych 7 dni, oraz getSecondaryOpeningHours(), która zwraca dodatkowe godziny otwarcia obiektu 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 ustawiona bieżąca chwila. Wartość isOpen zostanie zwrócona tylko wtedy, gdy dostępne są wartości Place.Field.UTC_OFFSET i Place.Field.OPENING_HOURS. Aby uzyskać dokładne wyniki, w pierwotnym żądaniu dotyczącego miejsca podaj pola Place.Field.BUSINESS_STATUS i Place.Field.UTC_OFFSET. Jeśli nie zostanie to poproszone, przyjmuje się, że firma jest aktywna. Aby dowiedzieć się, jak używać isOpen w przypadku szczegółów miejsca, obejrzyj ten film.

  Uwaga: ta metoda została wycofana. Zamiast tego użyj polecenia PlacesClient.isOpen(IsOpenRequest request). Więcej informacji znajdziesz w sekcji Pobieranie stanu otwartego.

Oto kilka przykładów:

KotlinJava

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

      

Pobieranie miejsca według identyfikatora

Identyfikator miejsca to tekstowy identyfikator jednoznacznie identyfikujący miejsce. W pakiecie SDK Miejsc na Androida możesz pobrać identyfikator miejsca, wywołując funkcję Place.getId(). Usługa autouzupełniania miejsc zwraca również identyfikator każdego miejsca, które pasuje do podanego zapytania i filtra. Możesz zapisać identyfikator miejsca i użyć go do ponownego pobrania obiektu Place.

Aby uzyskać miejsce na podstawie identyfikatora, wywołaj funkcję PlacesClient.fetchPlace(), podając parametr FetchPlaceRequest.

Interfejs API zwracaFetchPlaceResponsew Task. FetchPlaceResponse zawiera obiekt Place odpowiadający podanemu identyfikatorowi miejsca.

Poniższy przykład kodu pokazuje wywołanie funkcji fetchPlace() w celu uzyskania szczegółów określonego miejsca.

KotlinJava

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

      

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

Możesz użyć CancellationToken, aby spróbować anulować żądanie do dowolnej klasy żądań (na przykład FetchPlaceRequest). Anulowanie odbywa się zgodnie z zasadą dołożenia wszelkich starań. Po wysłaniu prośby o anulowanie nie otrzymasz odpowiedzi. Wydanie tokena anulowania NIE gwarantuje, że konkretne żądanie zostanie anulowane. Możesz nadal zostać obciążony opłatą za żądanie, nawet jeśli nie otrzymasz odpowiedzi.

Pobieranie stanu otwartości

Metoda PlacesClient.isOpen(IsOpenRequest request) zwraca obiekt IsOpenResponse, który wskazuje, czy dane miejsce jest obecnie otwarte na podstawie czasu określonego 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.
  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, domyślnie zostanie ustawiona bieżąca chwila.

Ta metoda wymaga, aby w obiekcie Place występował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ą dostępne w obiekcie Place lub jeśli przekazujesz identyfikator miejsca, metoda używa parametru PlacesClient.fetchPlace() do ich pobierania. Więcej informacji o tworzeniu obiektu Miejsce z wymaganymi polami znajdziesz w sekcji Szczegóły miejsca.

Uwaga: za połączenia z numerem fetchPlace() w wersji Place.Field.UTC_OFFSET i Place.Field.BUSINESS_STATUS pobierana jest opłata za poziom danych podstawowych w usłudze Places. SKU danych kontaktowych w usłudze Places jest naliczany za połączenia z numerem fetchPlace() w przypadku Place.Field.CURRENT_OPENING_HOURS i Place.Field.OPENING_HOURS.

W tym przykładzie określamy, czy dane miejsce jest obecnie otwarte. W tym przykładzie do funkcji isOpen() przekazujesz tylko identyfikator miejsca:

KotlinJava

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ępujący przykład pokazuje wywołanie funkcji isOpen(), do której przekazujesz obiekt Place. Obiekt Place musi zawierać prawidłowy identyfikator miejsca:

KotlinJava

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 informacji o pochodzeniu danych w aplikacji

Jeśli aplikacja wyświetla informacje o miejscach, w tym opinie o miejscach, musi też wyświetlać wszelkie informacje o źródłach. Więcej informacji znajdziesz w sekcji atrybucja.

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 miejsca. Istnieją też inne okoliczności, które mogą spowodować, że miejsce otrzyma nowy identyfikator. Może się tak zdarzyć, jeśli firma przeniesie się do nowej lokalizacji.

Gdy wysyłasz żądanie dotyczące miejsca, podając jego identyfikator, możesz mieć pewność, że w odpowiedzi zawsze otrzymasz informacje o tym samym miejscu (jeśli nadal istnieje). Pamiętaj jednak, że odpowiedź może zawierać identyfikator miejsca inny niż ten podany w prośbie.

Więcej informacji znajdziesz w artykule Omówienie identyfikatora miejsca.