リクエスト パラメータ

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

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

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

必須パラメータ

このセクションでは、Places Insights API にリクエストを送信する際に必要なパラメータについて説明します。各リクエストで、次のプロパティを指定する必要があります。

  • 分析情報の種類。
  • ロケーション フィルタとタイプ フィルタ。

分析情報の種類

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

  • INSIGHT_COUNT: フィルタ条件に一致する場所の数を返します。

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

    注: INSIGHT_PLACES を選択した場合、Places Insights API は、count が 100 以下の場合のみプレイス ID を返します。

フィルタ

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

ロケーション フィルタ

位置情報フィルタには、次のいずれかのタイプを使用できます。

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

地理的なエリアを円として選択する場合は、center と radius を指定する必要があります。中心は、緯度と経度、または円の中心の場所 ID のいずれかです。

  • center:
    • latLng: 円の中心の緯度と経度。緯度は -90 ～ 90 の数値で指定する必要があります。経度は -180 ～ 180 の数値で指定する必要があります。
    • place: 円の中心のプレイス ID。なお、サポートされているのはポイント プレイスのみです。この文字列は places/ 接頭辞で始まる必要があります。
  • radius: 円の半径（メートル単位）。この数値は正の数値でなければなりません。
地域

プレイス ID を place パラメータに渡して、対象地域をリージョンとして定義します。プレイス ID は、地理的なエリア（ポリゴンで表されるエリアなど）を表します。たとえば、フロリダ州タンパの場所 ID は places/ChIJ4dG5s4K3wogRY7SWr4kTX6c です。すべての place ID に明確なジオメトリが設定されているわけではありません。そのような場合は、Places Insights API から 404 エラーコードが返されます。

次の表に、サポートされていないリージョン タイプを示します。プレイス ID がサポートされていない地域タイプを表しているかどうかを確認するには、Geocoding API リクエストでプレイス ID を渡します。レスポンスには、プレイス ID に関連付けられている地域（city、neighborhood、country など）を一覧表示する type 配列が含まれます。

サポートされていないリージョン タイプ
establishment place_of_worship
floor post_box
food postal_code_suffix
general_contractor room
geocode street_address
health street_number
intersection sublocality_level_5
landmark 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 Insights API でサポートされているプライマリとセカンダリの両方の場所タイプの一覧については、Places API（新規）の場所タイプの表 A をご覧ください。includedTypes 型または includedPrimaryTypes 型を少なくとも 1 つ指定する必要があります。

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

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

オプション パラメータ

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

  • operatingStatus: 含める場所または除外する場所のステータスを指定します。デフォルトは operatingStatus: OPERATING_STATUS_OPERATIONAL（1 つの特定の値）によるフィルタリングです。
  • priceLevels: 場所の料金レベルを指定します。デフォルトではフィルタなし（すべての価格帯が結果に含まれます）。
  • ratingFilter: 場所の評価範囲を指定します。デフォルトではフィルタなし（すべての評価が結果に含まれます）。

営業状況

営業状況（営業中、臨時休業など）に基づいてフィルタします。

価格帯

[料金レベル]（無料、中程度、高額など）に基づいてフィルタします。

評価フィルタ

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

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