Felder für die Rückgabe auswählen

Entwickler im Europäischen Wirtschaftsraum (EWR)

Einführung

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 der entsprechenden SKUs finden Sie unter Felder für Ortsdaten (neu). Informationen zu den Feldern, die für die einzelnen APIs spezifisch sind, finden Sie hier:

  • Place Details (Neu) FieldMask-Parameter
  • „Nearby Search (New)“-Parameter für FieldMask
  • FieldMask-Parameter für „Text Search (New)“

Sie geben die Feldliste an, indem Sie eine Antwortfeldmaske erstellen. Sie übergeben die Antwortfeldmaske dann mit dem Parameter $fields oder fields oder mit dem HTTP- oder gRPC-Header X-Goog-FieldMask an eine der beiden Methoden.

Mit der Maskierung von Feldern lässt sich verhindern, dass unnötige Daten angefordert werden, was wiederum hilft, unnötige Verarbeitungszeiten und Gebühren zu vermeiden.

Feldmaske für die Antwort definieren

Die Antwortfeldmaske ist eine durch Kommas getrennte Liste von Pfaden, wobei jeder Pfad ein eindeutiges Feld im Antworttext angibt. Der Pfad beginnt mit der Antwortnachricht der obersten Ebene und verwendet einen durch Punkte getrennten Pfad zum angegebenen Feld.

So erstellen Sie einen Feldpfad:

topLevelField[.secondLevelField][.thirdLevelField][...]

Sie können alle Felder anfordern, indem Sie die Feldmaske * verwenden.

Weitere Informationen zum Erstellen von Feldmasken finden Sie unter field_mask.proto.

Zu verwendende Feldmasken festlegen

So ermitteln Sie, welche Feldmasken Sie verwenden möchten:

  1. Fordern Sie alle Felder mit der Feldmaske * an.
  2. Sehen Sie sich die Hierarchie der Felder in der Antwort an und legen Sie fest, welche Felder Sie benötigen.
  3. Erstellen Sie die Feldmaske mithilfe der Feldhierarchie.

Antwortfeldmaske für Nearby Search (New) und Text Search (New) definieren

Bei „Nearby Search (New)“ und „Text Search (New)“ wird ein Array von Place-Objekten im Feld places der Antwort zurückgegeben. Bei diesen APIs ist places das Feld der obersten Ebene der Antwort.

So rufen Sie beispielsweise das vollständige Antwortobjekt aus 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 das folgende 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 eine Feldmaske für diese APIs in folgender Form 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

„Place Details (New)“ gibt ein einzelnes Place-Objekt in folgendem Format 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 Place-Objekts 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 Feldmaske für die Antwort fest. Anschließend können Sie diese Variable an die Anfrage übergeben.

const (
  fieldMask = "places.formattedAddress,places.displayName"
)

Hinweise zu Feldpfaden

Nehmen Sie nur die Felder in die Antwort auf, die Sie benötigen. Nur die benötigten Felder zurückgeben:

  • Verkürzt die Verarbeitungszeiten, sodass Ihre Ergebnisse mit einer geringeren Latenz zurückgegeben werden.
  • Sorgt für eine stabile Latenzleistung, wenn die API in Zukunft weitere Antwortfelder hinzufügt, die zusätzliche Rechenzeit erfordern. Wenn Sie alle Felder oder alle Felder auf der obersten Ebene auswählen, kann es zu Leistungseinbußen kommen, wenn alle neuen Felder automatisch in Ihre Antwort aufgenommen werden.
  • Führt zu einer kleineren Antwortgröße, was zu einem höheren Netzwerkdurchsatz führt.
  • Verhindert, dass unnötige Daten angefordert werden, was wiederum hilft, unnötige Verarbeitungszeiten und Gebühren zu vermeiden.