Place Details

Plattform auswählen: Android iOS JavaScript Webdienst

Über das Places SDK for Android erhalten Sie umfangreiche Informationen zu Orten, z. B. den Namen und die Adresse des Ortes, den geografischen Standort (Breiten- und Längengrad), die Art des Ortes (z. B. Nachtclub, Tierhandlung, Museum). 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, mit der ein Ort eindeutig identifiziert wird.

Ortsdetails

Das Place-Objekt bietet Informationen zu einem bestimmten Ort. Sie haben folgende Möglichkeiten, ein Place-Objekt abzurufen:

• Rufen Sie PlacesClient.findCurrentPlace() auf. Weitere Informationen finden Sie in der Anleitung zum Abrufen des aktuellen Ortes.
• Rufen Sie PlacesClient.fetchPlace() auf. Weitere Informationen finden Sie in der Anleitung Ort nach ID abrufen.

Wenn Sie einen Ort anfordern, müssen Sie festlegen, 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 ein wichtiger Faktor, da sie die Kosten für jede Anfrage beeinflusst.

Die Ergebnisse für „Place“-Daten dürfen nicht leer sein. Es werden aber nur Ortsergebnisse mit Daten zurückgegeben. Wenn ein angeforderter Ort z. B. keine Fotos hat, 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:

Java

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

Kotlin

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

Hinweis:PlacesClient.fetchPlace() unterstützt zwar alle Ortsdetails, PlacesClient.findCurrentPlace() jedoch nur einen Teil. Eine Liste der Felder, die von findCurrentPlace() nicht unterstützt werden, finden Sie unter Unterstützung für Felder vom Places SDK for Android.

Nachdem Sie das Objekt Place 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. Nachfolgend sind einige der verfügbaren Methoden aufgeführt. Eine vollständige Liste aller Methoden finden Sie in der API-Referenz zu Place.

• getAddress(): die Adresse des Ortes im menschenlesbaren Format.
• getAddressComponents(): Eine List von Adresskomponenten für diesen Ort. Die Komponenten dienen dazu, strukturierte Daten zur Adresse eines Ortes zu extrahieren, etwa um die Stadt zu finden, in der sich ein Ort befindet. Verwenden Sie diese Komponenten nicht für die Adressformatierung. Rufen Sie stattdessen getAddress() auf. Dadurch wird eine lokalisierte formatierte Adresse bereitgestellt.
• getId(): die ID des Textes für den Ort Weitere Informationen zu Orts-IDs finden Sie im weiteren Verlauf dieser Seite.
• getLatLng(): der geografische Standort des Ortes, angegeben in Breiten- und Längengraden
• getName(): der Name des Ortes

• getOpeningHours(): Der OpeningHours des Orts. Rufen Sie OpeningHours.getWeekdayText() auf, um eine Liste von Strings zurückzugeben, die Öffnungszeiten für jeden Wochentag enthalten. Rufen Sie OpeningHours.getPeriods() auf, um eine Liste von period-Objekten mit detaillierten Informationen zurückzugeben, die den von getWeekdayText() bereitgestellten Daten entsprechen.

  Hinweis : Wenn ein Ort immer geöffnet ist, wird der Zeitraum um Sonntag um Mitternacht dargestellt. closeEvent ist null.

  Das Place-Objekt enthält auch die Methode getCurrentOpeningHours(), die die Öffnungszeiten eines Ortes in den nächsten sieben Tagen zurückgibt, und die Methode getSecondaryOpeningHours(), die die sekundären Öffnungszeiten eines Ortes 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 jetzt die Standardeinstellung verwendet. isOpen wird nur zurückgegeben, wenn sowohl Place.Field.UTC_OFFSET als auch Place.Field.OPENING_HOURS verfügbar sind. Damit Sie genaue Ergebnisse erhalten, fordern Sie in der ursprünglichen Ortsanfrage die Felder Place.Field.BUSINESS_STATUS und Place.Field.UTC_OFFSET an. Wenn hier keine Angaben gemacht werden, wird angenommen, dass das Unternehmen betriebsbereit ist. In diesem Video erfahren Sie, wie Sie isOpen mit Place Details verwenden.

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

