Sélectionnez les champs à afficher

Lorsque vous appelez les méthodes Place Details (New) (Informations sur le lieu (Nouveau)), Nearby Search (New) (Recherche à proximité (Nouveau)) ou Text Search (New) (Recherche dans le texte (Nouveau)), vous devez spécifier les champs que vous souhaitez renvoyer dans la réponse. Il n'existe pas de liste par défaut des champs renvoyés. Si vous omettez cette liste, les méthodes renvoient une erreur.

Vous trouverez la liste complète des champs de données compatibles et des SKU correspondants dans Champs de données Places (nouveaux). Pour en savoir plus sur les champs spécifiques à chaque API, consultez les documents suivants:

  • Paramètres FieldMask des informations sur le lieu (nouveau)
  • Paramètres FieldMask de Nearby Search (nouveau)
  • Paramètres FieldMask de la recherche textuelle (nouvelle)

Vous spécifiez la liste des champs en créant un masque de champ de réponse. Vous transmettez ensuite le masque de champ de réponse à l'une des méthodes à l'aide du paramètre $fields ou fields, ou à l'aide de l'en-tête HTTP ou gRPC X-Goog-FieldMask.

Le masquage de champ est une bonne pratique de conception pour vous assurer de ne pas demander de données inutiles, ce qui permet d'éviter les temps de traitement et les frais de facturation inutiles.

Définir un masque de champ de réponse

Le masque de champ de réponse est une liste de chemins séparés par une virgule, où chaque chemin spécifie un champ unique dans le corps de la réponse. Le chemin d'accès commence à partir du message de réponse de niveau supérieur et utilise un chemin d'accès au champ spécifié séparé par des points.

Créez un chemin de champ comme suit:

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

Vous pouvez demander tous les champs en utilisant un masque de champ *.

Pour en savoir plus sur la création de masques de champ, consultez field_mask.proto.

Déterminer les masques de champ à utiliser

Voici comment déterminer les masques de champ que vous souhaitez utiliser:

  1. Demandez tous les champs à l'aide d'un masque de champ *.
  2. Examinez la hiérarchie des champs dans la réponse et déterminez les champs qui vous intéressent.
  3. Créez votre masque de champ à l'aide de la hiérarchie des champs.

Définir un masque de champ de réponse pour Nearby Search (nouveau) et Text Search (nouveau)

Nearby Search (nouveau) et Text Search (nouveau) renvoient un tableau d'objets Place dans le champ places de la réponse. Pour ces API, places est le champ de niveau supérieur de la réponse.

Par exemple, pour afficher l'objet de réponse complet d'une recherche textuelle (nouvelle):

curl -X POST -d '{
  "textQuery" : "Spicy Vegetarian Food in Sydney, Australia"
}' \
-H 'Content-Type: application/json' -H 'X-Goog-Api-Key: API_KEY' \
-H 'X-Goog-FieldMask: *' \
'https://places.googleapis.com/v1/places:searchText'

L'objet de réponse complet d'un appel Text Search (New) se présente sous la forme suivante:

{
  "places": [
    {
      "name": "places/ChIJs5ydyTiuEmsR0fRSlU0C7k0",
      "id": "ChIJs5ydyTiuEmsR0fRSlU0C7k0",
      "types": [
        "vegetarian_restaurant",
        "vegan_restaurant",
        "meal_takeaway",
        "restaurant",
        "food",
        "point_of_interest",
        "establishment"
      ],
      "nationalPhoneNumber": "0433 479 794",
      "internationalPhoneNumber": "+61 433 479 794",
      "formattedAddress": "29 King St, Sydney NSW 2000, Australia",
      "displayName": {
        "text": "Spiced @ Barangaroo",
        "languageCode": "en"
      },      ...
    },
  ...
  ]
}

Vous devez donc spécifier un masque de champ pour ces API sous la forme suivante:

places[.secondLevelField][.thirdLevelField][...]

Si vous ne souhaitez renvoyer que les champs formattedAddress et displayName, définissez votre masque de champ sur:

places.formattedAddress,places.displayName

Spécifier displayName inclut à la fois les champs text et language de displayName. Si vous ne souhaitez que le champ text, définissez le masque de champ comme suit:

places.formattedAddress,places.displayName.text

Définir un masque de champ de réponse pour Place Details (New)

Place Details renvoie un seul objet Place sous la forme suivante:

{
  "name": "places/ChIJkR8FdQNB0VQRm64T_lv1g1g",
  "id": "ChIJkR8FdQNB0VQRm64T_lv1g1g",
  "types": [
    "locality",
    "political"
  ],
  "formattedAddress": "Trinidad, CA 95570, USA",
  "displayName": {
    "text": "Trinidad",
    "languageCode": "en"
  }
  ...
}

Par conséquent, vous devez spécifier un masque de champ pour cette API en spécifiant les champs de l'objet Place que vous souhaitez renvoyer:

curl -X GET -H 'Content-Type: application/json' \
-H "X-Goog-Api-Key: API_KEY" \
-H "X-Goog-FieldMask: formattedAddress,displayName" \
https://places.googleapis.com/v1/places/ChIJj61dQgK6j4AR4GeTYWZsKWw

Appel 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 = "places.formattedAddress,places.displayName"
)

Considérations concernant le chemin d'accès au champ

N'incluez dans la réponse que les champs dont vous avez besoin. Il ne renvoie que les champs dont vous avez besoin:

  • Réduit les temps de traitement, ce qui permet de renvoyer vos résultats avec une latence plus faible.
  • Assure des performances de latence stables si l'API ajoute d'autres champs de réponse à l'avenir et que ces nouveaux champs nécessitent un temps de calcul supplémentaire. 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 tous les nouveaux champs sont automatiquement inclus dans votre réponse.
  • Résulte en une taille de réponse plus petite, ce qui se traduit par un débit réseau plus élevé.
  • Assure que vous ne demandez pas de données inutiles, ce qui permet d'éviter un temps de traitement et des frais facturés inutiles.