リクエストパラメータ

このドキュメントでは、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%）。

重要: region フィルタを INSIGHT_PLACES 分析情報の種類で使用する場合、Google サービスの精度と中立性を確保するため、紛争地域を含むリクエストは自動的に拒否されます。紛争地域とは、国やエンティティによって境界や領有権が異なる地域のことです。紛争中の境界は、Google マップに灰色の破線で表示されます。

紛争地域がどのように特定されるかについて詳しくは、国境と国名を理解するをご覧ください。

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

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

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

注: 上記にリストされていないプレイスでも、明確に定義されたポリゴンジオメトリがない場合は拒否されることがあります。これは、 neighborhood、locality、sublocality などのタイプや、その番号付きのバリアント (sublocality_level_1、sublocality_level_2、sublocality_level_3、 sublocality_level_4)でよく見られます。この場合、400 エラーコードが返されます。

カスタムエリア

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

https://geojson.io/ にアクセスしてカスタムポリゴンを描画し、その座標をリクエストに入力できます。A ポリゴンには、少なくとも 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 でサポートされているプライマリとセカンダリの両方の場所タイプの一覧については、表 A の 場所タイプ（Places API （新しい））をご覧ください。少なくとも 1 つの includedTypes または includedPrimaryTypes タイプを指定する必要があります。

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

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

注: タイプフィルタには、指定したタイプのサブタイプが自動的に含まれます。たとえば、gym でフィルタすると、yoga_studio などのサブタイプに分類される場所も結果に含まれます。

オプションパラメータ

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

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