Method: computeInsights

這個方法可讓您使用各種篩選條件 (例如區域、地點類型、營業狀態、價格等級和評分) 擷取區域相關洞察資料。目前支援「計數」和「地點」洞察資料。您可以利用「計數」洞察資料回答問題，例如「加州有多少家餐廳正在營業，價格低廉且平均評分至少 4 顆星？」 (詳情請參閱 insight 列舉項目)。您可以透過「地點」洞察，判斷哪些地點符合要求的篩選條件。接著，用戶端可以使用這些地點資源名稱，透過 Places API 擷取每個地點的更多詳細資料。

HTTP 要求

POST https://areainsights.googleapis.com/v1:computeInsights

這個網址使用 gRPC 轉碼語法。

要求主體

要求主體的資料會採用以下結構：

JSON 表示法 
{
  "insights": [
    enum (Insight)
  ],
  "filter": {
    object (Filter)
  }
}
欄位
insights[]

enum (Insight)

必要欄位。洞察運算。目前僅支援 INSIGHT_COUNT 和 INSIGHT_PLACES。
filter

object (Filter)

必要欄位。洞察篩選器。

回應主體

回應 v1.computeInsights RPC。

如果成功，回應主體會含有以下結構的資料：

JSON 表示法 
{
  "placeInsights": [
    {
      object (PlaceInsight)
    }
  ],
  "count": string
}
欄位
placeInsights[]

object (PlaceInsight)

Insights.INSIGHT_PLACES 的結果。
count

string (int64 format)

Insights.INSIGHT_COUNT 的結果。

授權範圍

需要下列 OAuth 範圍：

  • https://www.googleapis.com/auth/cloud-platform

深入分析

支援的洞察資料。

列舉
INSIGHT_UNSPECIFIED 未指定。
INSIGHT_COUNT

計數洞察。

指定這項洞察後，v1.computeInsights 會傳回符合指定篩選條件的地點數量。

要求範例：

{
  "insights": ["INSIGHT_COUNT"],
  "filter": {
    "locationFilter": {
      "region": {
        "place": "places/ChIJPV4oX_65j4ARVW8IJ6IJUYs"
      }
    },
    "typeFilter": {
      "includedTypes": ["restaurant"]
    },
    "operatingStatus": ["OPERATING_STATUS_OPERATIONAL"],
    "priceLevels": [
      "PRICE_LEVEL_FREE",
      "PRICE_LEVEL_INEXPENSIVE"
    ],
    "ratingFilter": {
      "minRating": 4.0
    }
  }
}

回應範例：

{
  "count": 1234
}
INSIGHT_PLACES

傳回地點

指定這項洞察後，v1.computeInsights 會傳回符合指定篩選條件的地點 ID。

要求範例：

{
  "insights": ["INSIGHT_PLACES"],
  "filter": {
    "locationFilter": {
      "region": {
        "place": "places/ChIJPV4oX_65j4ARVW8IJ6IJUYs"
      }
    },
    "typeFilter": {
      "includedTypes": ["restaurant"]
    },
    "operatingStatus": ["OPERATING_STATUS_OPERATIONAL"],
    "priceLevels": [
      "PRICE_LEVEL_FREE",
      "PRICE_LEVEL_INEXPENSIVE"
    ],
    "ratingFilter": {
      "minRating": 4.0
    }
  }
}

回應範例：

{
  "placeInsights": [
    {"place": "places/ABC"},
    {"place": "places/PQR"},
    {"place": "places/XYZ"}
  ]
}

篩選器

v1.computeInsights RPC 的篩選器。

JSON 表示法 
{
  "locationFilter": {
    object (LocationFilter)
  },
  "typeFilter": {
    object (TypeFilter)
  },
  "operatingStatus": [
    enum (OperatingStatus)
  ],
  "priceLevels": [
    enum (PriceLevel)
  ],
  "ratingFilter": {
    object (RatingFilter)
  }
}
欄位
locationFilter

object (LocationFilter)

必要欄位。限制結果只顯示位於地點篩選條件指定區域內的地點。
typeFilter

object (TypeFilter)

必要欄位。刊登位置類型篩選器。
operatingStatus[]

enum (OperatingStatus)

選用設定。讓結果只顯示營業狀態符合此清單中條件的地點。如果未設定 operatingStatus，系統會預設使用 OPERATING_STATUS_OPERATIONAL。
priceLevels[]

enum (PriceLevel)

選用設定。限制系統只傳回價格範圍位於此清單內的地點。如果未設定 priceLevels，結果就會包含所有價格等級。
ratingFilter

object (RatingFilter)

選用設定。限制結果只顯示平均使用者評分介於 ratingFilter 指定範圍內的地點。如果未設定 ratingFilter，結果就會包含所有評分。

LocationFilter

位置篩選器。

指定洞察資料的興趣區域。

JSON 表示法 
{

  // Union field area can be only one of the following:
  "circle": {
    object (Circle)
  },
  "region": {
    object (Region)
  },
  "customArea": {
    object (CustomArea)
  }
  // End of list of possible types for union field area.
}
欄位
聯集欄位 area。必須指定下列其中一個值。area 只能是下列其中一項：
circle

object (Circle)

以圓形表示面積。
region

object (Region)

區域為區域。
customArea

object (CustomArea)

由多邊形指定的自訂區域。

圓形

圓形是由中心點和半徑 (以公尺為單位) 定義。

