リクエスト パラメータ

このドキュメントでは、Places Aggregate API のリクエスト パラメータについて説明します。また、このサービスを使用する際の分析情報とベスト プラクティスも紹介します。

Places Aggregate API を使用すると、次の主な機能を実行できます。

  • 場所をカウントする: ロケーション タイプ、営業状況、価格帯、評価など、特定の条件に一致する場所の数を特定します。
  • Place Details を取得する: 指定したフィルタに一致する場所の名前を取得し、Places API を使用して詳細情報を取得します。
  • 柔軟なフィルタリング: 包括的なフィルタを適用して、正確な集計を取得します。使用できるフィルタは次のとおりです。
    • 地理的エリア（円、リージョン、カスタム ポリゴン）
    • 場所タイプ
    • 営業状況
    • 価格帯
    • 評価の範囲

必須パラメータ

このセクションでは、Places Aggregate API にリクエストを発行する際に必要なパラメータについて説明します。各リクエストで、次の情報を指定する必要があります。

  • 分析情報の種類。
  • 地域フィルタとタイプフィルタ。

分析情報の種類

計算する分析情報の種類を指定します。サポートされている分析情報の種類は次のとおりです。

  • INSIGHT_COUNT: フィルタ条件に一致する場所の数を返します。
  • INSIGHT_PLACES: フィルタ条件に一致するプレイス ID を返します。

フィルタ

場所をフィルタリングする条件を指定します。少なくとも LocationFilter と TypeFilter を指定する必要があります。

ロケーション フィルタ

地域フィルタには、次のいずれかのタイプを指定できます。

  • circle: 中心と半径を持つ円としてエリアを定義します。
  • region: 領域をリージョンとして定義します。
  • customArea: カスタム ポリゴンとしてエリアを定義します。
サークル

地理的なエリアを円として選択する場合は、center と radius を指定する必要があります。center には、緯度と経度、または円の中心のプレイス ID を指定できます。この方法では、定義した円形領域に基づいて正確にフィルタリングできます。

  • center:
    • latLng: 円の中心の緯度と経度。緯度は -90 ～ 90 の数値で指定する必要があります。経度は -180 ～ 180 の数値（指定した値を含む）で指定する必要があります。
    • place: 円の中心のプレイス ID。ポイントの場所のみがサポートされています。この文字列は、接頭辞 places/ で始まる必要があります。
  • radius: 円の半径（メートル単位）。この数値は正の値で指定してください。
リージョン

プレイス ID を place パラメータに渡して、エリアをリージョンとして定義します。プレイス ID は、地理的なエリア（ポリゴンで表すことができるエリアなど）を表します。たとえば、フロリダ州タンパのプレイス ID は places/ChIJ4dG5s4K3wogRY7SWr4kTX6c です。すべてのプレイス ID に明確に定義されたジオメトリがあるわけではありません。このような場合、Places Aggregate API は 400 エラーコードを返し、地域がサポートされていないことを示すメッセージを表示します。また、複雑な地理的リージョンの場合、内部処理の最適化により、リージョンを表すエリアがわずかに過大に近似されることがあります（最大 2 ～ 3%）。

プレイス ID がサポートされていないプレイスタイプを表しているかどうかを判断するには、Geocoding API リクエストでプレイス ID を渡します。レスポンスには、プレイス ID に関連付けられたプレイスタイプ（locality、neighborhood、country など）を一覧表示する type 配列が含まれます。いずれかのタイプがこのリストと一致する場合、その場所は地域フィルタリングで拒否されます。

サポートされていない場所の種類は次のとおりです。

  • establishment: 通常、まだ分類されていない場所を示します。
  • intersection: 主要交差点（通常は 2 つの大通りの交差点）を示します。
  • subpremise: 敷地レベルより下のアドレス指定可能なエンティティ（アパート、ユニット、スイートなど）を示します。
カスタムエリア

緯度と経度の座標を使用して、カスタム ポリゴンの領域を定義します。

https://geojson.io/ にアクセスしてカスタム ポリゴンを描画し、それらの座標をリクエストに入力できます。ポリゴンには、少なくとも 4 つの座標が必要です。最初と最後の座標は同じです。指定された座標のうち少なくとも 3 つは一意である必要があります。