Einige einfache Beispiele:

Java

final CharSequence name = place.getName();
final CharSequence address = place.getAddress();
final LatLng location = place.getLatLng();

      

Kotlin

val name = place.name
val address = place.address
val location = place.latLng

      

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. Über den Place Autocomplete-Dienst wird außerdem für jeden Ort eine Orts-ID zurückgegeben, die der angegebenen Suchanfrage und dem Filter entspricht. Sie können die Orts-ID speichern und später verwenden, um das Objekt Place noch einmal abzurufen.

Um einen Ort anhand der ID abzurufen, rufen Sie PlacesClient.fetchPlace() auf und übergeben einen FetchPlaceRequest.

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

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

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

      

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")
        }
    }

      

Sie können ein CancelToken verwenden, um eine Anfrage an eine der Anfrageklassen zu senden (z. B. FetchPlaceRequest). Die Kündigung wird auf Best-Effort-Basis durchgeführt. Nach der Genehmigung wird keine Antwort mehr gesendet. Das Ausgeben eines Stornierungstokens ist keine Garantie dafür, dass eine bestimmte Anfrage abgebrochen wird. Die Anfrage wird Ihnen auch dann in Rechnung gestellt, wenn keine Antwort zurückgegeben wird.

Öffnungsstatus abrufen

Die Methode PlacesClient.isOpen(IsOpenRequest request) gibt ein IsOpenResponse-Objekt zurück, das angibt, ob der Ort derzeit basierend auf der im Aufruf angegebenen Zeit 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 Objekt Place muss eine gültige Orts-ID enthalten.
• Ein optionaler Zeitwert, der die Zeit in Millisekunden von 1970-01-01T00:00:00Z angibt. Wenn keine Uhrzeit angegeben ist, wird jetzt die Standardeinstellung 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 nicht im Place-Objekt enthalten sind oder eine Orts-ID übergeben wird, werden sie mit der Methode PlacesClient.fetchPlace() abgerufen. Weitere Informationen zum Erstellen eines „Place“-Objekts mit den erforderlichen Feldern finden Sie unter „Place Details“.

Hinweis : Für die SKU „Basic Data“ werden die fetchPlace()-Aufrufe für Place.Field.UTC_OFFSET und Place.Field.BUSINESS_STATUS berechnet. Die SKU „Places Data“ in Places wird für Aufrufe von fetchPlace() für Place.Field.CURRENT_OPENING_HOURS und Place.Field.OPENING_HOURS berechnet.

Das folgende Beispiel bestimmt, ob ein Ort derzeit geöffnet ist. In diesem Beispiel wird nur die Orts-ID an isOpen() übergeben:

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

      

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

      

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

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

      

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

      

Zuordnungen in der App anzeigen

Wenn in Ihrer App Ortsinformationen angezeigt werden, müssen auch Attributionen vorhanden sein. Weitere Informationen finden Sie in der Dokumentation zu Attributionen.

Weitere Informationen zu Orts-IDs

Die im Places SDK for Android verwendete Orts-ID ist die gleiche wie in der Places API. Jede Orts-ID kann nur auf einen Ort verweisen, ein einzelner Ort kann jedoch mehrere Orts-IDs haben. In anderen Fällen kann es vorkommen, dass ein Ort eine neue Orts-ID erhält. Das kann beispielsweise der Fall sein, wenn ein Unternehmen umzieht.

Wenn Sie einen Ort über eine Orts-ID anfordern, können Sie sicher sein, dass Sie immer denselben Ort in der Antwort erhalten, sofern der Ort noch existiert. Die Antwort kann jedoch eine Orts-ID enthalten, die von der in Ihrer Anfrage abweicht.

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