Wenn Sie die Methoden Place Details (New), Nearby Search (New) oder Text Search (New) aufrufen, müssen Sie angeben, welche Felder in der Antwort zurückgegeben werden sollen. Es gibt keine Standardliste der zurückgegebenen Felder. Wenn Sie diese Liste weglassen, geben die Methoden einen Fehler zurück.
Eine vollständige Liste der unterstützten Datenfelder und ihrer entsprechenden SKUs finden Sie unter Felder für „Place“-Daten (neu). Informationen zu den spezifischen Feldern der einzelnen APIs finden Sie hier:
- FieldMask-Parameter für „Place Details (New)“
- FieldMask-Parameter für Nearby Search (New)
- FieldMask-Parameter für „Text Search (New)“
Sie geben die Feldliste an, indem Sie eine Antwortfeldmaske erstellen. Sie übergeben die Antwortfeldmaske dann an eine der Methoden, indem Sie den Parameter $fields oder fields oder den HTTP- oder gRPC-Header X-Goog-FieldMask verwenden.
Mit der Feldmaskierung lässt sich verhindern, dass unnötige Daten angefordert werden, was wiederum hilft, unnötige Verarbeitungszeiten und Gebühren zu vermeiden.
Antwortfeldmaske definieren
Die Antwortfeldmaske ist eine durch Kommas getrennte Liste von Pfaden, wobei jeder Pfad ein eindeutiges Feld im Antworttext angibt. Der Pfad beginnt bei der Antwortnachricht der obersten Ebene und verwendet einen durch Punkte getrennten Pfad zum angegebenen Feld.
So erstellen Sie einen Feldpfad:
topLevelField[.secondLevelField][.thirdLevelField][...]
Mit einer Feldmaske von * können Sie alle Felder anfordern.
Weitere Informationen zum Erstellen von Feldmasken finden Sie in der Datei field_mask.proto.
Feldmasken festlegen
So ermitteln Sie, welche Feldmasken Sie verwenden möchten:
- Fordern Sie alle Felder mit einer Feldmaske von
*an. - Sehen Sie sich die Hierarchie der Felder in der Antwort an und ermitteln Sie, welche Felder Sie benötigen.
- Erstellen Sie die Feldmaske anhand der Feldhierarchie.
Antwortfeldmaske für Nearby Search (New) und Text Search (New) definieren
„Nearby Search (New)“ und „Text Search (New)“ geben im Feld places der Antwort ein Array von Ortsobjekten zurück. Bei diesen APIs ist places das Feld der obersten Ebene der Antwort.
So rufen Sie beispielsweise das vollständige Antwortobjekt einer Text Search (New) ab:
curl -X POST -d '{
"textQuery" : "Spicy Vegetarian Food in Sydney, Australia"
}' \
-H 'Content-Type: application/json' -H 'X-Goog-Api-Key: API_KEY' \
-H 'X-Goog-FieldMask: *' \
'https://places.googleapis.com/v1/places:searchText'
Das vollständige Antwortobjekt eines „Text Search (New)“-Aufrufs hat folgendes Format:
{
"places": [
{
"name": "places/ChIJs5ydyTiuEmsR0fRSlU0C7k0",
"id": "ChIJs5ydyTiuEmsR0fRSlU0C7k0",
"types": [
"vegetarian_restaurant",
"vegan_restaurant",
"meal_takeaway",
"restaurant",
"food",
"point_of_interest",
"establishment"
],
"nationalPhoneNumber": "0433 479 794",
"internationalPhoneNumber": "+61 433 479 794",
"formattedAddress": "29 King St, Sydney NSW 2000, Australia",
"displayName": {
"text": "Spiced @ Barangaroo",
"languageCode": "en"
}, ...
},
...
]
}
Daher geben Sie für diese APIs eine Feldmaske in folgendem Format an:
places[.secondLevelField][.thirdLevelField][...]
Wenn Sie nur die Felder formattedAddress und displayName zurückgeben möchten, legen Sie die Feldmaske so fest:
places.formattedAddress,places.displayName
Wenn Sie displayName angeben, sind sowohl die Felder text als auch language von displayName enthalten. Wenn Sie nur das Feld text benötigen, legen Sie die Feldmaske so fest:
places.formattedAddress,places.displayName.text
Antwortfeldmaske für „Place Details (New)“ definieren
„Places Details“ gibt ein einzelnes Ortsobjekt in der folgenden Form zurück:
{
"name": "places/ChIJkR8FdQNB0VQRm64T_lv1g1g",
"id": "ChIJkR8FdQNB0VQRm64T_lv1g1g",
"types": [
"locality",
"political"
],
"formattedAddress": "Trinidad, CA 95570, USA",
"displayName": {
"text": "Trinidad",
"languageCode": "en"
}
...
}
Daher geben Sie für diese API eine Feldmaske an, indem Sie die Felder des Ortsobjekts angeben, die zurückgegeben werden sollen:
curl -X GET -H 'Content-Type: application/json' \ -H "X-Goog-Api-Key: API_KEY" \ -H "X-Goog-FieldMask: formattedAddress,displayName" \ https://places.googleapis.com/v1/places/ChIJj61dQgK6j4AR4GeTYWZsKWw
gRPC-Aufruf
Legen Sie für gRPC eine Variable mit der Antwortfeldmaske fest. Sie können diese Variable dann an die Anfrage übergeben.
const ( fieldMask = "places.formattedAddress,places.displayName" )
Hinweise zu Feldpfaden
Geben Sie nur die Felder an, die Sie in der Antwort benötigen. So rufen Sie nur die benötigten Felder ab:
- Reduziert die Verarbeitungszeiten, sodass die Ergebnisse mit einer geringeren Latenz zurückgegeben werden.
- Sorgt für eine stabile Latenzleistung, wenn der API in Zukunft weitere Antwortfelder hinzugefügt werden und diese neuen Felder zusätzliche Rechenzeit erfordern. Wenn Sie alle Felder oder alle Felder auf oberster Ebene auswählen, kann es zu Leistungseinbußen kommen, wenn alle neuen Felder automatisch in die Antwort eingeschlossen werden.
- Die Antwortgröße ist kleiner, was zu einem höheren Netzwerkdurchsatz führt.
- So wird verhindert, dass Sie unnötige Daten anfordern, was wiederum hilft, unnötige Verarbeitungszeiten und in Rechnung gestellte Gebühren zu vermeiden.