使用 Places Aggregate API 建立自訂位置分數

目標

圖片

無論是尋找下次度假的飯店,還是適合親子同遊的公寓,尋找理想地點往往需要比較多個選項,過程既耗時又令人沮喪。您可以提供自訂指標,讓使用者輕鬆瞭解飯店是否適合觀光客人,或是根據公寓是否適合親子同住來排序,讓使用者輕鬆做出決定,不再需要花時間比較。

本文件概略說明如何使用Places Aggregate API,根據指定地理區域內的 Place 密度產生動態自訂位置分數。分數是根據您指定的條件計算出的數值排名,可立即傳達位置是否符合使用者需求。

舉例來說,假設你要宣傳某個城市的飯店,並且想透過建立適合觀光客的評分,突顯最受觀光客歡迎的飯店。使用 Places Aggregate API 計算每間飯店附近有多少相關的地點類型。舉例來說,假設您知道客戶重視飯店所在地點是否鄰近下列地點:

  • 餐廳和咖啡廳
  • 公園和博物館
  • 服飾店

您可以為這些所選地點類型的計數值套用重要性權重,計算每個飯店位置的總分數。分數會根據附近地點,反映位置的整體適合度。為每個地點類型指派的重量應與您的特定用途和目標對象重視的內容一致。本文將以「適合觀光客」分數做為主要範例,但您可以根據使用者客層和需求建立分數。

必要條件

建議您在閱讀本文之前,先熟悉下列說明文件:

  • 請參閱 Places Aggregate API 開發人員說明文件,瞭解技術細節和可用的參數。
  • [選用] Gemini Developer API 開發人員說明文件,可瞭解如何使用 API 呼叫 Gemini,並在本文件中用於產生自訂位置分數。

示範

這個示範會顯示自訂位置分數的實際運作情形。從下拉式選單中選擇城市,然後按一下「Calculate Custom Score」按鈕,即可顯示五個預先填入位置的自訂位置分數。

選取相關地點類型

建立自訂位置分數的第一步,就是從表格 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 工程師