本文档介绍了 Places Insights API 的请求参数,并包含有关使用此服务的数据分析和最佳实践。
借助 Places Insights API,您可以执行以下几项关键功能:
- 统计地点数量:确定与特定条件(例如地点类型、营业状态、价格水平和评分)匹配的地点数量。
- 检索地点详情:获取符合指定过滤条件的地点的名称,然后使用 Places API 提取更详细的信息。
- 灵活过滤:应用全面的过滤条件,获取精准的数据分析。
可用的过滤条件包括:
- 地理区域(圆形、区域或自定义多边形)
- 地点类型
- 营业状态
- 价位
- 分级范围
必需参数
本部分介绍了向 Places Insights API 发出请求时所需的参数。每个请求都必须提供以下信息:
- 一种数据分析。
- 位置过滤条件和类型过滤条件。
数据分析类型
指定您要计算的数据分析的类型。支持以下数据分析类型:
INSIGHT_COUNT
:返回与过滤条件匹配的地点数量。INSIGHT_PLACES
:返回与过滤条件匹配的地点 ID。注意:如果您选择
INSIGHT_PLACES
,则只有当count
不超过 100 时,Places Insights API 才会返回地点 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
。请注意,并非所有地点 ID 都有明确定义的几何图形,在这种情况下,Places Insights API 会返回 404 错误代码。
下表列出了不受支持的区域类型。如需确定地点 ID 是否表示不受支持的区域类型,请在 Geocoding API 请求中传递地点 ID。响应包含 type
数组,其中列出了与地点 ID 关联的区域,例如 city
、neighborhood
或 country
。
不支持的地区类型 | |
---|---|
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
类型。
includedTypes
:包含的地点类型的列表。excludedTypes
:排除的地点类型列表。includedPrimaryTypes
:包含的主要地点类型的列表。excludedPrimaryTypes
:排除的主要地点类型的列表。
如需详细了解类型过滤条件和地点类型的运作方式,请参阅详细了解类型过滤条件。
可选参数
以下过滤条件为可选项:
operatingStatus
:指定要包含或排除的地点的状态。默认按operatingStatus: OPERATING_STATUS_OPERATIONAL
(一个特定值)过滤。priceLevels
:指定地点的价格水平。默认为不进行过滤(结果中包含所有价格级别)。ratingFilter
:指定地点的评分范围。默认为不进行过滤(结果中包含所有分级)。
营业状态
根据营业状态(例如正常营业或暂停营业)进行过滤。
价格水平
根据价格水平(例如免费、适中或昂贵)进行过滤。
“评分”过滤器
根据用户平均评分过滤地点。这两个字段都是可选字段,因此如果省略这两个字段,系统会默认将未评分的酒店也包含在内。
minRating
:最低用户平均评分(介于 1.0 到 5.0 之间)。maxRating
:最高平均用户评分(介于 1.0 到 5.0 之间)。