„Place Details“

Das Places SDK für Android bietet Ihrer App umfangreiche Informationen zu Orten, darunter Name und Adresse des Orts, geografischer Standort als Koordinaten für Längen- und Breitengrad sowie Ortstyp (z. B. Nachtclub, Zoohandlung, Museum). Um auf diese Informationen für einen bestimmten Ort zuzugreifen, können Sie die Orts-ID verwenden. Das ist eine stabile Kennung, die einen Ort eindeutig identifiziert.

Ortsdetails

Das Place-Objekt enthält Informationen zu einem bestimmten Ort. Sie haben folgende Möglichkeiten, ein Place-Objekt zu erhalten:

• PlacesClient.fetchPlace() anrufen: 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.
  Während PlacesClient.fetchPlace() alle Ortsdatenfelder unterstützt, wird bei PlacesClient.findCurrentPlace() nur ein Teil der Ortsdatenfelder unterstützt. Eine Liste der Felder, die von findCurrentPlace() NICHT unterstützt werden, finden Sie unter Unterstützte Felder des Places SDK for Android.

Wenn Sie einen Ort anfordern, müssen Sie angeben, welche Ortsdaten zurückgegeben werden sollen. Dazu übergeben Sie eine Liste von Place.Field-Werten, die die zurückzugebenden Daten angeben. Diese Liste ist wichtig, da sie sich auf die Kosten pro 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.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 Datenfelder von Ortsobjekten zugreifen

Nachdem du das Place-Objekt abgerufen hast, kannst du mithilfe der 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. Unten finden Sie Beispiele für einige der verfügbaren Methoden.

Eine vollständige Liste aller Methoden finden Sie in der Place-API-Referenz.

• getAddress(): Die Adresse des Ortes in visuell lesbarer Form.
• getAddressComponents(): Ein List mit Adresskomponenten für diesen Ort. Diese Komponenten dienen dazu, strukturierte Informationen über die 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 Textkennzeichnung für den Ort. Weitere Informationen zu Orts-IDs finden Sie im Rest dieser Seite.
• getLatLng(): Der geografische Standort des Orts, angegeben als Breiten- und Längengradkoordinaten.
• getName(): Der Name des Orts.

• getOpeningHours() – OpeningHours des Orts. Rufen Sie OpeningHours.getWeekdayText() auf, um eine Liste von Strings zurückzugeben, die 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 durchgehend geöffnet ist, wird der Zeitraum als Sonntag um Mitternacht dargestellt und closeEvent ist null.

  Das Place-Objekt enthält außerdem die Methode getCurrentOpeningHours(), die die Öffnungszeiten eines Ortes für die nächsten sieben Tage zurückgibt, und getSecondaryOpeningHours(), die die sekundären Öffnungszeiten eines Ortes 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 standardmäßig die aktuelle Zeit verwendet. isOpen wird nur zurückgegeben, wenn sowohl Place.Field.UTC_OFFSET als auch Place.Field.OPENING_HOURS verfügbar sind. Um genaue Ergebnisse zu erhalten, fordern Sie in Ihrer ursprünglichen Ortsanfrage die Felder Place.Field.BUSINESS_STATUS und Place.Field.UTC_OFFSET an. Wenn dies nicht beantragt wird, wird davon ausgegangen, dass das Unternehmen in Betrieb ist. In diesem Video erfahren Sie, wie Sie isOpen mit Place Details nutzen.

  Hinweis : Diese Methode wird nicht mehr unterstützt. Verwenden Sie stattdessen PlacesClient.isOpen(IsOpenRequest request). Weitere Informationen finden Sie unter Status „Offen“ abrufen.

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 Orts abrufen, indem Sie Place.getId() aufrufen. Der Place Autocomplete-Dienst gibt außerdem eine Orts-ID für jeden Ort zurück, der mit der angegebenen 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 anhand der ID abrufen möchten, rufen Sie PlacesClient.fetchPlace() auf und übergeben Sie eine FetchPlaceRequest.

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

Im folgenden Codebeispiel wird fetchPlace() aufgerufen, 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.

Mit einem CancellationToken können Sie versuchen, eine Anfrage an eine der Anfrageklassen (z. B. FetchPlaceRequest) abzubrechen. Die Stornierung erfolgt auf Best-Effort-Basis. Nach dem Einreichen einer Kündigungsanfrage erhalten Sie keine Antwort mehr. Das Ausstellen eines Kündigungstokens ist KEIN Garant dafür, dass eine bestimmte Anfrage storniert wird. Es kann sein, dass Ihnen die Anfrage in Rechnung gestellt wird, auch wenn keine Antwort zurückgegeben wird.

Status „Offen“ abrufen

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

Diese Methode akzeptiert 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.
• Optionaler Zeitwert, der die Zeit in Millisekunden seit dem 01.01.1970 00:00:00 UTC angibt. Wenn keine Zeit angegeben ist, wird standardmäßig 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 mithilfe der Methode PlacesClient.fetchPlace() abgerufen. Weitere Informationen zum Erstellen des Ortsobjekts mit den erforderlichen Feldern finden Sie unter Place Details.

Hinweis : Die SKU „Places Basic Data“ wird für fetchPlace()-Anfragen für Place.Field.UTC_OFFSET und Place.Field.BUSINESS_STATUS in Rechnung gestellt. Die Places-SKU „Contact Data“ wird für Aufrufe von fetchPlace() für Place.Field.CURRENT_OPENING_HOURS und Place.Field.OPENING_HOURS in Rechnung gestellt.

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 = "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 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 = "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 Informationen zu Orten angezeigt werden, einschließlich Rezensionen, müssen auch alle Quellenangaben eingeblendet werden. Weitere Informationen finden Sie unter Attributionen.

Weitere Informationen zu Orts-IDs

Die Orts-ID, die im Places SDK for Android verwendet wird, ist dieselbe Kennung wie in der Places API. Jede Orts-ID kann nur auf einen Ort verweisen. Ein Ort kann aber mehrere Orts-IDs haben. Es gibt noch andere Umstände, die dazu führen können, dass einem Ort eine neue Orts-ID zugewiesen wird. Das kann beispielsweise passieren, wenn ein Unternehmen an einen neuen Standort umzieht.

Wenn Sie einen Ort anfordern, indem Sie eine Orts-ID angeben, können Sie sich darauf verlassen, dass Sie in der Antwort immer denselben Ort erhalten (sofern der Ort noch existiert). Beachten Sie jedoch, dass die Antwort eine Orts-ID enthalten kann, die sich von der in Ihrer Anfrage unterscheidet.

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