„Place Details“

Plattform auswählen: Android iOS JavaScript Webdienst

Das Places SDK for Android stellt Ihrer App umfangreiche Informationen zu Orten zur Verfügung, z. B. Name und Adresse des Orts, den geografischen Standort (mit Breiten- und Längengradkoordinaten), die Art des Ortes (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.

Ortsangaben

Das Objekt Place liefert Informationen zu einem bestimmten Ort. So rufen Sie ein Place-Objekt ab:

• Rufen Sie PlacesClient.fetchPlace() auf. Weitere Informationen finden Sie in der Anleitung zum Abrufen eines Orts anhand der ID.
• Rufen Sie PlacesClient.findCurrentPlace() auf. Weitere Informationen finden Sie in der Anleitung zum Abrufen des aktuellen Orts.
  PlacesClient.fetchPlace() unterstützt zwar alle Felder mit Ortsdaten, PlacesClient.findCurrentPlace() unterstützt jedoch nur einen Teil der Felder mit Ortsdaten. Eine Liste der Felder, die NICHT von findCurrentPlace() unterstützt werden, finden Sie unter Unterstützung von Feldern im Places SDK for Android.

Wenn Sie einen Ort anfragen, müssen Sie angeben, welche Ortsdaten zurückgegeben werden sollen. Dazu übergeben Sie eine Liste von Place.Field-Werten, mit denen die zurückzugebenden Daten angegeben werden. Diese Liste ist eine wichtige Überlegung, da sie sich auf die Kosten pro Anfrage auswirkt.

Da Ortsdatenergebnisse nicht leer sein dürfen, werden nur Ortsergebnisse mit Daten zurückgegeben. Wenn für einen angeforderten Ort beispielsweise 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.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);
  

Auf Felder für „Place“-Objektdaten zugreifen

Nachdem Sie das Place-Objekt abgerufen haben, können Sie mit den Methoden des Objekts auf die in der Anfrage angegebenen Datenfelder zugreifen. 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. Eine vollständige Liste aller Methoden finden Sie in der API-Referenz zu Place.

• getAddress(): Die Adresse des Orts in einem visuell lesbaren Format.
• getAddressComponents(): Eine List der Adresskomponenten für diesen Ort. Diese Komponenten werden bereitgestellt, um strukturierte Informationen zur Adresse eines Ortes zu extrahieren, z. B. um die Stadt zu finden, in der sich ein Ort befindet. Verwende diese Komponenten nicht für die Adressformatierung. Rufe stattdessen getAddress() auf, um eine lokalisierte Adresse bereitzustellen.
• getId(): Die Kennung des Orts in Textform. Weitere Informationen zu Orts-IDs finden Sie im Folgenden.
• getLatLng(): Der geografische Standort des Orts, angegeben in Breiten- und Längengradkoordinaten.
• getName(): Der Name des Ortes.

• getOpeningHours(): Die OpeningHours des Orts. Rufen Sie OpeningHours.getWeekdayText() auf, um eine Liste von Strings zurückzugeben, die Öffnungszeiten 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.

  Hinweis : Wenn ein Ort immer geöffnet ist, wird als Zeitraum Sonntag um Mitternacht angegeben und closeEvent ist null.

  Das Objekt Place enthält außerdem die Methode getCurrentOpeningHours(), die die Öffnungszeiten eines Orts in den nächsten sieben Tagen zurückgibt, und getSecondaryOpeningHours(), die die sekundären Öffnungszeiten eines Orts in den nächsten sieben Tagen zurückgibt.

