Place Details (Legacy)

Entwickler im Europäischen Wirtschaftsraum (EWR)

Das Places SDK for Android (Legacy) stellt Ihrer App umfangreiche Informationen zu Orten zur Verfügung, darunter Name und Adresse des Orts, die geografische Position als Breiten- und Längengrad, die Art des Orts (z. B. Nachtclub, Zoohandlung, Museum) und mehr. Wenn Sie auf diese Informationen für einen bestimmten Ort zugreifen möchten, können Sie die Orts-ID verwenden. Das ist eine stabile Kennung, die einen Ort eindeutig identifiziert.

Ortsdetails

Das Objekt Place liefert Informationen zu einem bestimmten Ort. Sie können ein Place-Objekt abrufen, indem Sie PlacesClient.fetchPlace() aufrufen. Weitere Informationen finden Sie im Hilfeartikel Place-Objekt anhand der ID abrufen.

Wenn Sie einen Ort anfragen, müssen Sie angeben, welche Ortsdaten zurückgegeben werden sollen. Übergeben Sie dazu eine Liste mit Place.Field-Werten, in der die zurückzugebenden Daten angegeben sind. Diese Liste ist ein wichtiger Aspekt, da sie sich auf die Kosten für jede Anfrage auswirkt.

Da Ergebnisse für „Place Details“-Anfragen nicht leer sein dürfen, werden nur Ergebnisse mit Daten zurückgegeben. Wenn für den Ort in der Anfrage z. B. keine Fotos vorhanden sind, ist das Feld photos nicht im Ergebnis enthalten.

Im folgenden Beispiel wird eine Liste mit drei Place.Field-Werten übergeben, um die von einer Anfrage zurückgegebenen Daten anzugeben:

Kotlin

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

Java

// Specify the fields to return.
final List<Place.Field> placeFields = Arrays.asList(Place.Field.DISPLAY_NAME, Place.Field.RATING);

Auf Datenfelder des Place-Objekts zugreifen

Nachdem Sie das Place-Objekt erhalten haben, verwenden Sie Methoden des Objekts, um auf die in der Anfrage angegebenen Datenfelder zuzugreifen. Wenn das Feld im Place-Objekt fehlt, gibt die zugehörige Methode „null“ zurück. Im Folgenden finden Sie Beispiele für einige der verfügbaren Methoden.

  • getAddress(): Die Adresse des Ortes in einem menschenlesbaren Format.
  • getAddressComponents(): ein List von Adresskomponenten für diesen Ort. Diese Komponenten dienen dazu, strukturierte Informationen zur Adresse eines Orts zu extrahieren, z. B. die Stadt, in der sich ein Ort befindet. Verwenden Sie diese Komponenten nicht für die Adressformatierung. Rufen Sie stattdessen getAddress() auf, um eine lokalisierte formatierte Adresse zu erhalten.
  • getId(): Die ID des Orts in Textform. Weitere Informationen zu Orts-IDs finden Sie auf dieser Seite.
  • getLatLng(): Der geografische Standort des Ortes, angegeben als Breiten- und Längengradkoordinaten.
  • getName(): Der Name des Ortes.

  • getOpeningHours(): Die OpeningHours des Ortes. Rufen Sie OpeningHours.getWeekdayText() auf, um eine Liste von Strings zurückzugeben, die die Öffnungs- und Schließzeiten für jeden Wochentag darstellen. Rufen Sie OpeningHours.getPeriods() auf, um eine Liste von period-Objekten mit detaillierteren Informationen zurückzugeben, die den von getWeekdayText() bereitgestellten Daten entsprechen.

    Das Objekt Place enthält auch die Methode getCurrentOpeningHours(), die die Öffnungszeiten eines Orts für die nächsten sieben Tage zurückgibt, und getSecondaryOpeningHours(), die die sekundären Öffnungszeiten eines Orts für die nächsten sieben Tage zurückgibt.

  • isOpen(): ein boolescher Wert, der angibt, ob der Ort derzeit geöffnet ist. Wenn keine Zeit angegeben ist, wird die aktuelle Zeit verwendet. isOpen wird nur zurückgegeben, wenn sowohl Place.Field.UTC_OFFSET als auch Place.Field.OPENING_HOURS verfügbar sind. Damit die Ergebnisse korrekt sind, müssen Sie die Felder Place.Field.BUSINESS_STATUS und Place.Field.UTC_OFFSET in Ihrer ursprünglichen Ortsanfrage angeben. Wenn nicht angefordert, wird davon ausgegangen, dass das Unternehmen geöffnet ist. In diesem Video erfahren Sie, wie Sie isOpen mit Place Details nutzen.

Beispiele:

Kotlin

        val name = place.displayName
        val address = place.formattedAddress
        val location = place.location

Java

                    final CharSequence name = place.getDisplayName();
                    final CharSequence address = place.getFormattedAddress();
                    final LatLng location = place.getLocation();

Ort nach ID anfordern

