„Place Details“

Plattform auswählen: Android iOS JavaScript Webdienst

Über das Places SDK for Android erhält Ihre App umfangreiche Informationen zu Orten, z. B. Name und Adresse des Ortes, den als Breiten- und Längengrad angegebenen geografischen Standort und die Art des Ortes (z. B. Nachtclub, Tierhandlung, Museum). Um auf diese Informationen für einen bestimmten Ort zuzugreifen, können Sie die Orts-ID verwenden, eine stabile Kennung, die einen Ort eindeutig identifiziert.

Ortsdetails

Das Objekt Place liefert Informationen zu einem bestimmten Ort. Sie können ein Place-Objekt auf folgende Arten abrufen:

• Rufen Sie PlacesClient.fetchPlace() auf: Weitere Informationen finden Sie im Leitfaden zur Suche nach einem Ort per ID.
• PlacesClient.findCurrentPlace() aufrufen – Weitere Informationen findest du in der Anleitung zum Abrufen des aktuellen Orts.
  PlacesClient.fetchPlace() unterstützt zwar alle Felder mit Ortsdaten, PlacesClient.findCurrentPlace() jedoch nur einen Teil davon. Eine Liste der Felder, die von findCurrentPlace() NICHT unterstützt werden, finden Sie unter Feldunterstützung im Places SDK for Android.

Wenn Sie einen Ort anfordern, müssen Sie angeben, welche Ortsdaten zurückgegeben werden sollen. Übergeben Sie dazu eine Liste von Place.Field-Werten, um festzulegen, welche Daten zurückgegeben werden sollen. Diese Liste ist ein wichtiger Aspekt, da sie sich auf die Kosten für jede Anfrage auswirkt.

Da Ergebnisse für Ortsdaten nicht leer sein dürfen, werden nur Ergebnisse mit Daten zurückgegeben. Wenn z. B. für einen angeforderten Ort 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 placeFields = Arrays.asList(Place.Field.NAME, Place.Field.RATING, Place.Field.OPENING_HOURS);

Hinweis : Das Places SDK for Android und das Places SDK for Android (New) unterstützen unterschiedliche Preismodelle. Das bedeutet, dass der Preis für einen Aufruf auf den angeforderten Feldern und der SDK-Version basiert, die Sie verwenden. Ausführliche Preisinformationen für beide SDKs finden Sie unter Nutzung und Abrechnung.

Auf Place-Objektdatenfelder 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 ähnliche 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 Place.

• getAddress(): Die Adresse des Ortes im menschenlesbaren Format.
• getAddressComponents(): Eine List mit Adresskomponenten für diesen Ort. Diese Komponenten werden verwendet, um strukturierte Informationen zur Adresse eines Ortes zu extrahieren, z. B. um die Stadt zu finden, in der sich der Ort befindet. Verwenden Sie diese Komponenten nicht für die Adressformatierung. Rufen Sie stattdessen getAddress() auf, um eine lokalisierte formatierte Adresse bereitzustellen.
• getId(): Die ID für den Ort in Textform. Weitere Informationen zu Orts-IDs finden Sie weiter unten auf dieser Seite.
• getLatLng(): Der geografische Standort des Ortes, angegeben in Breiten- und Längengraden.
• getName(): Name des Ortes

• 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 immer geöffnet ist, wird als Zeitraum Sonntag um Mitternacht angegeben und closeEvent ist null.

  Das Place-Objekt enthält auch die Methode getCurrentOpeningHours(), mit der die Öffnungszeiten eines Ortes in den nächsten sieben Tagen zurückgegeben werden, sowie die Methode getSecondaryOpeningHours(), die die sekundären Öffnungszeiten eines Ortes in den nächsten sieben Tagen zurückgibt.

• isOpen(): Boolescher Wert, der angibt, ob der Ort derzeit geöffnet ist. Wenn keine Zeit 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 kein Antrag 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 findest du unter Status „Geöffnet“ 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();

      

Auf Place-Daten zugreifen, die in Version 3.3.0 hinzugefügt wurden

Version 3.3.0 des Places SDK for Android enthält neue Daten für Place:

• Ortstypen: Neue Typwerte für einen Ort.
• Rezensionen: Bis zu fünf Rezensionen für einen Ort.
• Namenssprachcode: Der Sprachcode für den Namen eines Ortes.

In den folgenden Abschnitten wird beschrieben, wie Sie auf diese neuen Daten zugreifen können.

Hinweis : Das neue SDK unterstützt nur die neuen Place-Daten in Java.

Auf neue Ortstypen zugreifen

Jedem Ort können ein oder mehrere type-Werte zugeordnet sein. Im Places SDK for Android Version 3.3.0 wurden viele neue Typwerte hinzugefügt. Eine vollständige Liste finden Sie unter Erweiterte Ortstypen.

In Version 3.2.0 und früheren Versionen des Places SDK for Android wurde die Methode Place.getTypes() verwendet, um auf die Typwerte eines Orts zuzugreifen. Place.getTypes() gibt eine Liste von Typen als Enum-Werte zurück, die von Place.Types definiert werden.

Die Methode Place.getTypes() wurde mit der Version 3.3.0 des Places SDK for Android eingestellt. Sie können es während des Einstellungszeitraums weiter verwenden, Sie sollten Ihre Anwendungen jedoch zur Verwendung von Place.getPlaceTypes() migrieren.

