このドキュメントでは、Places Insights API のリクエスト パラメータについて説明します。また、このサービスの使用に関する分析情報とベスト プラクティスも記載しています。
Places Insights API を使用すると、次の重要な機能を実行できます。
- 場所の数をカウントする: 場所のタイプ、営業状況、価格帯、評価などの特定の条件に一致する場所の数を特定します。
- 場所の詳細を取得する: 指定したフィルタに一致する場所の名前を取得し、Places API を使用して詳細情報を取得します。
- 柔軟なフィルタリング: 包括的なフィルタを適用して、正確な分析情報を取得します。使用できるフィルタは次のとおりです。
- 地理的エリア（円、地域、カスタム ポリゴン）
- 場所タイプ
- 営業状況
- 価格帯
- 評価範囲
必須パラメータ
このセクションでは、Places Insights 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 Insights API は、リージョンがサポートされていないことを示すメッセージとともに 400 エラーコードを返します。また、複雑な地理的地域では、内部処理の最適化により、地域を表すエリアがわずかに過大に近似される（最大 2 ～ 3%）可能性があります。
プレイス ID がサポートされていないプレイスタイプを表しているかどうかを確認するには、Geocoding API リクエストでプレイス ID を渡します。レスポンスには、プレイス ID に関連付けられているプレイスタイプ（city、neighborhood、country など）を一覧表示する type 配列が含まれます。
サポートされていないスポットタイプは次のとおりです。
establishment: 通常、まだ分類されていない場所を示します。street_number: 正確な番地を示します。floor: 建物の階数を示します。post_box: 特定の郵便ポストを示します。street_address: 正確な住所を示します。room: 建物の部屋を示します。intersection: 主要交差点（通常は 2 つの大通りの交差点）を示します。landmark: ナビゲーションを支援するために参照として使用される付近の場所を示します。subpremise: 敷地レベルより下位のアドレス指定可能なエンティティ（アパート、ユニット、スイートなど）を示します。sublocality_level_5: 住所の最も詳細なサブローカリティー コンポーネント。通常は、非常に小さな近隣地区や都市内の超ローカルエリアを表します。
カスタム領域
緯度と経度の座標を使用してカスタム ポリゴンの領域を定義します。
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 Insights API でサポートされているプライマリ タイプとセカンダリ タイプの一覧については、Places API（新規）の場所タイプの表 A をご覧ください。includedTypes 型または includedPrimaryTypes 型を少なくとも 1 つ指定する必要があります。
includedTypes: 含まれる場所の種類のリスト。excludedTypes: 除外される場所の種類のリスト。includedPrimaryTypes: 含まれる主な場所の種類のリスト。excludedPrimaryTypes: 除外されるプライマリ プレイスタイプ。
タイプフィルタとプレイスタイプの仕組みの詳細については、タイプフィルタの詳細をご覧ください。
オプション パラメータ
次のフィルタは省略可能です。
operatingStatus: 含める場所または除外する場所のステータスを指定します。デフォルトはoperatingStatus: OPERATING_STATUS_OPERATIONAL（1 つの特定の値）によるフィルタリングです。priceLevels: 場所の料金レベルを指定します。デフォルトではフィルタなし（すべての価格帯が結果に含まれます）。ratingFilter: 場所の評価範囲を指定します。デフォルトではフィルタなし（すべての評価が結果に含まれます）。
営業状況
operatingStatus フィルタを使用すると、営業状況（営業中、臨時休業など）に基づいてフィルタできます。operatingStatus フィルタが設定されていない場合、営業ステータスが OPERATING_STATUS_OPERATIONAL の場所のみが結果に含まれます。
価格帯
price_levels フィルタを使用すると、価格帯（無料、中程度、高価など）に基づいてフィルタできます。price_levels フィルタが設定されていない場合、すべての料金レベルが結果に含まれます。
評価フィルタ
ユーザーの平均評価に基づいて場所をフィルタします。これらのフィールドはどちらも省略可能であるため、省略すると、デフォルトで評価のない場所も含まれます。
minRating: 最低平均ユーザー評価（1.0 ～ 5.0）。maxRating: 最大平均ユーザー評価（1.0 ～ 5.0）。
また、minRating 値は常に maxRating 値以下にする必要があります。minRating が maxRating より大きい値として指定されている場合、INVALID_ARGUMENT エラーが返されます。