Wenn Sie eine Geocoding-Anfrage senden, können Sie eine Feldmaske verwenden, um die Liste der Felder anzugeben, die in der Antwort zurückgegeben werden sollen. Feldmasken tragen dazu bei, die Antwortlatenz zu verringern, da Sie keine unnötigen Daten anfordern.
Bei den Methoden „Geocode an address“, „Geocode a location“ und „Place geocoding“ werden standardmäßig alle Felder im Antwortobjekt zurückgegeben. Eine Feldmaske ist zwar nicht erforderlich, wir empfehlen Ihnen jedoch dringend, sie zu verwenden, um die Antwortlatenz zu verringern.
Feldmaske für die Antwort definieren
Die Feldmaske für die Antwort ist eine durch Kommas getrennte Liste von Pfaden ohne Leerzeichen. Jeder Pfad gibt ein eindeutiges Feld im Antwortobjekt an. Der Pfad beginnt mit dem Antwortfeld der obersten Ebene und verwendet einen durch Punkte getrennten Pfad zu einem bestimmten Feld.
Übergeben Sie die Feldmaske für die Antwort an eine Anfrage, indem Sie den URL-Parameter $fields
oder fields, oder den HTTP- oder gRPC-Header X-Goog-FieldMask verwenden.
Beispiel für Feldmasken
Unten sehen Sie die vollständige Antwort auf eine Anfrage für das Geocoding von Adressen:
{ "results": [ { "place": "//places.googleapis.com/places/ChIJF4Yf2Ry7j4AR__1AkytDyAE", "placeId": "ChIJF4Yf2Ry7j4AR__1AkytDyAE", "location": { "latitude": 37.422010799999995, "longitude": -122.08474779999999 }, "granularity": "ROOFTOP", "viewport": { "low": { "latitude": 37.420656719708511, "longitude": -122.08547523029148 }, "high": { "latitude": 37.4233546802915, "longitude": -122.0827772697085 } }, "formattedAddress": "1600 Amphitheatre Pkwy, Mountain View, CA 94043, USA", ... }
Erstellen Sie Ihre Feldmasken anhand der Hierarchie der Antwortfelder im folgenden Format:
topLevelField[.secondLevelField][.thirdLevelField][...]
Wenn Sie beispielsweise nur das Feld placeId in der Antwort zurückgeben möchten, verwenden Sie die folgende Feldmaske:
curl -X GET -H 'Content-Type: application/json' \ -H 'X-Goog-FieldMask: results.placeId' \ -H "X-Goog-Api-Key: API_KEY" \ https://geocode.googleapis.com/v4/geocode/address/1600+Amphitheatre+Parkway,+Mountain+View,+CA
Die Antwort sieht jetzt so aus:
{ "results": [ { "placeId": "ChIJF4Yf2Ry7j4AR__1AkytDyAE" } ] }
Wenn Sie das Feld viewport zurückgeben möchten, lautet die Feldmaske:
-H 'X-Goog-FieldMask: results.viewport'
Die Antwort sieht jetzt so aus:
{ "results": [ { "viewport": { "low": { "latitude": 37.420654569708496, "longitude": -122.08547618029148 }, "high": { "latitude": 37.423352530291496, "longitude": -122.0827782197085 } } } ] }
Wenn Sie beide zurückgeben möchten:
-H 'X-Goog-FieldMask: results.placeId,results.viewport'
Die Antwort sieht jetzt so aus:
{ "results": [ { "placeId": "ChIJF4Yf2Ry7j4AR__1AkytDyAE", "viewport": { "low": { "latitude": 37.420654569708496, "longitude": -122.08547618029148 }, "high": { "latitude": 37.423352530291496, "longitude": -122.0827782197085 } } } ] }
gRPC-Feldmasken
Legen Sie für gRPC eine Variable fest, die die Feldmaske für die Antwort enthält. Anschließend können Sie diese Variable an die Anfrage übergeben.
const ( fieldMask = "results.placeId,results.viewport" )
Hinweise zu Feldpfaden
Fügen Sie nur die Felder ein, die Sie in der Antwort benötigen, um nur die Felder zurückzugeben, die Sie benötigen:
- Verringert die Verarbeitungszeiten, sodass Ihre Ergebnisse mit einer geringeren Latenz zurückgegeben werden.
- Sorgt für eine stabile Latenzleistung. Wenn Sie alle Felder oder alle Felder auf der obersten Ebene auswählen, kann es zu Leistungseinbußen kommen, wenn neue Felder hinzugefügt werden und dann automatisch in Ihre Antwort aufgenommen werden.
- Führt zu einer kleineren Antwortgröße, was zu einem höheren Netzwerk durchsatz führt.
Weitere Informationen zum Erstellen einer Feldmaske finden Sie unter field_mask.proto.