Sélectionnez les champs à afficher

Lorsque vous effectuez 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. Les masques de champ permettent de réduire la latence des réponses en vous évitant de demander des données inutiles.

Pour les méthodes de géocodage de base (Géocoder une adresse, Géocoder un lieu et Géocoder un lieu), tous les champs de l'objet de réponse sont renvoyés par défaut, contrairement à Rechercher des destinations, où il est obligatoire de spécifier un masque de champ. Bien qu'un masque de champ ne soit pas requis pour les méthodes de base, nous vous encourageons vivement à en utiliser un pour réduire la latence des réponses.

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, 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 à 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

Voici 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, au format suivant :

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

Masques de champ pour la recherche de destinations

Lorsque vous appelez SearchDestinations, spécifiez les attributs de destination exacts dont vous avez besoin, tels que les détails du lieu principal, les entrées, les points de navigation, les contours des bâtiments (displayPolygon) et les points de repère :

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

Masques de champ de géocodage de base

Par exemple, pour ne renvoyer que le champ placeId dans une réponse GeocodeAddress, 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/v4/geocode/address/1600+Amphitheatre+Parkway,+Mountain+View,+CA

La réponse est désormais :

{
  "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 :

{
  "results": [
    {
      "viewport": {
        "low": {
          "latitude": 37.420654569708496,
          "longitude": -122.08547618029148
        },
        "high": {
          "latitude": 37.423352530291496,
          "longitude": -122.0827782197085
        }
      }
    }
  ]
}

Pour retourner les deux :

-H 'X-Goog-FieldMask: results.placeId,results.viewport'

La réponse est désormais :

{
  "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 les chemins d'accès aux champs

N'incluez que les champs dont vous avez besoin dans la réponse pour ne renvoyer que les champs dont vous avez besoin :

• Réduction des 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 si vous sélectionnez tous les champs au niveau supérieur, vous risquez de constater une dégradation des performances lorsque de nouveaux champs sont ajoutés, puis automatiquement inclus 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 field_mask.proto.