Lorsque vous effectuez une requête de geocoding, vous pouvez utiliser un masque de champ pour spécifier la liste des champs à renvoyer dans la réponse. Les masques de champ contribuent à réduire la latence de la réponse en vous assurant de ne pas demander de données inutiles.
Pour les méthodes Geocode an address, Geocode a location et Place geocoding, tous les champs de l'objet de réponse sont renvoyés par défaut. Bien qu'un masque de champ ne soit pas obligatoire, nous vous encourageons vivement à l'utiliser pour réduire la latence de la réponse.
Définir un masque de champ de réponse
Le masque de champ de réponse est une liste de chemins d'accès séparés par une virgule et sans espaces, où chaque chemin d'accès spécifie un champ unique dans l'objet de réponse. Le chemin d'accès commence par le champ de réponse de premier niveau et utilise un chemin d'accès séparé par un point vers un champ spécifié.
Transmettez le masque de champ de réponse à une requête à l'aide du paramètre d'URL $fields
ou fields, ou à l'aide de l'en-tête HTTP ou gRPC X-Goog-FieldMask.
Exemples de masques de champ
Vous trouverez ci-dessous la réponse complète à une requête de geocoding direct :
{ "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", ... }
Créez vos masques de champ à l'aide de la hiérarchie des champs de réponse, au format suivant :
topLevelField[.secondLevelField][.thirdLevelField][...]
Par exemple, pour ne renvoyer que le champ placeId dans la réponse, utilisez un masque de champ de :
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
La réponse est maintenant :
{ "results": [ { "placeId": "ChIJF4Yf2Ry7j4AR__1AkytDyAE" } ] }
Pour renvoyer le champ viewport, votre masque de champ est le suivant :
-H 'X-Goog-FieldMask: results.viewport'
La réponse est maintenant :
{ "results": [ { "viewport": { "low": { "latitude": 37.420654569708496, "longitude": -122.08547618029148 }, "high": { "latitude": 37.423352530291496, "longitude": -122.0827782197085 } } } ] }
Pour renvoyer les deux :
-H 'X-Goog-FieldMask: results.placeId,results.viewport'
La réponse est maintenant :
{ "results": [ { "placeId": "ChIJF4Yf2Ry7j4AR__1AkytDyAE", "viewport": { "low": { "latitude": 37.420654569708496, "longitude": -122.08547618029148 }, "high": { "latitude": 37.423352530291496, "longitude": -122.0827782197085 } } } ] }
Masques de champ gRPC
Pour gRPC, définissez une variable contenant le masque de champ de réponse. Vous pouvez ensuite transmettre cette variable à la requête.
const ( fieldMask = "results.placeId,results.viewport" )
Points à prendre en compte concernant le chemin d'accès au champ
N'incluez que les champs dont vous avez besoin dans la réponse pour ne renvoyer que les champs dont vous avez besoin :
- Réduit les temps de traitement, de sorte que vos résultats sont renvoyés avec une latence plus faible.
- Garantit des performances de latence stables. Si vous sélectionnez tous les champs ou tous les champs de premier niveau, vous risquez de constater une dégradation des performances lorsque de nouveaux champs sont ajoutés et inclus automatiquement dans votre réponse.
- Réduit la taille de la réponse, ce qui se traduit par un débit réseau plus élevé.
Pour en savoir plus sur la création d'un masque de champ, consultez le field_mask.proto.