連続する同一の座標は、単一の座標として扱われます。ただし、連続していない重複する座標（必須の同一の最初と最後の座標を除く）はエラーになります。

また、隣接していないエッジは交差できません。長さが 180 度のエッジは許可されません（つまり、隣接する頂点は対蹠点にできません）。

次に例を示します。

"coordinates":[
   {
      "latitude":37.776,
      "longitude":-122.666
   },
   {
      "latitude":37.130,
      "longitude":-121.898
   },
   {
      "latitude":37.326,
      "longitude":-121.598
   },
   {
      "latitude":37.912,
      "longitude":-122.247
   },
   {
      "latitude":37.776,
      "longitude":-122.666
   }
]

タイプ フィルタ

含める場所のタイプまたは除外する場所のタイプを指定します。Places Aggregate API でサポートされているプライマリとセカンダリの場所タイプの一覧については、Places API（New）の場所タイプの表 A をご覧ください。少なくとも 1 つの includedTypes タイプまたは includedPrimaryTypes タイプを指定する必要があります。

  • includedTypes: 含まれる場所タイプのリスト。
  • excludedTypes: 除外する場所タイプのリスト。
  • includedPrimaryTypes: 含まれるプライマリ プレイスタイプのリスト。
  • excludedPrimaryTypes: 除外するプライマリ プレイスタイプのリスト。

タイプフィルタと場所タイプの仕組みの詳細については、タイプフィルタの詳細をご覧ください。

オプション パラメータ

次のフィルタは省略可能です。

  • operatingStatus: 含める、または除外する場所のステータスを指定します。デフォルトでは、operatingStatus: OPERATING_STATUS_OPERATIONAL（1 つの特定の値）でフィルタリングされます。
  • priceLevels: 検索対象に含める場所の価格レベルを指定します。デフォルトでは、価格レベルのフィルタリングは適用されず、すべての場所（価格レベル情報のない場所を含む）が返されます。
  • ratingFilter: 場所の評価範囲を指定します。デフォルトではフィルタリングは行われません（すべての評価が結果に含まれます）。

営業状況

operatingStatus フィルタを使用すると、OPERATIONAL や TEMPORARILY_CLOSED などの営業状況に基づいてフィルタできます。operatingStatus フィルタの動作は次のとおりです。

  • フィルタが指定されていない場合、営業状況が OPERATING_STATUS_OPERATIONAL の場所のみが結果に含まれます。
  • 1 つ以上のフィルタを指定する場合は、有効な営業状況の値（OPERATING_STATUS_OPERATIONAL、OPERATING_STATUS_PERMANENTLY_CLOSED、OPERATING_STATUS_TEMPORARILY_CLOSED）を指定する必要があります。

価格帯

priceLevels フィルタを使用すると、価格レベルに基づいて場所をフィルタできます。有効な価格レベルの値は、PRICE_LEVEL_FREE、PRICE_LEVEL_INEXPENSIVE、PRICE_LEVEL_MODERATE、PRICE_LEVEL_EXPENSIVE、PRICE_LEVEL_VERY_EXPENSIVE です。

priceLevels フィルタの動作は次のとおりです。

  • フィルタが指定されていない場合: 価格レベルが割り当てられているかどうかに関係なく、すべての場所が返されます。これには、価格レベル情報のない場所も含まれます。これらの場所は、特定の価格レベルでフィルタリングすると返されない場合があります。
  • 1 つ以上のフィルタが指定されている場合: 指定された価格レベルに一致する場所のみが返されます。

評価フィルタ

ユーザーの平均評価に基づいて場所をフィルタします。どちらのフィールドも省略可能であるため、省略すると、デフォルトで評価のない場所も含まれます。

  • minRating: ユーザーの評価の平均の最小値（1.0 ～ 5.0）。
  • maxRating: ユーザーの評価の平均の最大値（1.0 ～ 5.0）。

また、minRating 値は常に maxRating 値以下にする必要があります。minRating が maxRating より大きい値として指定されている場合、INVALID_ARGUMENT エラーが返されます。