Wenn Sie eine Geocoding-Anfrage stellen, können Sie mit einer Feldmaske die Liste der Felder angeben, die in der Antwort zurückgegeben werden sollen. Feldmasken helfen, die Antwortlatenz zu verringern, da Sie keine unnötigen Daten anfordern.
Bei grundlegenden Geocodierungsmethoden (Adresse geocodieren, Ort geocodieren und Ort geocodieren) werden standardmäßig alle Felder im Antwortobjekt zurückgegeben. Bei Nach Zielen suchen ist dagegen die Angabe einer Feldmaske erforderlich. Für grundlegende Methoden ist eine Feldmaske zwar nicht erforderlich, wir empfehlen jedoch dringend, eine zu verwenden, um die Antwortlatenz zu verringern.
Antwortfeldmaske definieren
Die Antwortfeldmaske ist eine durch Kommas getrennte Liste von Pfaden ohne Leerzeichen, wobei jeder Pfad ein eindeutiges Feld im Antwortobjekt angibt. Der Pfad beginnt im Antwortfeld der obersten Ebene und verwendet einen durch Punkte getrennten Pfad zu einem angegebenen Feld.
Übergeben Sie die Antwortfeldmaske an eine Anfrage, indem Sie den URL-Parameter $fields oder fields oder den HTTP- oder gRPC-Header X-Goog-FieldMask verwenden.
Beispiele für Feldmasken
Unten sehen Sie die vollständige Antwort auf eine Anfrage zur Forward Geocoding:
{ "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][...]
Feldmasken für Ziele suchen
Geben Sie beim Aufrufen von SearchDestinations die genauen Zielattribute an, die Sie benötigen, z. B. die primären Ortsdetails, Eingänge, Navigationspunkte, Gebäudeumrisse (displayPolygon) und Sehenswürdigkeiten:
curl -X POST -d '{"addressQuery": {"addressQuery": "1600 Amphitheatre Pkwy, Mountain View, CA"}}' \
-H 'Content-Type: application/json' \
-H 'X-Goog-FieldMask: destinations.primary.displayName,destinations.primary.displayPolygon,destinations.entrances,destinations.navigationPoints,destinations.landmarks' \
-H "X-Goog-Api-Key: API_KEY" \
https://geocode.googleapis.com/v4/geocode/destinations
Wichtige Feldmasken für die Geocodierung
Wenn Sie beispielsweise nur das Feld placeId in einer GeocodeAddress-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 lautet jetzt:
{ "results": [ { "placeId": "ChIJF4Yf2Ry7j4AR__1AkytDyAE" } ] }
Wenn Sie das Feld viewport zurückgeben möchten, lautet die Feldmaske:
-H 'X-Goog-FieldMask: results.viewport'
Die Antwort lautet jetzt:
{ "results": [ { "viewport": { "low": { "latitude": 37.420654569708496, "longitude": -122.08547618029148 }, "high": { "latitude": 37.423352530291496, "longitude": -122.0827782197085 } } } ] }
So gibst du beide zurück:
-H 'X-Goog-FieldMask: results.placeId,results.viewport'
Die Antwort lautet jetzt:
{ "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 Antwortfeldmaske enthält. Anschließend können Sie diese Variable an die Anfrage übergeben.
const ( fieldMask = "results.placeId,results.viewport" )
Hinweise zu Feldpfaden
Geben Sie nur die Felder an, die Sie in der Antwort benötigen, damit nur diese Felder zurückgegeben werden:
- Verkürzt die Verarbeitungszeiten, sodass die 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 und dann automatisch in die Antwort aufgenommen werden.
- Führt zu einer kleineren Antwortgröße, was zu einem höheren Netzwerkdurchsatz führt.
Weitere Informationen zum Erstellen einer Feldmaske finden Sie unter field_mask.proto.