请求参数

本文档介绍了 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 之间的数字（含 -90 和 90）。经度必须是介于 -180 和 180 之间的数字（含 -180 和 180）。
    • place：圆形中心的地点 ID。请注意，系统仅支持点状地点。此字符串必须以 places/ 前缀开头。
  • radius：圆形的半径（以米为单位）。此数字必须为正数。
区域

通过将地点 ID 传递给 place 参数，将区域定义为区域。地点 ID 表示地理区域（例如可用多边形表示的区域）。例如，佛罗里达州坦帕的地点 ID 为 places/ChIJ4dG5s4K3wogRY7SWr4kTX6c。请注意，并非所有地点 ID 都具有明确定义的几何图形，在这种情况下，Places Aggregate API 会返回 400 错误代码，并显示一条消息，指明该区域不受支持。此外，对于复杂的地理区域，内部处理优化可能会导致对代表该区域的面积进行略微过高的近似估计（最多 2-3%）。

如需确定地点 ID 是否表示不受支持的地点类型，请在 Geocoding API 请求中传递该地点 ID。响应包含 type 数组，其中列出了与该地点 ID 关联的地点类型，例如 locality、neighborhood 或 country。如果某个地点的任何类型与此列表匹配，则该地点将被拒绝进行区域过滤。

不受支持的地点类型包括：

  • establishment：通常表示某个尚未归类的地点。
  • intersection：表示主要交叉路口，通常是两条主要道路的交叉路口。
  • subpremise：表示低于 premise 级别的可寻址实体，例如公寓、单元或套房。
自定义区域

使用纬度和经度坐标定义自定义多边形的区域。

您可以访问 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 Aggregate API 支持的主要 和次要地点类型的列表，请参阅 表 A，具体请参阅 Places API （新）的 地点类型。您必须至少指定一个 includedTypes 或 includedPrimaryTypes 类型。

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

如需详细了解类型过滤条件和地点类型的工作原理，请参阅类型过滤条件。

可选参数

以下过滤条件是可选的：

  • operatingStatus：指定要包含或排除的地点状态。 默认情况下，系统会按 operatingStatus: OPERATING_STATUS_OPERATIONAL（一个特定值）进行过滤。
  • priceLevels：指定要包含的地点价格水平。默认情况下，系统不会应用任何价格水平过滤条件，并且会返回所有地点（包括没有价格水平信息的地点）。
  • ratingFilter：指定地点的评分范围。默认情况下，系统不会进行过滤（所有评分都包含在结果中）。

营业状态

借助 operatingStatus 过滤条件，您可以按 营业状态 （例如 OPERATIONAL 或 TEMPORARILY_CLOSED）进行过滤。operatingStatus 过滤条件的行为如下所示：

  • 如果未提供任何过滤条件，则结果中仅包含营业状态为 OPERATING_STATUS_OPERATIONAL 的地点。
  • 如果提供了一个或多个过滤条件，您必须指定有效的营业状态值（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 过滤条件的行为如下所示：

  • 如果未提供任何过滤条件 ：系统会返回所有地点，无论是否已分配价格水平 。这包括没有价格水平信息的地点，这些地点在按特定价格水平过滤时可能不会返回。
  • 如果提供了一个或多个过滤条件 ：系统只会返回与指定价格水平匹配的地点。

评分过滤条件

根据地点的平均用户评分过滤地点。这两个字段都是可选字段，因此如果省略，它们将默认包含没有评分的地点。

  • minRating：最低平均房客评分（介于 1.0 和 5.0 之间）。
  • maxRating：最高平均房客评分（介于 1.0 和 5.0 之间）。

此外，minRating 值必须始终小于或等于 maxRating 值。如果 minRating 指定为大于 maxRating，系统将返回 INVALID_ARGUMENT 错误。