目标
寻找理想的住宿地点，无论是即将到来的假期酒店还是全家皆宜的公寓，往往需要比较众多选项，过程繁琐且耗时。如果您能提供一个自定义指标，揭示酒店对游客的适宜程度，或者根据公寓对家庭的友好程度对公寓房源进行排名，从而将繁琐的家务事变成轻松的决定，帮助用户更轻松地完成这项工作，结果会怎样？
本文档概述了如何使用 Places Aggregate API 根据指定地理区域内的地点密度生成动态、自定义的地点评分。该分数是根据您指定的条件得出的数字排名，可立即传达该位置是否符合其需求。
假设您正在推广某个城市的酒店，并希望通过创建适合游客的评分来突出显示位于最具吸引力的旅游区域的酒店。使用 Places Aggregate API 统计每家酒店附近有多少相关地点类型。例如，您知道客户看重酒店的地理位置，希望酒店附近有以下多个场所：
- 餐厅和咖啡馆
- 公园与博物馆
- 服装店
通过对这些所选地点类型的计数应用重要性权重，您可以计算每个酒店位置的总体得分。该得分反映了该地点根据附近的地点得出的整体适宜度。为每种地点类型分配的权重应与您的具体应用场景以及对目标受众群体而言重要的因素保持一致。本文档将以适合游客分数作为主要示例，但您可以根据用户受众特征和需求来构建分数。
前提条件
在阅读本文档之前，建议您先熟悉以下文档：
- Places Aggregate API 开发者文档，了解技术细节和可用参数。
- [可选] Gemini Developer 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 之间的地点，从而在计数中排除评分较低的地点。
针对您的特定用例，尝试更改位置过滤器的设置。例如，您可能希望通过增加 radius 的值来捕获中心纬度和经度更大半径范围内的地点。或者，您可能希望使用其他方法来设置搜索区域，例如区域或自定义区域。
请熟悉 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 Developer 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 工程师