Die Orts-ID ist eine Kennung in Textform, die einen Ort eindeutig definiert. Im Places SDK for Android können Sie die ID eines Orts abrufen, indem Sie Place.getId() aufrufen. Der Dienst Place Autocomplete gibt außerdem für jeden Ort, der der angegebenen Suchanfrage und dem Filter entspricht, eine Orts-ID zurück. Sie können die Orts-ID speichern und später verwenden, um das Place-Objekt noch einmal abzurufen.

Wenn Sie einen Ort anhand der ID abrufen möchten, rufen Sie PlacesClient.fetchPlace() auf und übergeben Sie ein FetchPlaceRequest.

Die API gibt ein FetchPlaceResponse in einem Task zurück. Das FetchPlaceResponse enthält ein Place-Objekt, das der angegebenen Orts-ID entspricht.

Im folgenden Codebeispiel wird gezeigt, wie fetchPlace() aufgerufen wird, um Details zum angegebenen Ort abzurufen.

Kotlin

// Define a Place ID.
val placeId = PlaceIdProvider.getRandomPlaceId()

// Specify the fields to return.
val placeFields = listOf(
    Place.Field.ID,
    Place.Field.DISPLAY_NAME,
    Place.Field.FORMATTED_ADDRESS,
    Place.Field.LOCATION,
)

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

        val name = place.displayName
        val address = place.formattedAddress
        val location = place.location

        binding.placeName.text = name
        binding.placeAddress.text = address
        if (location != null) {
            binding.placeLocation.text = getString(
                R.string.place_location,
                location.latitude,
                location.longitude,
            )
        } else {
            binding.placeLocation.text = null
        }
        Log.i(TAG, "Place found: ${place.displayName}")
    }.addOnFailureListener { exception: Exception ->
        if (exception is ApiException) {
            val message = getString(R.string.place_not_found, exception.message)
            binding.placeName.text = message
            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 = PlaceIdProvider.getRandomPlaceId();

// Specify the fields to return.
final List<Place.Field> placeFields =
        Arrays.asList(
                Place.Field.ID,
                Place.Field.DISPLAY_NAME,
                Place.Field.FORMATTED_ADDRESS,
                Place.Field.LOCATION);

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

                    final CharSequence name = place.getDisplayName();
                    final CharSequence address = place.getFormattedAddress();
                    final LatLng location = place.getLocation();

                    binding.placeName.setText(name);
                    binding.placeAddress.setText(address);
                    if (location != null) {
                        binding.placeLocation.setText(
                                getString(
                                        R.string.place_location,
                                        location.latitude,
                                        location.longitude));
                    } else {
                        binding.placeLocation.setText(null);
                    }

                    Log.i(TAG, "Place found: " + place.getDisplayName());
                })
        .addOnFailureListener(
                (exception) -> {
                    if (exception instanceof ApiException apiException) {
                        final String message =
                                getString(
                                        R.string.place_not_found,
                                        apiException.getMessage());
                        binding.placeName.setText(message);
                        Log.e(TAG, "Place not found: " + exception.getMessage());
                        final int statusCode = apiException.getStatusCode();
                        // TODO: Handle error with given status code.
                    }
                });

Status „Geöffnet“ abrufen

Die Methode PlacesClient.isOpen(IsOpenRequest request) gibt ein IsOpenResponse-Objekt zurück, das angibt, ob der Ort derzeit geöffnet ist. Dabei wird die im Aufruf angegebene Zeit berücksichtigt.

Diese Methode verwendet ein einzelnes Argument vom Typ IsOpenRequest, das Folgendes enthält:

  • Ein Place-Objekt oder ein String, der eine Orts-ID angibt.
  • Ein optionaler Zeitwert, der die Zeit in Millisekunden ab dem 01.01.1970, 00:00:00 Uhr (UTC) angibt. Wenn keine Zeit angegeben ist, wird die aktuelle Zeit verwendet.

Für diese Methode müssen die folgenden Felder im Place-Objekt vorhanden sein:

  • Place.Field.BUSINESS_STATUS
  • Place.Field.CURRENT_OPENING_HOURS
  • Place.Field.OPENING_HOURS
  • Place.Field.UTC_OFFSET

Wenn diese Felder nicht im Place-Objekt angegeben sind oder Sie eine Orts-ID übergeben, werden sie mit der Methode PlacesClient.fetchPlace() abgerufen. Weitere Informationen zum Erstellen des Place-Objekts mit den erforderlichen Feldern finden Sie unter Place Details.

Im folgenden Beispiel wird ermittelt, ob ein Ort derzeit geöffnet ist. In diesem Beispiel übergeben Sie nur die Orts-ID an isOpen():

Kotlin

val isOpenCalendar: Calendar = Calendar.getInstance()
val placeId = PlaceIdProvider.getRandomPlaceId()

val request: IsOpenRequest = try {
    IsOpenRequest.newInstance(placeId, isOpenCalendar.timeInMillis)
} catch (e: IllegalArgumentException) {
    Log.e("PlaceIsOpen", "Error: " + e.message)
    return
}
val isOpenTask: Task<IsOpenResponse> = placesClient.isOpen(request)
isOpenTask.addOnSuccessListener { response ->
    val isOpen = response.isOpen ?: false
    binding.isOpenByIdResult.text = getString(R.string.is_open_by_id, isOpen.toString())
    Log.d("PlaceIsOpen", "Is open by ID: $isOpen")
}
// ...