JSON 表示法 
{
  "radius": integer,

  // Union field center can be only one of the following:
  "latLng": {
    object (LatLng)
  },
  "place": string
  // End of list of possible types for union field center.
}
欄位
radius

integer

選用設定。圓形的半徑 (以公尺為單位)
聯集欄位 center。圓心。center 只能是下列其中一項：
latLng

object (LatLng)

圓形中心點的經緯度。
place

string

格式：必須採用 places/PLACE_ID 格式，其中 PLACE_ID 是地點的專屬 ID。例如：places/ChIJgUbEo8cfqokR5lP9_Wh_DaM。

LatLng

代表經緯度組合的物件。以一對雙精準數表示經度度數和緯度度數。除非另有指定，否則這個物件必須符合 WGS84 標準。此外，值必須在正規化範圍內。

JSON 表示法 
{
  "latitude": number,
  "longitude": number
}
欄位
latitude

number

緯度度數，必須介於 [-90.0, +90.0] 的範圍之間。
longitude

number

經度度數，必須介於 [-180.0, +180.0] 的範圍之間。

區域

區域是指地理邊界，例如城市、郵遞區號、縣、州等。

JSON 表示法 
{

  // Union field region can be only one of the following:
  "place": string
  // End of list of possible types for union field region.
}
欄位
聯集欄位 region。定義地理區域。一次只能指定一種區域類型 (例如地點)。region 只能是下列其中一項：
place

string

特定地理區域的專屬 ID。

CustomArea

自訂區域。

JSON 表示法 
{
  "polygon": {
    object (Polygon)
  }
}
欄位
polygon

object (Polygon)

必要欄位。以多邊形表示的自訂區域

多邊形

多邊形由一系列以逆時針順序連接的座標組成。座標會形成封閉迴圈，並定義填滿區域。第一個和最後一個座標是等價的，且必須包含相同的值。這項格式是 GeoJSON 多邊形的簡化版本 (我們只支援一個逆時針外環)。

JSON 表示法 
{
  "coordinates": [
    {
      object (LatLng)
    }
  ]
}
欄位
coordinates[]

object (LatLng)

選用設定。定義多邊形的座標。

TypeFilter

地點類型篩選器。

僅支援表 1所列的地點類型。

地點只能與單一主要類型建立關聯。舉例來說，主要類型可能是「mexican_restaurant」或「steak_house」。使用 includedPrimaryTypes 和 excludedPrimaryTypes 篩選地點的主要類型結果。

地點也可能與多個類型值相關聯。舉例來說，餐廳可能有以下類型：「seafood_restaurant」、「restaurant」、「food」、「point_of_interest」、「establishment」。使用 includedTypes 和 excludedTypes 篩選與地點相關聯的類型清單結果。

如果搜尋指定多個類型限制，系統只會傳回符合所有限制的場所。舉例來說，如果您指定 {"includedTypes": ["restaurant"], "excludedPrimaryTypes": ["steak_house"]}, 系統會傳回提供「餐廳」相關服務，但主要不是以「steak_house」為主的地點。

如果有任何相衝突的類型，也就是在 includedTypes 和 excludedTypes 類型或 includedPrimaryTypes 和 excludedPrimaryTypes 中同時出現某個類型，系統會傳回 INVALID_ARGUMENT 錯誤。

必須設定 includedTypes 或 includedPrimaryTypes 其中一個。

JSON 表示法 
{
  "includedTypes": [
    string
  ],
  "excludedTypes": [
    string
  ],
  "includedPrimaryTypes": [
    string
  ],
  "excludedPrimaryTypes": [
    string
  ]
}
欄位
includedTypes[]

string

選用設定。納入的地點類型。
excludedTypes[]

string

選用設定。排除的地點類型。
includedPrimaryTypes[]

string

選用設定。已納入的主要地點類型。
excludedPrimaryTypes[]

string

選用設定。排除的主要地點類型。

OperatingStatus

地點的營業狀態。

列舉
OPERATING_STATUS_UNSPECIFIED 不指定。請勿使用這個值。
OPERATING_STATUS_OPERATIONAL 該地點正在營業，且在指定營業時間開放。
OPERATING_STATUS_PERMANENTLY_CLOSED 該地點已停止營業。
OPERATING_STATUS_TEMPORARILY_CLOSED 該地點目前暫停營業，預計日後會重新營業。

PriceLevel

地點的價格等級。

列舉
PRICE_LEVEL_UNSPECIFIED 不指定。請勿使用此值。
PRICE_LEVEL_FREE 地點提供免費服務。
PRICE_LEVEL_INEXPENSIVE 地點提供價格實惠的服務。
PRICE_LEVEL_MODERATE 商家提供價格合理的服務。
PRICE_LEVEL_EXPENSIVE 該地提供的服務價格昂貴。
PRICE_LEVEL_VERY_EXPENSIVE 地點提供的服務價格非常昂貴。

RatingFilter

平均使用者評分篩選器。

JSON 表示法 
{
  "minRating": number,
  "maxRating": number
}
欄位
minRating

number

選用設定。只顯示平均使用者評分大於或等於 minRating 的地點搜尋結果。值必須介於 1.0 到 5.0 之間。
maxRating

number

選用設定。只顯示平均使用者評分低於或等於 maxRating 的地點。值必須介於 1.0 到 5.0 之間。

PlaceInsight

儲存地點資訊

JSON 表示法 
{
  "place": string
}
欄位
place

string

地點的專屬 ID。您可以使用這個資源名稱，透過 Places API 擷取地點詳細資料。