Szczegóły miejsc

Wybierz platformę: Android iOS JavaScript Usługa internetowa

Pakiet SDK Miejsc na Androida zapewnia Twojej aplikacji szczegółowe informacje o miejscach, w tym ich nazwę i adres, lokalizację geograficzną określoną jako współrzędne geograficzne, typ miejsca (np. klub nocny, sklep zoologiczny, muzeum) i wiele innych. Aby uzyskać dostęp do informacji o konkretnym miejscu, możesz użyć identyfikatora miejsca – stałego identyfikatora, który jednoznacznie identyfikuje to miejsce.

Szczegóły miejsca

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 umieścić miejsce na podstawie identyfikatora.
• Zadzwoń pod numer PlacesClient.findCurrentPlace() – zapoznaj się z przewodnikiem, aby uzyskać informacje o bieżącym miejscu.
  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 sekcji Obsługa pól pakietu Places SDK for Android.

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, które określają dane do zwrócenia. Ta lista należy rozważyć, ponieważ wpływa na koszt każdego żądania.

Ponieważ dane o miejscach nie mogą być puste, zwracane są tylko te wyniki z danymi (jeśli na przykład żądane miejsce nie zawiera zdjęć, pole photos nie będzie widoczne).

W przykładzie poniżej przesyłamy 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 placeFields = Arrays.asList(Place.Field.NAME, Place.Field.RATING, Place.Field.OPENING_HOURS);

Uwaga: pakiety SDK Miejsc na Androida i Places SDK na Androida (nowego) obsługują różne modele cenowe. Oznacza to, że cena za wywołanie zależy od żądanych pól i używanej wersji pakietu SDK. Szczegółowe informacje o cenach obu pakietów SDK znajdziesz w artykule Korzystanie i płatności.

Dostęp do pól danych obiektu Place

Po uzyskaniu obiektu Place użyj go, 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 dla tego miejsca. Komponenty te służą do wyodrębniania uporządkowanych informacji o adresie miejsca (np. w znalezieniu miasta, w którym znajduje się dane miejsce). Nie używaj tych komponentów do formatowania adresów. Zamiast tego użyj metody getAddress(), która udostępnia zlokalizowany adres.
• getId() – identyfikator tekstowy miejsca. Więcej informacji o identyfikatorach miejsc znajdziesz w pozostałej części tej strony.
• getLatLng() – lokalizacja geograficzna miejsca określona jako szerokość i długość geograficzna.
• getName() – nazwa miejsca.

• getOpeningHours() – OpeningHours miejsca. Wywołaj OpeningHours.getWeekdayText(), aby zwrócić listę ciągów znaków, które reprezentują godziny otwarcia i zamknięcia dla każdego dnia tygodnia. Wywołaj OpeningHours.getPeriods(), aby zwrócić listę obiektów period z bardziej szczegółowymi informacjami, które odpowiadają danym dostarczonym przez getWeekdayText().

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

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

• isOpen() – wartość logiczna wskazująca, czy miejsce jest obecnie otwarte. Jeśli nie podasz godziny, domyślnie zostanie użyta wartość bieżąca. Zwracana jest wartość isOpen tylko wtedy, gdy dostępne są zarówno wartości Place.Field.UTC_OFFSET, jak i Place.Field.OPENING_HOURS. Aby zapewnić dokładność wyników, 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ładamy, że firma działa. Obejrzyj ten film, aby dowiedzieć się, jak używać właściwości isOpen z informacjami o miejscu.

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

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

      

Dostęp do danych Miejsc dodanych w wersji 3.3.0

Pakiet SDK Miejsc na Androida w wersji 3.3.0 dodaje nowe dane do Place:

• Typy miejsc: nowe wartości typu powiązane z miejscem.
• Opinie: maksymalnie 5 opinii o miejscu.
• Name language code (Kod języka nazwy): kod języka nazwy miejsca.