• isOpen(): Ein boolescher Wert, der angibt, ob der Ort derzeit geöffnet ist. Wenn keine Uhrzeit angegeben ist, wird die Standardeinstellung „jetzt“ verwendet. isOpen wird nur zurückgegeben, wenn sowohl Place.Field.UTC_OFFSET als auch Place.Field.OPENING_HOURS verfügbar sind. Fordern Sie die Felder Place.Field.BUSINESS_STATUS und Place.Field.UTC_OFFSET in Ihrer ursprünglichen Ortsanfrage an, um genaue Ergebnisse zu erhalten. Wird keine Anfrage gestellt, wird davon ausgegangen, dass das Unternehmen betriebsbereit ist. In diesem Video erfahren Sie, wie Sie isOpen mit Place Details-Anfragen verwenden.

  Hinweis : Diese Methode wurde eingestellt. Verwenden Sie stattdessen PlacesClient.isOpen(IsOpenRequest request). Weitere Informationen finden Sie unter Geöffnet-Status abrufen.

Einige einfache Beispiele:

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

      

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 Ortes durch Aufrufen von Place.getId() abrufen. Der Dienst Place Autocomplete gibt außerdem eine Orts-ID für jeden Ort zurück, der mit der Suchanfrage und dem Filter übereinstimmt. Sie können die Orts-ID speichern und später verwenden, um das Place-Objekt noch einmal abzurufen.

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

Die API gibt ein FetchPlaceResponse in einem Task-Element zurück. 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 = "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.
    }
});

      

Hinweis:Weitere Informationen zum Initialisieren von PlacesClient finden Sie unter Places API-Client initialisieren.

Sie können ein CancellationToken verwenden, um eine Anfrage an eine der Anfrageklassen (z. B. FetchPlaceRequest) abzubrechen. Die Stornierung erfolgt auf Best-Effort-Basis. Nachdem eine Kündigungsanfrage gestellt wurde, wird keine Antwort mehr zurückgegeben. Das Ausstellen eines Kündigungstokens garantiert NICHT, dass eine bestimmte Anfrage abgebrochen wird. Die Anfrage kann Ihnen auch dann in Rechnung gestellt werden, wenn keine Antwort zurückgegeben wird.

Geöffnet-Status abrufen

Die Methode PlacesClient.isOpen(IsOpenRequest request) gibt ein IsOpenResponse-Objekt zurück, das basierend auf der im Aufruf angegebenen Zeit angibt, ob der Ort derzeit geöffnet ist.

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

• Ein Place-Objekt oder ein String, der eine Orts-ID angibt.
  Hinweis : Das Place-Objekt muss eine gültige Orts-ID enthalten.
• Ein optionaler Zeitwert, der die Zeit in Millisekunden ab 1970-01-01T00:00:00Z angibt. Wenn keine Uhrzeit angegeben ist, wird die Standardeinstellung „jetzt“ verwendet.

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

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

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

Hinweis : Die Places Basic Data SKU wird für Aufrufe von fetchPlace() für Place.Field.UTC_OFFSET und Place.Field.BUSINESS_STATUS berechnet. Die Places Contact Data SKU wird für Aufrufe von fetchPlace() für Place.Field.CURRENT_OPENING_HOURS und Place.Field.OPENING_HOURS berechnet.

Im folgenden Beispiel sehen Sie, ob ein Ort derzeit geöffnet ist. In diesem Beispiel übergeben Sie die Orts-ID nur an 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());
// ...

      

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

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

      

Zuordnungen in der App anzeigen

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

Weitere Informationen zu Orts-IDs

Die im Places SDK for Android verwendete Orts-ID ist dieselbe Kennung wie in der Places API. Jede Orts-ID kann sich nur auf einen Ort beziehen, aber ein Ort kann mehrere Orts-IDs haben. Es gibt andere Umstände, die dazu führen können, dass ein Ort eine neue Orts-ID erhält. Dies kann beispielsweise der Fall sein, wenn ein Unternehmen an einen neuen Standort umzieht.

Wenn Sie einen Ort durch Angabe einer Orts-ID anfordern, können Sie sicher sein, dass in der Antwort immer derselbe Ort zurückgegeben wird (sofern der Ort noch vorhanden ist). 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.