Java

@NonNull Calendar isOpenCalendar = Calendar.getInstance();
String placeId = PlaceIdProvider.getRandomPlaceId();
IsOpenRequest isOpenRequest;

try {
    isOpenRequest = IsOpenRequest.newInstance(placeId, isOpenCalendar.getTimeInMillis());
} catch (IllegalArgumentException e) {
    Log.e("PlaceIsOpen", "Error: " + e.getMessage());
    return;
}

Task<IsOpenResponse> placeTask = placesClient.isOpen(isOpenRequest);

placeTask.addOnSuccessListener(
        (response) -> {
            final boolean isOpen = Boolean.TRUE.equals(response.isOpen());
            binding.isOpenByIdResult.setText(
                    getString(R.string.is_open_by_id, String.valueOf(isOpen)));
            Log.d("PlaceIsOpen", "Is open by ID: " + isOpen);
        });
placeTask.addOnFailureListener(
        (exception) -> {
            binding.isOpenByIdResult.setText(
                    getString(R.string.is_open_by_id, "Error: " + exception.getMessage()));
            Log.e("PlaceIsOpen", "Error: " + exception.getMessage());
        });

Im nächsten Beispiel wird isOpen() aufgerufen und ein Place-Objekt übergeben. Das Place-Objekt muss eine gültige Orts-ID enthalten:

Kotlin

val isOpenCalendar: Calendar = Calendar.getInstance()
var place: Place
val placeId = PlaceIdProvider.getRandomPlaceId()
// 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.DISPLAY_NAME,
)

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) {
        Log.e("PlaceIsOpen", "Error: " + e.message)
        return@addOnSuccessListener
    }
    val isOpenTask: Task<IsOpenResponse> = placesClient.isOpen(isOpenRequest)
    isOpenTask.addOnSuccessListener { isOpenResponse ->
        val isOpen = when (isOpenResponse.isOpen) {
            true -> getString(R.string.is_open)
            else -> getString(R.string.is_closed)
        }
        binding.isOpenByObjectResult.text = getString(
            R.string.is_open_by_object,
            place.displayName,
            isOpen,
        )
        Log.d("PlaceIsOpen", "Is open by object: $isOpen")
    }
    // ...
}
// ...

Java

@NonNull Calendar isOpenCalendar = Calendar.getInstance();
String placeId = PlaceIdProvider.getRandomPlaceId();
// 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.DISPLAY_NAME));

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) {
                Log.e("PlaceIsOpen", "Error: " + e.getMessage());
                return;
            }
            Task<IsOpenResponse> isOpenTask = placesClient.isOpen(isOpenRequest);

            isOpenTask.addOnSuccessListener(
                    (isOpenResponse) -> {
                        final boolean isOpen = Boolean.TRUE.equals(isOpenResponse.isOpen());
                        binding.isOpenByObjectResult.setText(
                                getString(
                                        R.string.is_open_by_object,
                                        place.getDisplayName(),
                                        String.valueOf(isOpen)));
                        Log.d("PlaceIsOpen", "Is open by object: " + isOpen);
                    });
            isOpenTask.addOnFailureListener(
                    (exception) -> { // also update the result text field
                        binding.isOpenByObjectResult.setText(
                                getString(
                                        R.string.is_open_by_object,
                                        place.getDisplayName(),
                                        "Error: " + exception.getMessage()));
                        Log.e("PlaceIsOpen", "Error: " + exception.getMessage());
                    });
        });
placeTask.addOnFailureListener(
        (exception) -> {
            binding.isOpenByObjectResult.setText("Error: " + exception.getMessage());
            Log.e("PlaceIsOpen", "Error: " + exception.getMessage());

Zuordnungen in der App anzeigen

Wenn in Ihrer App Ortsinformationen, einschließlich Rezensionen, angezeigt werden, müssen auch alle Quellenangaben eingeblendet werden. Weitere Informationen finden Sie unter Attributionen.

Weitere Informationen zu Orts-IDs

Die im Places SDK for Android (Legacy) verwendete Orts-ID ist dieselbe Kennung wie in der Places API (Legacy). Eine Orts-ID kann nur auf einen Ort verweisen. Ein Ort kann aber mehrere Orts-IDs haben. Es gibt noch weitere Umstände, unter denen ein Ort eine neue Orts-ID erhalten kann. Das kann beispielsweise passieren, wenn ein Unternehmen an einen neuen Standort umzieht.

Wenn Sie einen Ort anhand einer Orts-ID anfordern, können Sie sicher sein, dass Sie in der Antwort immer denselben Ort erhalten (sofern der Ort noch existiert). Die Antwort kann jedoch eine Orts-ID enthalten, die sich von der in Ihrer Anfrage unterscheidet.

Weitere Informationen finden Sie in der Übersicht zur Orts-ID.