请求参数

本文档介绍了 Places Insights API 的请求参数,并包含有关使用此服务的数据分析和最佳实践。

借助 Places Insights API,您可以执行以下几项关键功能:

  • 统计地点数量:确定与特定条件(例如地点类型、营业状态、价格水平和评分)匹配的地点数量。
  • 检索地点详情:获取符合指定过滤条件的地点的名称,然后使用 Places API 提取更详细的信息。
  • 灵活过滤:应用全面的过滤条件,获取精准的数据分析。 可用的过滤条件包括:
    • 地理区域(圆形、区域或自定义多边形)
    • 地点类型
    • 营业状态
    • 价位
    • 分级范围

必需参数

本部分介绍了向 Places Insights API 发出请求时所需的参数。每个请求都必须提供以下信息:

  • 一种数据分析。
  • 位置过滤条件和类型过滤条件。

数据分析类型

指定您要计算的数据分析的类型。支持以下数据分析类型:

  • INSIGHT_COUNT:返回与过滤条件匹配的地点数量。
  • INSIGHT_PLACES:返回与过滤条件匹配的地点 ID

    注意:如果您选择 INSIGHT_PLACES,则只有当 count 不超过 100 时,Places Insights API 才会返回地点 ID。

过滤条件

指定过滤地点的条件。您至少必须指定 LocationFilterTypeFilter

位置过滤条件

地理位置过滤条件可以是以下类型之一:

  • circle:将区域定义为具有中心和半径的圆形。
  • region:将区域定义为地区。
  • customArea:将区域定义为自定义多边形。
圆形

如果您选择地理区域为圆形,则需要提供 centerradius。中心可以是纬度和经度,也可以是圆心所在地点的 ID。

  • center
    • latLng:圆形中心的纬度和经度。纬度必须介于 -90 到 90 之间(包括这两个数值)。经度必须介于 -180 到 180(包括这两个数值)之间。
    • place:圆心所在的地点 ID。请注意,仅支持地点。此字符串必须以 places/ 前缀开头。
  • radius:圆的半径(以米为单位)。此数字必须为正数。
区域

将地点 ID 传递给 place 参数,将您的区域定义为一个地区。地点 ID 表示地理区域(例如可由多边形表示的区域)。例如,佛罗里达州坦帕的地点 ID 为 places/ChIJ4dG5s4K3wogRY7SWr4kTX6c。请注意,并非所有地点 ID 都有明确定义的几何图形,在这种情况下,Places Insights API 会返回 404 错误代码。

下表列出了不受支持的区域类型。如需确定地点 ID 是否表示不受支持的区域类型,请在 Geocoding API 请求中传递地点 ID。响应包含 type 数组,其中列出了与地点 ID 关联的区域,例如 cityneighborhoodcountry

不支持的地区类型
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。您必须至少指定一个 includedTypesincludedPrimaryTypes 类型。

  • includedTypes:包含的地点类型的列表。
  • excludedTypes:排除的地点类型列表。
  • includedPrimaryTypes:包含的主要地点类型的列表。
  • excludedPrimaryTypes:排除的主要地点类型的列表。

如需详细了解类型过滤条件和地点类型的运作方式,请参阅详细了解类型过滤条件

可选参数

以下过滤条件为可选项:

  • operatingStatus:指定要包含或排除的地点的状态。默认按 operatingStatus: OPERATING_STATUS_OPERATIONAL(一个特定值)过滤。
  • priceLevels:指定地点的价格水平。默认为不进行过滤(结果中包含所有价格级别)。
  • ratingFilter:指定地点的评分范围。默认为不进行过滤(结果中包含所有分级)。

营业状态

根据营业状态(例如正常营业或暂停营业)进行过滤。

价格水平

根据价格水平(例如免费、适中或昂贵)进行过滤。

“评分”过滤器

根据用户平均评分过滤地点。这两个字段都是可选字段,因此如果省略这两个字段,系统会默认将未评分的酒店也包含在内。

  • minRating:最低用户平均评分(介于 1.0 到 5.0 之间)。
  • maxRating:最高平均用户评分(介于 1.0 到 5.0 之间)。