使用 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 開發人員 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 開發人員 API 也提供強大的方式,可計算所有地點的自訂位置分數。只要提供所有飯店地點的數量和權重資料,以及系統操作說明即可。

如果您想在計算中加入詳細資訊 (例如:

  • 每個飯店位置的文字說明,例如:「這個位置適合家庭入住,晚上很安靜」。
  • 使用者的相關資訊,例如:「這位使用者為家人預訂,希望入住市中心安靜的區域」。

Gemini 開發人員 API 可以理解並考量這項質性資料,進而提供比純粹數學方法更精確且相關的分數。

使用 Gemini 開發人員 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 工程師