Lorsque vous envoyez une requête de géocodage, vous pouvez utiliser un masque de champ pour spécifier la liste des champs à renvoyer dans la réponse. Par défaut, la requête renvoie tous les champs de l'objet de réponse.
Utilisez un masque de champ pour vous assurer de ne pas demander de données inutiles, ce qui permet de réduire la latence de 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 des virgules 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 des points vers un champ spécifié.
Transmettez le masque de champ de réponse à une requête en utilisant le paramètre d'URL $fields ou fields, ou en utilisant 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 géocodage 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 en utilisant la hiérarchie des champs de réponse, sous la forme suivante :
topLevelField[.secondLevelField][.thirdLevelField][...]
Par exemple, pour ne renvoyer que le champ placeId dans la réponse, utilisez un masque de champ :
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/v4beta/"geocode/address/1600+Amphitheatre+Parkway,+Mountain+View,+CA"
La réponse est désormais la suivante :
{ "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 désormais la suivante :
{ "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 désormais la suivante :
{ "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" )
Remarques concernant les chemins d'accès aux champs
N'incluez que les champs dont vous avez besoin dans la réponse :
- Réduit les temps de traitement, ce qui permet de renvoyer vos résultats avec une latence plus faible.
- Garantit des performances de latence stables. Si vous sélectionnez tous les champs ou tous les champs au niveau supérieur, vous risquez de constater une dégradation des performances lorsque de nouveaux champs sont ajoutés et inclus automatiquement dans votre réponse.
- La taille de la réponse est plus petite, 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 field_mask.proto.