目标
无论是寻找适合您即将到来的度假的酒店，还是寻找适合家庭入住的公寓，通常都需要比较大量的选项，这是一个令人沮丧且耗时的过程。如果您能提供自定义指标来显示酒店是否适合游客入住，或者根据公寓是否适合家庭入住对其进行排名，从而帮助用户更轻松地做出决定，那该多好！
本文档概述了如何使用 Places Aggregate API 根据指定地理区域内地点的密度生成动态的自定义地点评分。得分是根据您指定的条件进行的数值排名，可让用户立即了解相应地理位置与其需求的契合度。
假设您要宣传某个城市的酒店，并希望通过创建适合旅客的评分，突出显示位于最具吸引力的旅游区域的酒店。使用 Places Aggregate API 统计每个酒店附近有多少个相关的地点类型。例如，您知道客户非常看重酒店所在地理位置是否靠近以下地点：
- 餐厅和咖啡馆
- 公园和博物馆
- 服装店
通过对这些所选地点类型的计数应用重要性权重，您可以计算每个酒店位置的总得分。此得分反映了相应位置的总体适宜性，基于附近的地点而定。为每种地点类型分配的权重应与您的具体用例以及对目标受众群体而言重要的事项保持一致。本文档将以适合游客评分作为主要示例，但您可以根据自己的用户受众特征和需求构建评分。
前提条件
建议您在阅读本文档之前先熟悉以下文档：
- Places Aggregate API 开发者文档，了解技术细节和可用参数。
- [可选] Gemini 开发者 API 开发者文档，了解如何使用 API 调用 Gemini，并在此文档中用作生成自定义位置评分的一个选项。
演示
此演示展示了自定义地理位置得分功能的运作方式。从下拉菜单中选择一个城市，然后点击计算自定义得分按钮，系统会显示五个预先填充的地理位置的自定义地理位置得分。
选择相关的地点类型
若要构建自定义地理位置得分，第一步是从表格 A 中确定与您的客户相关的地点类型。由于我们要创建适合旅客评分，因此选择了旅客在住宿期间希望位于附近的以下地点类型：
- 餐馆
- 公园
- clothing_store
- 博物馆
- coffee_shop
接下来，为每种地点类型分配权重，以反映其在最终得分中的相对重要性。权重应根据您的用例和用户的偏好确定。在此示例中，权重范围介于 0 到 1 之间，如下所示：
地点类型 |
加权 |
餐馆 |
0.8 |
公园 |
0.6 |
clothing_store |
0.3 |
博物馆 |
0.2 |
coffee_shop |
0.5 |
调用 Places Aggregate API
现在，您已经有了感兴趣的地点类型列表，接下来要调用 Places Aggregate API。
Places Aggregate API 需要地理位置过滤条件。在本示例中，请使用 circle，其中中心 latLng 为酒店的位置，radius 为 500 米。此外，还将 ratingFilter 设置为返回评分介于 3.8 到 5 之间的地点，从统计数据中排除评分较低的地点。
您可以根据自己的具体用例，尝试更改位置信息过滤条件的设置。例如，您可能希望通过增加半径值，从中心纬度和经度捕获半径更大的地点。或者，您也可以使用其他方法设置搜索区域，例如区域或自定义区域。
熟悉 Places Aggregate API 文档中的“地点过滤条件”部分，了解可供您使用的选项。
针对您要为其生成自定义评分的每种地点类型和地理位置调用 Places Aggregate API。例如，调用某家酒店的餐厅地点类型：
curl --location 'https://areainsights.googleapis.com/v1:computeInsights' \
--header 'X-Goog-Api-Key: API_KEY \
--header 'Content-Type: application/json' \
--data '{
"insights": [
"INSIGHT_COUNT"
],
"filter": {
"locationFilter": {
"circle": {
"latLng": {
"latitude": 51.51611,
"longitude": -0.12726
},
"radius": 500
}
},
"typeFilter": {
"includedTypes": [
"restaurant"
]
},
"ratingFilter": {
"minRating": 3.8,
"maxRating": 5
}
}
}'
完成对 API 的所有调用后，您将获得每个营业地点的如下数据：
地点类型 |
加权 |
计数 |
餐馆 |
0.8 |
56 |
公园 |
0.6 |
3 |
clothing_store |
0.3 |
32 |
博物馆 |
0.2 |
8 |
coffee_shop |
0.5 |
41 |
生成自定义地理位置得分
现在，您已经有了每个地点的每个地点类型的地点数量和权重，接下来可以生成自定义地点得分了。在本部分中，我们将讨论两种方法：使用本地算法或使用 Gemini 开发者 API。
方法 1：使用算法
我们将介绍的第一个选项是使用本地算法，根据每个地点类型的权重和计数生成得分。将此得分标准化为 0 到 5 的范围，其中值越高表示相应区域的吸引力越大（根据您的条件）。在本例中，请根据上述数据生成两个 JavaScript 对象：
itemCounts |
typeWeights |
{ "restaurant": 56, "park": 3, "clothing_store": 32, "museum": 8, "coffee_shop": 41 } |
{ "restaurant": 0.8, "park": 0.6, "clothing_store": 0.3, "museum": 0.2, "coffee_shop": 0.5 } |
通过将 itemCounts 乘以 typeWeights，并将结果添加到总体 weightedCount，从计数和权重生成得分：
let weightedCount = 0;
for (const itemType in itemCounts) {
weightedCount += itemCounts[itemType] * typeWeights[itemType];
}
weightedCount = weightedCount.toFixed(2);
在此示例中，此步骤的输出为：78.3。
现在，您可以使用对数归一化方法为此地理位置生成 0 到 5 之间的最终得分：
if (weightedCount === 0) {
normalizedScore = 0;
} else {
normalizedScore = Math.log(weightedCount + 1);
}
// Clamp between 0 and 5
normalizedScore = Math.max(0, Math.min(5, normalizedScore));
对于此示例，最终得分输出为：4.36（四舍五入取小数点后两位）。
方案 2：使用 Gemini Developer API
Gemini Developer API 是一种强大的替代方案，可用于计算所有地理位置的自定义地理位置得分。只需为所有酒店位置提供计数和权重数据以及系统说明即可。
如果您有想要纳入计算中的细致信息，例如：
- 每个酒店位置的文本说明，例如：“此位置适合家庭入住，夜间环境安静”。
- 与用户相关的信息，例如：“此用户是为家人预订，偏好位于市中心的闹中取静的区域”。
Gemini Developer API 可以理解并纳入这些定性数据，从而得出比纯粹数学方法更精细、更相关的分数。
除了上述地点类型和权重表之外，使用 Gemini Developer API 还可以为每个地点提供如下说明数据：
位置 |
说明 |
位于市中心，靠近博物馆，夜晚安静，适合家庭入住。 |
|
地理位置优越，靠近酒吧和餐厅。晚上很吵闹，人很多，适合团体入住。 |
|
远离市中心的住宅区。 |
|
位于市中心，靠近河流，夜晚安静，适合家庭入住。 |
|
远离市中心的住宅区。 |
您可以在向 Gemini 提问时添加这些定性说明以及任何用户信息或偏好设置。
系统指令
Gemini 需要同时提供说明和原始数据，才能知道它需要根据提供的数据点为每个地理位置生成得分。实现此目的的系统说明示例如下：
You will be given a json file containing details about a number of locations grouped by their latitude and longitudes. Within the location details is information about the count of places nearby the location that match a specific category, and the weighting of importance of that category, between 0 - 1. You will also be given information about the user's preference, and a description of each location. Take this into consideration when generating scores. Generate a location suitability score taking these into account for each location. The score should be between 1 - 5 inclusive, to two decimal places. The minimum score a location can receive is 1. Output in JSON
上述系统说明可让 Gemini 知道预期的数据以及 AI 模型的预期输出。它还会以 JSON 格式请求输出。
结构化输出
虽然我们已要求 Gemini 以 JSON 格式输出结果，但我们需要更具体地说明输出的结构，以便知道使用代码查询时会出现什么结果。为此，我们可以使用 Gemini API 中的 responseSchema 字段，向请求添加额外的结构化输出说明。这使用 OpenAPI 架构对象来约束模型输出。
例如：
{
"type": "array",
"description": "Array of location data with score",
"items": {
"type": "object",
"properties": {
"location": {
"type": "object",
"description": "Geographical coordinates of the location",
"properties": {
"latitude": {
"type": "number",
"format": "float",
"description": "Latitude of the location"
},
"longitude": {
"type": "number",
"format": "float",
"description": "Longitude of the location"
}
},
"required": [
"latitude",
"longitude"
]
},
"score": {
"type": "string",
"description": "A score associated with the location"
}
},
"required": [
"location",
"score"
]
}
}
以下示例请求 Gemini 输出一个 JavaScript 数组，其中包含以下内容：
- 营业地点的纬度和经度
- 自定义位置得分
使用上述系统说明和结构化输出，Gemini 针对某个地理位置的回答将如下所示，其中 score 是自定义地理位置得分：
[
{
"location": {
"latitude": 51.51611,
"longitude": -0.12726
},
"score": "4.13"
}
]
显示得分
使用上述方法之一为每个地理位置生成自定义地理位置得分后，您可以将其与酒店详情一起显示，也可以将其用作搜索过滤选项。例如，“向我显示适合游客评分较高的地点”。这样，客户在预订时就能根据数据做出决策。
总结
自定义地点评分是一款强大的工具，可让用户一目了然地了解某个区域的适宜程度。本文档演示了如何使用五种不同的地点类型为各种地点生成自定义地点评分。您可以根据需要修改此实现，并将类似的地点类型合并到一个请求中，以返回这些类型的汇总计数，以提供给您的自定义地点评分解决方案。
立即试用 Places Aggregate API，生成富有洞见的位置评分，帮助您的客户做出明智的基于位置的决策！
贡献者
Henrik Valve | DevX 工程师