使用 Places Aggregate API 创建自定义地理位置评分

目标

图片

无论是为即将到来的假期寻找理想的酒店,还是寻找适合家庭入住的公寓,通常都需要比较众多选项,这往往令人沮丧且耗时。如果您能提供自定义指标,帮助用户更轻松地做出决定,例如显示酒店是否适合游客,或根据公寓房源的家庭友好度对房源进行排名,将繁琐的任务变成轻松的决策,那会怎么样?

本文档概述了如何使用 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 之间的地点,并从计数中排除评分较低的地点。

您可以根据自己的具体使用情形,尝试调整位置信息过滤器的设置。例如,您可能希望通过增加半径值来捕获中心纬度和经度周围更大半径范围内的地点。或者,您可能需要使用其他方法来设置搜索区域,例如区域自定义区域

请参阅 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 获取每个地点的说明数据,如下所示:

位置

说明

51.49884, -0.17978

位置居中,靠近博物馆,夜间安静,适合家庭入住。

51.51750, -0.13065

位置居中,靠近酒吧和餐厅。夜间喧闹繁忙,适合聚会。

51.45712、0.01146

住宅区,远离市中心。

51.51271, -0.09933

位置居中,靠近河流。夜间安静,适合家庭入住。

51.58502, -0.06445

住宅区,远离市中心。

这些定性描述以及任何用户信息或偏好设置都可以包含在您向 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 工程师