リクエスト パラメータ

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

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

  • 場所の数を取得する: 場所の種類、営業状況、価格帯、評価などの特定の条件に一致する場所の数を取得します。
  • 場所の詳細を取得する: 指定されたフィルタに一致する場所の名前を取得し、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: 円の半径（メートル単位）。この数値は正の値でなければなりません。
地域

place パラメータにプレイス ID を渡して、地域をリージョンとして定義します。プレイス 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 つは一意である必要があります。

連続して同じ座標が指定された場合は、1 つの座標として扱われます。ただし、連続しない重複座標（必須の同一の最初と最後の座標を除く）はエラーになります。

また、隣接しないエッジが交差することは許可されず、長さが 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 をご覧ください。includedTypes または includedPrimaryTypes 型を少なくとも 1 つ指定する必要があります。

  • 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 エラーが返されます。