Das Places SDK for Android stellt Ihrer App umfangreiche Informationen zu Orten zur Verfügung, darunter Name und Adresse des Orts, der als Breiten- und Längengrad angegebene geografische Standort sowie die Art des Ortes (z. B. Nachtclub, Tierhandlung, Museum) und vieles mehr. 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 haben folgende Möglichkeiten, auf ein Place
-Objekt zuzugreifen:
- Rufen Sie
PlacesClient.fetchPlace()
auf: Weitere Informationen finden Sie in der Anleitung Ort über ID anfordern. - Rufen Sie
PlacesClient.findCurrentPlace()
auf – Weitere Informationen finden Sie in der Anleitung zum Abrufen des aktuellen Orts.
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 Daten angeben, die zurückgegeben werden sollen. Diese Liste ist wichtig, da sie sich auf die Kosten pro 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 ListplaceFields = Arrays.asList(Place.Field.NAME, Place.Field.RATING, Place.Field.OPENING_HOURS);
Auf Place-Objektdatenfelder zugreifen
Nachdem Sie das Place
-Objekt abgerufen haben, verwenden Sie die Methoden des Objekts, um auf die in der Anfrage angegebenen Datenfelder zuzugreifen. Wenn das Feld im Place
-Objekt fehlt, gibt die verwandte 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 in einem visuell lesbaren Format.getAddressComponents()
: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 ein Ort befindet. Verwende diese Komponenten nicht für die Adressformatierung. Rufe stattdessengetAddress()
auf, um eine lokalisierte formatierte Adresse zu erhalten.getId()
: Der Bezeichner für den Ort in Textform. Weitere Informationen zu Orts-IDs finden Sie weiter auf dieser Seite.getLatLng()
: Die geografische Lage des Orts, angegeben in Breiten- und Längengradkoordinaten.getName()
: Name des Ortes.getOpeningHours()
:OpeningHours
des Orts. Rufen SieOpeningHours.getWeekdayText()
auf, um eine Liste von Strings zurückzugeben, die die Öffnungszeiten für jeden Wochentag angeben. Rufen SieOpeningHours.getPeriods()
auf, um eine Liste vonperiod
-Objekten mit detaillierteren Informationen zurückzugeben, die den vongetWeekdayText()
bereitgestellten Daten entsprechen.Das
Place
-Objekt enthält auch die MethodegetCurrentOpeningHours()
, mit der die Öffnungszeiten eines Ortes in den nächsten sieben Tagen zurückgegeben werden, sowiegetSecondaryOpeningHours()
, mit der die sekundären Öffnungszeiten eines Ortes in den nächsten sieben Tagen zurückgegeben werden.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 sowohlPlace.Field.UTC_OFFSET
als auchPlace.Field.OPENING_HOURS
verfügbar sind. Fordern Sie die FelderPlace.Field.BUSINESS_STATUS
undPlace.Field.UTC_OFFSET
in Ihrer ursprünglichen Ortsanfrage an, um genaue Ergebnisse zu erhalten. Bei Nichtbeantragung wird davon ausgegangen, dass das Unternehmen betriebsbereit ist. In diesem Video erfahren Sie, wie SieisOpen
mit Place Details-Anfragen verwenden.
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.
- Sprachcode für Name: Der Sprachcode für den Namen eines Ortes.
Sie müssen das Places SDK for Android (New) aktivieren, um auf diese Daten zugreifen zu können. Informationen zu den wichtigsten Unterschieden zwischen den beiden SDK-Versionen finden Sie unter SDK-Version auswählen.
In den folgenden Abschnitten wird beschrieben, wie Sie auf diese neuen Daten zugreifen können.
Auf neue Ortstypen zugreifen
Jedem Ort können ein oder mehrere type-Werte zugeordnet sein. Mit dem Places SDK for Android Version 3.3.0 wurden viele neue Typwerte hinzugefügt. Die vollständige Liste finden Sie unter Erweiterte Ortstypen.
In Version 3.2.0 des Places SDK for Android und früheren Versionen haben Sie 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 durch Place.Types
definiert sind.
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): Gibt die unter Ortstypen (Neu) aufgeführten Strings zurück, die in den Tabellen A und B definiert wurden, einschließlich aller in Version 3.3.0 hinzugefügten Ortstypen.
- Places SDK for Android: Gibt die in
Place.Types
definierten Enums zurück. Die in Version 3.3.0 hinzugefügten neuen Typen sind nicht enthalten.
Informationen zu den wichtigsten Unterschieden zwischen den beiden SDK-Versionen finden Sie unter SDK-Version auswählen.
Auf Rezensionen zu Orten zugreifen
Mit dem Places SDK for Android (New) wird die Klasse Review
hinzugefügt. Sie enthält eine Rezension zu einem Ort. Das Place
-Objekt kann bis zu fünf Rezensionen enthalten.
Die Klasse Review
kann auch eine Quellenangabe und eine Quellenangabe des Autors enthalten. Wenn Sie die Rezension in Ihrer App präsentieren, müssen Sie auch die Quellenangabe oder den Autor angeben.
Weitere Informationen finden Sie unter Rezensionen anzeigen.
Um Rezensionen in das Place
-Objekt aufzunehmen, müssen Sie:
- Aktivieren Sie das neue SDK, wenn Sie Ihr Google Cloud-Projekt einrichten.
- Initialisieren Sie das neue SDK innerhalb einer Aktivität oder eines Fragments.
- Fügen Sie
Place.Field.REVIEWS
in die Liste der Felder der „Place Details“-Anfrage ein. - Rufen Sie
PlacesClient.fetchPlace()
auf. Das Rezensionsfeld wird vonPlacesClient.findCurrentPlace()
nicht unterstützt. - Verwenden Sie die Methode
Place.getReviews()
, um auf das Rezensionsdatenfeld im ObjektPlace
zuzugreifen.
Auf Sprachcode für Ortsnamen zugreifen
Die vorhandene Methode Place.getName()
gibt einen Textstring mit dem Namen eines Ortes zurück. Wenn der Name des Orts in das Place
-Objekt aufgenommen werden soll, müssen Sie Place.Field.NAME
in die Feldliste der Anfrage für Ortsdetails aufnehmen.
Das Place
-Objekt enthält jetzt den Sprachcode für den Namensstring. So füllen Sie das Place
-Objekt mit Sprachcode:
- Aktivieren Sie das neue SDK, wenn Sie Ihr Google Cloud-Projekt einrichten.
- Initialisieren Sie das neue SDK innerhalb einer Aktivität oder eines Fragments.
- 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 ObjektPlace
enthält. - Rufen Sie
PlacesClient.fetchPlace()
auf.PlacesClient.findCurrentPlace()
unterstützt nicht das Sprachcodefeld. - Verwenden Sie die Methode
Place.getNameLanguageCode()
, um auf das Sprachcodefeld im ObjektPlace
zuzugreifen.
Regionscode in Version 3.3.0 festlegen
Das Places SDK for Android (New) fügt Place Details den Anfrageparameter „Regionscode“ hinzu. Mit dem Regionscode wird die Antwort als zweistelliger CLDR-Code-Wert angegeben. Dieser Parameter kann sich auch negativ 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. Es gibt jedoch einige Ausnahmen. Die ccTLD des Vereinigten Königreichs lautet beispielsweise „uk“ (.co.uk), während der ISO 3166-1-Code „gb“ lautet (technisch für die Rechtspersönlichkeit „The United Kingdom of Great Britain and Northern Ireland“). Der Parameter kann die Ergebnisse gemäß anwendbarem Recht beeinflussen.
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.
Auch der Place Autocomplete-Dienst gibt für jeden Ort eine Orts-ID zurück, der der angegebenen Suchanfrage und dem angegebenen Filter entspricht. 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 ermitteln möchten, rufen Sie PlacesClient.fetchPlace()
auf und übergeben Sie einen FetchPlaceRequest
.
Die API gibt ein FetchPlaceResponse
in einem Task
zurück.
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. } });
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. - 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
Sind diese Felder nicht im Place
-Objekt vorhanden oder übergeben Sie eine Orts-ID, werden sie mit 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 = "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 ein Place
-Objekt übergeben wird.
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 Quellenangaben eingeblendet werden. Weitere Informationen finden Sie unter Quellenangaben.
Weitere Informationen zu Orts-IDs
Die im Places SDK for Android verwendete Orts-ID entspricht der Kennung der Places API. Jede Orts-ID kann sich nur auf einen Ort beziehen, aber ein Ort kann mehrere Orts-IDs haben. Es gibt aber auch 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 durch Angabe einer Orts-ID einen Ort anfordern, können Sie sicher sein, dass Sie in der Antwort immer denselben Ort erhalten (sofern der Ort noch vorhanden ist). Die Antwort kann jedoch eine Orts-ID enthalten, die sich von der ID in Ihrer Anfrage unterscheidet.
Weitere Informationen finden Sie in der Übersicht zur Orts-ID.