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

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

Sie geben die Feldliste an, indem Sie eine Antwortfeldmaske erstellen. Anschließend übergeben Sie die Antwortfeldmaske an eine der beiden Methoden. Verwenden Sie dazu den Parameter $fields oder fields, oder den HTTP- oder gRPC-Header X-Goog-FieldMask.

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.

Antwortfeldmaske 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 auf oberster Ebene und verwendet einen durch Punkte getrennten Pfad zum angegebenen Feld.

So erstellen Sie einen Feldpfad:

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

Sie können alle Felder mit einer Feldmaske von * anfordern.

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

Zu verwendende Feldmasken bestimmen

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

  1. Fordern Sie alle Felder mit einer Feldmaske von * an.
  2. Sehen Sie sich die Hierarchie der Felder in der Antwort an und bestimmen Sie, welche Felder Sie benötigen.
  3. Erstellen Sie Ihre Feldmaske anhand der Feldhierarchie.

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

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

Beispiel für das vollständige Antwortobjekt aus einer „Text Search (New)“-Anfrage:

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 aus einem „Text Search (New)“-Aufruf 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 eine Feldmaske für diese APIs im folgenden 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, werden sowohl die Felder text als auch language von displayName berücksichtigt. 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 im folgenden 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 eine Feldmaske für diese API 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 fest, die die Antwortfeldmaske enthält. 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. Wenn Sie nur die Felder zurückgeben, die Sie benötigen:

  • Verringern sich die Verarbeitungszeiten, sodass Ihre Ergebnisse mit einer geringeren Latenz zurückgegeben werden.
  • Bleibt die Latenz stabil, wenn die API in Zukunft weitere Antwortfelder hinzufügt und für diese neuen Felder zusätzliche Rechenzeit erforderlich ist. Wenn Sie alle Felder oder alle Felder auf oberster Ebene auswählen, kann es zu Leistungseinbußen kommen, wenn alle neuen Felder automatisch in Ihre Antwort aufgenommen werden.
  • Ist die Antwort kleiner, was zu einem höheren Netzwerk durchsatz führt.
  • Fordern Sie keine unnötigen Daten an, was wiederum hilft, unnötige Verarbeitungszeiten und Gebühren zu vermeiden.