Die Methode Place.getPlaceTypes() gibt die Typwerte als Liste von Stringwerten zurück. Die zurückgegebenen Werte hängen von Ihrer Version des Places SDK for Android ab:

• Places SDK for Android (New): Es werden die in den Tabellen A und B definierten Strings unter Ortstypen (Neu) zurückgegeben, einschließlich aller in Version 3.3.0 hinzugefügten Ortstypen.
• Places SDK for Android: Gibt die durch Place.Types definierten Enums zurück. Die in Version 3.3.0 neu hinzugefügten Typen sind nicht enthalten.

Informationen zu den wichtigsten Unterschieden zwischen den beiden SDK-Versionen finden Sie unter SDK-Version auswählen.

Rezensionen zu Orten aufrufen

Im Places SDK for Android (New) wird die Klasse Review hinzugefügt, die eine Rezension zu einem Ort enthält. Das Place-Objekt kann bis zu fünf Rezensionen enthalten.

Die Klasse Review kann auch eine Quellenangabe und eine Angabe zum Autor enthalten. Wenn Sie die Rezension in Ihrer App präsentieren, müssen Sie auch die Quellenangaben oder den Autor angeben. Weitere Informationen finden Sie unter Rezensionen anzeigen.

Wenn Sie Rezensionen in das Place-Objekt einfügen möchten, müssen Sie:

1. Aktivieren Sie das neue SDK, wenn Sie Ihr Google Cloud-Projekt einrichten.
2. Initialisieren Sie das neue SDK innerhalb einer Aktivität oder eines Fragments.
3. Fügen Sie Place.Field.REVIEWS in die Feldliste der „Place Details“-Anfrage ein.
4. Rufen Sie PlacesClient.fetchPlace() auf. Das Rezensionsfeld wird von PlacesClient.findCurrentPlace() nicht unterstützt.
5. Verwenden Sie die Methode Place.getReviews(), um auf das Datenfeld für Rezensionen im Objekt Place zuzugreifen.

Auf Sprachcode für Ortsnamen zugreifen

Die vorhandene Methode Place.getName() gibt einen Textstring mit dem Namen eines Ortes zurück. Wenn der Ortsname in das Place-Objekt aufgenommen werden soll, müssen Sie Place.Field.NAME in die Feldliste der „Place Details“-Anfrage aufnehmen.

Das Objekt Place enthält jetzt den Sprachcode für den Namensstring. So füllen Sie das Place-Objekt mit Sprachcode:

1. Aktivieren Sie das neue SDK, wenn Sie Ihr Google Cloud-Projekt einrichten.
2. Initialisieren Sie das neue SDK innerhalb einer Aktivität oder eines Fragments.
3. Fügen Sie Place.Field.NAME in die Feldliste der Anfrage ein. Mit diesem Wert wird die Antwort so konfiguriert, dass sie sowohl den Ortsnamen als auch den Sprachcode im Place-Objekt enthält.
4. Rufen Sie PlacesClient.fetchPlace() auf. PlacesClient.findCurrentPlace() unterstützt das Sprachcodefeld nicht.
5. Verwenden Sie die Methode Place.getNameLanguageCode(), um auf das Sprachcodefeld im Objekt Place zuzugreifen.

Regionscode in Version 3.3.0 festlegen

Das Places SDK for Android (New) fügt den „Regionscode“-Anfrageparameter „Place Details“ hinzu. Der Regionscode wird zum Formatieren der Antwort verwendet und als zweistelliger CLDR-Code angegeben. Dieser Parameter kann sich auch Verzerrungen auf die Suchergebnisse auswirken. Es gibt keinen Standardwert. Sie müssen das neue SDK aktivieren, um den Regionscode festzulegen.

Wenn der Ländername des Adressfelds in der Antwort mit dem Regionscode übereinstimmt, wird der Ländercode in der Adresse weggelassen.

Die meisten CLDR-Codes entsprechen den ISO 3166-1-Codes, mit einigen Ausnahmen. Die ccTLD des Vereinigten Königreichs lautet beispielsweise „uk“ (.co.uk), während der ISO 3166-1-Code „gb“ lautet (technisch für das Vereinigte Königreich von Großbritannien und Nordirland). Der Parameter kann sich gemäß anwendbarem Recht auf die Ergebnisse auswirken.

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 abrufen, indem Sie Place.getId() aufrufen. Der Dienst Place Autocomplete gibt ebenfalls eine Orts-ID für jeden Ort zurück, der der angegebenen Suchanfrage und dem angegebenen Filter entspricht. Sie können die Orts-ID speichern und sie verwenden, um das Place-Objekt später 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 zurück. Der FetchPlaceResponse enthält ein Place-Objekt, das mit der angegebenen Orts-ID übereinstimmt.

Das folgende Codebeispiel zeigt, 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.
    }
});

      

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

Status „Geöffnet“ abrufen

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

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

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, wenn Sie 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, einschließlich Rezensionen zu Orten, angezeigt werden, müssen in der App auch Zuordnungen angezeigt werden. Weitere Informationen finden Sie unter Quellenangaben.

Weitere Informationen zu Orts-IDs

Die im Places SDK for Android verwendete Orts-ID entspricht der ID 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. Das 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 er noch vorhanden ist. Die Antwort kann jedoch eine Orts-ID enthalten, die sich von der in Ihrer Anfrage unterscheidet.

Weitere Informationen finden Sie unter Orts-IDs.