Szczegóły miejsc

Wybierz platformę: Android iOS JavaScript Usługa internetowa

Places SDK na Androida dostarcza 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ące sposoby:

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 obecne w wyniku.

W tym przykładzie przekazywana jest lista 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 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 znajdziesz kilka przykładów dostępnych metod.

  • 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 zapewnia sformatowany adres w wersji zlokalizowanej.
  • getId() – tekstowy identyfikator miejsca. Więcej informacji o identyfikatorach miejsc znajdziesz w dalszej części tej strony.
  • getLatLng() – geograficzna lokalizacja 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 poszczególnych dniach tygodnia. Wywołanie OpeningHours.getPeriods() zwraca listę obiektów period z bardziej szczegółowymi informacjami, które są równoważne danym udostępnianym przez getWeekdayText().

    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 mieć pewność, że wyniki będą dokładne, w pierwotnym żądaniu przesłanym do Google 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.

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

Uzyskiwanie informacji o miejscu na podstawie 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łnianie miejsc zwraca również identyfikator każdego miejsca, które pasuje do podanych zapytania i filtru. 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.

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

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.
  • 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 artykule Szczegóły miejsca.

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

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ępujący przykład pokazuje wywołanie funkcji isOpen(), do której 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 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 tym samym identyfikatorem, który jest 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.