W sekcjach poniżej dowiesz się, jak uzyskać dostęp do tych nowych danych.

Uwaga: nowy pakiet SDK obsługuje tylko nowe dane Place w Javie.

Dostęp do nowych typów miejsc

Z każdym miejscem może być powiązana co najmniej 1 wartość typu. Pakiet Miejsca SDK na Androida w wersji 3.3.0 dodaje wiele nowych wartości typów. Pełną listę znajdziesz w sekcji Rozwinięte typy miejsc.

W pakiecie Miejsca SDK na Androida w wersji 3.2.0 i wcześniejszych została użyta metoda Place.getTypes(), która pozwala uzyskać dostęp do wartości typu powiązanych z miejscem. Place.getTypes() zwraca listę typów w postaci wartości wyliczeniowych zdefiniowanych przez Place.Types.

Metoda Place.getTypes() jest wycofana z pakietu Places SDK na Androida w wersji 3.3.0. W okresie wycofania możesz nadal korzystać z tej funkcji, ale przenieś swoje aplikacje, aby korzystały z usługi Place.getPlaceTypes().

Metoda Place.getPlaceTypes() zwraca wartości typu w formie listy wartości ciągu znaków. Zwracane wartości zależą od wersji pakietu Places SDK dla Androida:

• Pakiet SDK Miejsc na Androida (nowy): zwraca ciągi znaków zdefiniowane w tabelach A i B w typach miejsc (nowe), z uwzględnieniem wszystkich dodanych typów miejsc dodanych w wersji 3.3.0.
• Pakiet SDK Miejsc na Androida: zwraca wyliczenia zdefiniowane przez Place.Types, które nie obejmują nowych typów dodanych w wersji 3.3.0.

Najważniejsze różnice między tymi wersjami pakietu SDK znajdziesz w artykule Wybieranie wersji pakietu SDK.

Dostęp do opinii o miejscu

Pakiet SDK Miejsc na Androida (nowy) dodaje klasę Review, która zawiera opinię o danym miejscu. Obiekt Place może zawierać maksymalnie 5 opinii.

Klasa Review może też zawierać informacje o autorze. Jeśli wyświetlasz opinię w aplikacji, musisz też uwzględnić wszelkie informacje o ich źródle i autorze. Więcej informacji znajdziesz w artykule Wyświetlanie opinii.

Aby wypełnić obiekt Place opiniami, musisz:

1. Włącz nowy pakiet SDK podczas konfigurowania projektu Google Cloud.
2. Zainicjuj nowy pakiet SDK w aktywności lub fragmencie.
3. Uwzględnij Place.Field.REVIEWS w liście pól w prośbie o szczegóły miejsca.
4. Zadzwoń pod numer PlacesClient.fetchPlace(). Pole opinii nie jest obsługiwane przez PlacesClient.findCurrentPlace().
5. Aby uzyskać dostęp do pola danych opinii w obiekcie Place, użyj metody Place.getReviews().

Dostęp do kodu języka nazwy miejsca

Istniejąca metoda Place.getName() zwraca ciąg tekstowy zawierający nazwę miejsca. Aby wypełnić obiekt Place nazwą miejsca, musisz uwzględnić pole Place.Field.NAME na liście pól w żądaniu informacji o miejscu.

Obiekt Place zawiera teraz kod języka ciągu nazwy. Aby wypełnić obiekt Place kodem języka, musisz:

1. Włącz nowy pakiet SDK podczas konfigurowania projektu Google Cloud.
2. Zainicjuj nowy pakiet SDK w aktywności lub fragmencie.
3. Dodaj Place.Field.NAME do listy pól żądania. Ta wartość pozwala skonfigurować odpowiedź tak, aby w obiekcie Place uwzględniła zarówno nazwę miejsca, jak i kod języka.
4. Zadzwoń pod numer PlacesClient.fetchPlace(). Pole PlacesClient.findCurrentPlace() nie obsługuje pola kodu języka.
5. Aby uzyskać dostęp do pola kodu języka w obiekcie Place, użyj metody Place.getNameLanguageCode().

