Szczegóły miejsc

Wybierz platformę: Android iOS JavaScript Usługa internetowa

Pakiet Places SDK na Androida dostarcza aplikacji szczegółowe informacje o miejscach, w tym ich nazwę i adres, lokalizację geograficzną określoną za pomocą współrzędnych geograficznych, rodzaj miejsca (np. klub nocny, sklep zoologiczny, muzeum) itd. Aby uzyskać dostęp do informacji o konkretnym miejscu, możesz użyć identyfikatora miejsca – stałego identyfikatora, który jednoznacznie identyfikuje miejsce.

Informacje o miejscu

Obiekt Place dostarcza informacji o konkretnym miejscu. Aby przejąć obiekt Place:

• Zadzwoń PlacesClient.fetchPlace() – przeczytaj przewodnik o uzyskaniu miejsca na podstawie identyfikatora.
• Zadzwoń: PlacesClient.findCurrentPlace() – przeczytaj przewodnik jak znaleźć aktualne miejsce.
  PlacesClient.fetchPlace() obsługuje wszystkie pola danych o miejscach, ale PlacesClient.findCurrentPlace() obsługuje tylko podzbiór pól danych o miejscach. Listę pól, które NIE są obsługiwane przez findCurrentPlace(), znajdziesz w artykule o obsłudze pól pakietu SDK Miejsc na Androida.

Zgłaszając prośbę o dane miejsce, musisz określić, które dane o nim mają zostać zwrócone. W tym celu przekaż listę wartości Place.Field, które określają dane do zwrócenia. Warto pamiętać o tej liście, ponieważ wpływa ona na koszt każdego żądania.

Wyniki z danymi o miejscach nie mogą być puste, dlatego zwracane są tylko wyniki miejsc z danymi (jeśli na przykład żądane miejsce nie ma zdjęć, w wyniku nie będzie pola photos).

Poniższy przykład przekazuje listę 3 wartości Place.Field, aby określić dane zwracane przez żądanie:

Kotlin

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

Java

// 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 obiektów Miejsc

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 tego pola, powiązana metoda zwraca wartość null. Poniżej przedstawiamy kilka przykładowych metod. Pełną listę wszystkich metod znajdziesz w dokumentacji interfejsu API Place.

• getAddress() – adres miejsca w formacie czytelnym dla człowieka.
• getAddressComponents() – List elementów adresu tego miejsca. Te komponenty są udostępniane na potrzeby wyodrębniania uporządkowanych informacji o adresie miejsca, np. w celu znalezienia miasta, w którym ono się znajduje. Nie używaj tych komponentów do formatowania adresu. Zamiast tego wywołaj funkcję getAddress(), która zapewni zlokalizowany sformatowany adres.
• getId() – tekstowy identyfikator miejsca. Więcej informacji o identyfikatorach miejsc znajdziesz w dalszej części tej strony.
• getLatLng() – lokalizacja geograficzna miejsca podana jako szerokość i długość geograficzna.
• 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ów period z bardziej szczegółowymi informacjami odpowiadającymi danym dostarczonym przez funkcję getWeekdayText().

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

  Obiekt Place zawiera również 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 żadnej godziny, domyślną wartością będzie teraz. Wartość isOpen zostanie zwrócona tylko wtedy, gdy dostępne są zarówno wartości Place.Field.UTC_OFFSET, jak i Place.Field.OPENING_HOURS. Aby wyniki były poprawne, poproś o pola Place.Field.BUSINESS_STATUS i Place.Field.UTC_OFFSET w pierwotnej prośbie o miejsce. Jeśli prośba nie zostanie wysłana, zakłada się, że firma działa. Aby dowiedzieć się, jak korzystać z elementu isOpen w informacjach o miejscu, obejrzyj ten film.

  Uwaga: ta metoda została wycofana. Zamiast niego użyj PlacesClient.isOpen(IsOpenRequest request). Więcej informacji znajdziesz w sekcji Uzyskiwanie informacji o stanie otwarcia.

Oto kilka prostych przykładów:

Kotlin

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

      

Java

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

      

Znajdź miejsce na podstawie identyfikatora

Identyfikator miejsca to identyfikator tekstowy jednoznacznie identyfikujący miejsce. W pakiecie SDK Places na Androida możesz pobrać identyfikator miejsca, wywołując metodę Place.getId(). Usługa Autouzupełnianie 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 do późniejszego pobrania obiektu Place.

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

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

Poniższy przykładowy kod pokazuje wywołanie fetchPlace() w celu uzyskania informacji o określonym miejscu.

Kotlin

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

      

Java

// 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 PlacesClient znajdziesz w artykule o inicjowaniu klienta Places API.

CancellationToken pozwala anulować żądanie wysłane do dowolnej z klas żądania (na przykład FetchPlaceRequest). Anulowanie odbywa się z najwyższą starannością. Po wysłaniu prośby o anulowanie nie otrzymasz odpowiedzi. Wystawienie tokena anulowania NIE gwarantuje anulowania danego żądania i może zostać naliczona opłata, nawet jeśli nie otrzymasz odpowiedzi.

Uzyskaj stan „Otwarty”

Metoda PlacesClient.isOpen(IsOpenRequest request) zwraca obiekt IsOpenResponse wskazujący, czy miejsce jest obecnie otwarte w godzinach określonych 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 żadnej godziny, domyślną wartością będzie teraz.

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

Uwaga: podstawowe dane SKU w usłudze Miejsca naliczane są za połączenia z numerem fetchPlace() w krajach Place.Field.UTC_OFFSET i Place.Field.BUSINESS_STATUS. Kod SKU danych kontaktowych pobiera opłaty za połączenia z numerem fetchPlace() Place.Field.CURRENT_OPENING_HOURS i Place.Field.OPENING_HOURS.

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

Kotlin

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

      

Java

@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 pokazuje wywoływanie funkcji isOpen() w miejscu, w którym przekazujesz obiekt Place. Obiekt Place musi zawierać prawidłowy identyfikator miejsca:

Kotlin

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

      

Java

@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świetl atrybucję w swojej aplikacji

Gdy aplikacja wyświetla informacje o miejscu, w tym opinie o nim, musi też wyświetlać informacje o źródłach. Więcej informacji znajdziesz w sekcji Atrybucje.

Więcej informacji o identyfikatorach miejsc

Identyfikator miejsca używany w pakiecie SDK Places 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 pojedyncze miejsce może mieć więcej niż 1 identyfikator miejsca. Istnieją też inne okoliczności, które mogą spowodować, że dane miejsce otrzyma nowy identyfikator. Może się tak na przykład zdarzyć, gdy firma przeprowadzi się w nowe miejsce.

Jeśli poprosisz o dane 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 inny niż w żądaniu.

Więcej informacji znajdziesz w omówieniu identyfikatora miejsca.