目標
無論是尋找度假飯店或適合全家入住的公寓，往往需要花費大量時間比較眾多選項，過程令人沮喪。如果能提供自訂指標，顯示飯店是否適合觀光客，或根據家庭友善程度為公寓房源排名，就能讓使用者輕鬆做出決定，不必再費心比較。
本文說明如何使用 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 之間的地點，並排除評分較低的地點。
請嘗試變更位置篩選器的設定，找出最適合您特定用途的設定。舉例來說，您可以增加半徑值，擷取中心經緯度較大半徑範圍內的地點。或者，您也可以使用其他方法設定搜尋區域，例如「Region」(區域) 或「Custom area」(自訂區域)。
請參閱 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 | 開發人員體驗工程師