返すフィールドを選択する

欧州経済領域（EEA）のデベロッパー

はじめに

Place Details（新版）、Nearby Search（新版）、またはテキスト検索（新版）メソッドを呼び出す場合は、レスポンスで返されるフィールドを指定する必要があります。返されるフィールドのデフォルトのリストはありません。このリストを省略すると、メソッドはエラーを返します。

サポートされているデータ フィールドとそれに対応する SKU の完全なリストについては、プレイス データ フィールド（新版）をご覧ください。各 API に固有のフィールドについては、以下をご覧ください。

  • Place Details（新規）FieldMask パラメータ
  • Nearby Search（新版）の FieldMask パラメータ
  • テキスト検索（新版）の FieldMask パラメータ

フィールド リストは、レスポンス フィールド マスクを作成して指定します。次に、パラメータ $fields または fields を使用するか、HTTP ヘッダーまたは gRPC ヘッダー X-Goog-FieldMask を使用して、レスポンス フィールド マスクをいずれかのメソッドに渡します。

フィールド マスキングは、不要なデータをリクエストしないようにするための優れた設計手法です。これにより、不要な処理時間と課金を回避できます。

レスポンス フィールド マスクを定義する

レスポンス フィールド マスクはパスのカンマ区切りのリストです。各パスは、レスポンスの本文内の一意のフィールドを指定します。パスは最上位のレスポンス メッセージから始まり、ドットで区切られたパスを使用して指定されたフィールドに移動します。

次のようにフィールド パスを作成します。

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

* のフィールド マスクを使用すると、すべてのフィールドをリクエストできます。

フィールド マスクの作成方法の詳細については、field_mask.proto をご覧ください。

使用するフィールド マスクを決定する

使用するフィールド マスクを決定する方法は次のとおりです。

  1. * のフィールド マスクを使用してすべてのフィールドをリクエストします。
  2. レスポンスのフィールドの階層を確認し、必要なフィールドを特定します。
  3. フィールド階層を使用してフィールド マスクを構築します。

Nearby Search（新版）とテキスト検索（新版）のレスポンス フィールド マスクを定義する

Nearby Search（新版）とテキスト検索（新版）は、レスポンスの places フィールドに Place オブジェクトの配列を返します。これらの API では、places はレスポンスの最上位フィールドです。

たとえば、テキスト検索（新版）から完全なレスポンス オブジェクトを取得するには:

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'

テキスト検索（新版）呼び出しからの完全なレスポンス オブジェクトは次の形式です。

{
  "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"
      },      ...
    },
  ...
  ]
}

したがって、これらの API のフィールド マスクは次の形式で指定します。

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

formattedAddress フィールドと displayName フィールドのみを返す場合は、フィールド マスクを次のように設定します。

places.formattedAddress,places.displayName

displayName を指定すると、displayName の text フィールドと language フィールドの両方が含まれます。text フィールドのみが必要な場合は、フィールド マスクを次のように設定します。

places.formattedAddress,places.displayName.text

Place Details（新版）のレスポンス フィールド マスクを定義する

Place Details (New) は、次の形式で単一の Place オブジェクトを返します。

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

したがって、この API のフィールド マスクは、返す Place オブジェクトのフィールドを指定することで指定します。

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

gRPC 呼び出し

gRPC の場合は、レスポンス フィールド マスクを含む変数を設定します。この変数をリクエストに渡すことができます。

const (
  fieldMask = "places.formattedAddress,places.displayName"
)

フィールドパスに関する考慮事項

レスポンスに必要なフィールドのみを含めます。必要なフィールドのみを返す:

  • 処理時間が短縮されるため、結果が低レイテンシで返されます。
  • API で今後レスポンス フィールドが追加され、それらの新しいフィールドで追加の計算時間が必要になった場合でも、レイテンシのパフォーマンスを安定させます。すべてのフィールドを選択した場合、または最上位ですべてのフィールドを選択した場合、新しいフィールドがすべてレスポンスに自動的に含まれると、パフォーマンスが低下する可能性があります。
  • レスポンス サイズが小さくなるため、ネットワーク スループットが向上します。
  • 不要なデータをリクエストしないようにすることで、不要な処理時間や請求料金を回避できます。