Szczegóły miejsc

Wybierz platformę: Android iOS JavaScript Usługa internetowa

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.

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 ustalić miejsce na podstawie identyfikatora.
• Zadzwoń pod numer PlacesClient.findCurrentPlace() – zobacz przewodnik uzyskania bieżącego miejsca.
  PlacesClient.fetchPlace() obsługuje wszystkie pola danych o miejscu, ale PlacesClient.findCurrentPlace() obsługuje tylko podzbiór pól danych o miejscu. Listę pól, które NIE są obsługiwane przez findCurrentPlace(), znajdziesz w artykule o obsłudze pól pakietu Places SDK na Androida.

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:

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 pakiety SDK Miejsc na Androida (nowość) 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 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().

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

  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.

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

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 danym miejscem.
• Opinie: maksymalnie 5 opinii o danym miejscu.
• Kod języka nazwy: kod języka nazwy miejsca.

Aby uzyskać dostęp do tych danych, musisz włączyć pakiet Places SDK dla Androida (nowego). Różnice między kluczami występującymi między 2 wersjami pakietu SDK znajdziesz w artykule Wybieranie wersji pakietu SDK.

Poniżej opisujemy, jak uzyskać dostęp do tych danych.

Uwaga: nowy pakiet SDK obsługuje tylko nowe dane Place w języku Java.

Dostęp do nowych typów miejsc

Z każdym miejscem może być powiązana co najmniej 1 wartość typu. Pakiet SDK Miejsc 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 SDK Miejsc na Androida w wersji 3.2.0 lub starszej użyto metody Place.getTypes(), aby uzyskać dostęp do wartości typu powiązanych z miejscem. Place.getTypes() zwraca listę typów jako wartości enum zdefiniowane przez Place.Types.

Metoda Place.getTypes() jest wycofana z pakietu SDK Miejsc na Androida w wersji 3.3.0. Chociaż w okresie wycofania możesz nadal z niej korzystać, przenieś swoje aplikacje do Place.getPlaceTypes().

Metoda Place.getPlaceTypes() zwraca wartości typu w formie listy wartości ciągów. Zwrócone 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 zasadę Place.Types, która nie obejmuje nowych typów dodanych w wersji 3.3.0.

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

Dostęp do opinii o miejscach

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ż podać wszelkie informacje o 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. W prośbie o szczegóły miejsca dodaj Place.Field.REVIEWS.
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 prośbie o szczegóły miejsca.

Obiekt Place zawiera teraz kod języka ciągu znaków 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 była uwzględniana zarówno nazwa miejsca, jak i kod języka.
4. Zadzwoń pod numer PlacesClient.fetchPlace(). 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 SDK Miejsc na Androida (nowy) dodaje do informacji o miejscu parametr żądania kodu regionu. Kod regionu jest używany do formatowania odpowiedzi, określony jako wartość dwuznakowego kodu CLDR. Ten parametr może też mieć wpływ na wyniki 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 identyczna z kodami ISO 3166-1 z kilkoma wyjątkami. Na przykład domena ccTLD w Wielkiej Brytanii to „uk” (.co.uk), a kod ISO 3166-1 to „gb” (technicznie oznacza to podmiot należący do „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 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.

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ć żądanie dowolnej klasy żądania (na przykład FetchPlaceRequest). Anulowanie jest przeprowadzane w miarę możliwości. Po wysłaniu prośby o anulowanie nie otrzymasz żadnej odpowiedzi. Wystawienie tokena anulowania NIE gwarantuje, że konkretne żądanie zostanie anulowane. Możesz też ponieść opłatę za żądanie, 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 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.

Uwaga: opłata za SKU podstawowych danych w usłudze Miejsca jest naliczana za połączenia z numerem fetchPlace() w usługach Place.Field.UTC_OFFSET i Place.Field.BUSINESS_STATUS. Opłata za kod SKU danych kontaktowych Miejsc Google jest naliczana za połączenia z numerem fetchPlace() w przypadku numerów Place.Field.CURRENT_OPENING_HOURS i Place.Field.OPENING_HOURS.

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