Ustaw kod regionu w wersji 3.3.0

Pakiet Miejsca SDK na Androida (nowy) dodaje parametr żądania kodu regionu do właściwości Place Details. Kod regionu służy do formatowania odpowiedzi, określanej jako wartość dwuznakowego kodu CLDR. Ten parametr może też mieć wpływ na odchylenie wyników wyszukiwania. Brak wartości domyślnej. Aby ustawić kod regionu, musisz włączyć nowy pakiet SDK.

Jeśli nazwa kraju w polu adresu w odpowiedzi jest zgodna z kodem regionu, kod kraju jest pomijany w adresie.

Większość kodów CLDR jest taka sama jak kody ISO 3166-1, z pewnymi istotnymi wyjątkami. Na przykład krajowa domena w Wielkiej Brytanii to „uk” (.co.uk), a kod ISO 3166-1 to „gb” (technicznie rzecz biorąc, podmiot należący do „Wielkiej Brytanii Wielkiej Brytanii i Irlandii Północnej”). Parametr może wpływać na wyniki w zależności od obowiązującego prawa.

Znajdź miejsce na podstawie dokumentu tożsamości

Identyfikator miejsca to identyfikator tekstowy, który jednoznacznie identyfikuje miejsce. W pakiecie SDK Miejsc na Androida możesz pobrać identyfikator miejsca, wywołując metodę Place.getId(). Usługa Autouzupełnianie miejsca zwraca też identyfikator każdego miejsca, który 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 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.

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

      

Możesz użyć CancellationToken, aby spróbować anulować prośbę dotyczącą dowolnej z klas żądania (na przykład FetchPlaceRequest). Anulowanie jest możliwe z należytą starannością. Po wysłaniu prośby o anulowanie nie zostanie zwrócona żadna odpowiedź. Wydanie tokena anulowania NIE gwarantuje anulowania danego żądania i nadal możemy za nie zapłacić, nawet jeśli nie otrzymasz odpowiedzi.

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.
  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 godziny, domyślnie zostanie użyta wartość bieżąca.

Ta metoda wymaga, aby w obiekcie Place znajdowały się następujące 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 pobiera identyfikator, korzystając z PlacesClient.fetchPlace(). Więcej informacji o tworzeniu obiektu Place z odpowiednimi polami znajdziesz w artykule Szczegóły miejsca.

Uwaga: za połączenia z numerem fetchPlace() w przypadku domen Place.Field.UTC_OFFSET i Place.Field.BUSINESS_STATUS za połączenia z usługą fetchPlace() naliczamy opłaty za podstawowe dane w usłudze Miejsca. Opłata za kod SKU danych kontaktowych Miejsc Google jest naliczana za połączenia z numerem fetchPlace() w przypadku domen Place.Field.CURRENT_OPENING_HOURS i Place.Field.OPENING_HOURS.

Z poniższego przykładu dowiesz się, czy miejsce jest obecnie otwarte. W tym przykładzie przekazujesz tylko identyfikator miejsca do isOpen():

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 przedstawia wywołanie 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świetlaj atrybucje w swojej aplikacji

Jeśli aplikacja wyświetla informacje o miejscach, w tym opinie o nich, musi też wyświetlać informacje o ich źródle. 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 co w 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ą też inne okoliczności, które mogą spowodować, że miejsce otrzyma nowy identyfikator miejsca. Może się tak np. zdarzyć, gdy firma przeprowadzi się w inne miejsce.

Jeśli podasz identyfikator miejsca, w odpowiedzi wyświetli się zawsze to samo miejsce (o ile miejsce nadal istnieje). Pamiętaj jednak, że odpowiedź może zawierać identyfikator miejsca inny niż ten podany w Twoim żądaniu.

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