Places Aggregate API を使用してカスタムの場所スコアを作成する

目標

画像

理想的な宿泊先（休暇用のホテルや家族向けのアパートメントなど）を見つけるには、多くのオプションを比較する手間と時間がかかることがよくあります。カスタマイズされた指標を提供することで、ユーザーがホテルの観光客向けの適合性や、家族連れ向けのアパートのリスティングのランキングを簡単に把握し、面倒な作業を簡単に判断できるようにしたらどうでしょうか。

このドキュメントでは、Places Aggregate API を使用して、定義された地理的領域内の場所の密度に基づいて、動的でカスタマイズされた位置スコアを生成する方法について概説します。指定した条件に対する数値ランクであるスコアから、その場所がニーズにどの程度適しているかをすぐに把握できます。

たとえば、ある都市のホテルを宣伝していて、観光客向けのスコアを作成して、観光客に最も魅力的な地域にあるホテルをハイライト表示したいとします。Places Aggregate API を使用して、各ホテルの近くにある関連する場所のタイプの数をカウントします。たとえば、お客様は次のような場所の近くにあるホテルを重視していることがわかっています。

  • レストラン、カフェ
  • 公園と美術館
  • 衣料品店

選択したスポットタイプの数に重要度の重み付けを適用することで、各ホテルの場所の総合スコアを計算できます。このスコアは、近くの場所に基づいて、場所の全体的な適合性を反映しています。各プレイスタイプに割り当てる重み付けは、特定のユースケースとターゲット オーディエンスにとって重要な要素に合わせて調整する必要があります。このドキュメントでは、観光客に適しているスコアを主な例として使用しますが、ユーザーの属性やニーズを反映するようにスコアを作成できます。

前提条件

このドキュメントを読む前に、次のドキュメントをよく理解しておくことをおすすめします。

  • 技術的な詳細と使用可能なパラメータについては、Places Aggregate API デベロッパー ドキュメントをご覧ください。
  • [省略可] Gemini Developer API デベロッパー ドキュメント。API を使用して Gemini を呼び出す方法を説明しています。このドキュメントでは、カスタム位置情報スコアを生成するオプションとして使用しています。

デモ

このデモでは、カスタム ロケーション スコアの例を示しています。プルダウンから都市を選択し、[カスタム スコアを計算] ボタンをクリックすると、事前入力された 5 つの場所のカスタム ロケーション スコアが表示されます。

関連する場所のタイプを選択する

カスタム ロケーション スコアを作成する最初のステップは、表 A から、お客様に関連する場所の種類を決定することです。観光客におすすめのスコアを作成するにあたり、旅行者が滞在中に近くに訪れたい場所として、次の場所の種類を選択しました。

  • レストランで
  • park
  • clothing_store（衣料品店）
  • museum
  • coffee_shop

次に、これらの場所の種類ごとに重み付けを割り当て、最終的なスコアにおける相対的な重要性を反映します。重み付けは、ユースケースとユーザーの設定で最も重要な要素に基づいて決定する必要があります。この例では、重み付けスケールは 0 ～ 1 の範囲になります。

プレイスタイプ

重み付け

レストランで

0.8

park

0.6

clothing_store（衣料品店）

0.3

museum

0.2

coffee_shop

0.5

Places Aggregate API を呼び出す

関心のある場所タイプのリストが取得できたので、次のステップは Places Aggregate API を呼び出すことです。

Places Aggregate API には、位置情報フィルタが必要です。この例では、circle を使用し、中心 latLng をホテルの場所とし、radius を 500 m にします。また、評価 3.8 ～ 5 の場所を返すように ratingFilter を設定し、評価が低い場所をカウントから除外します。

特定のユースケースに合わせて、位置情報フィルタの設定を変更してテストします。たとえば、中心の緯度と経度から半径を大きくして、より広範囲の場所をキャプチャできます。または、リージョンやカスタム領域など、別の方法で検索領域を設定することもできます。

利用可能なオプションについては、Places Aggregate API のドキュメントの位置情報フィルタのセクションをご覧ください。

カスタム スコアを生成する場所タイプと場所ごとに Places Aggregate API を呼び出します。たとえば、ホテルのレストランの Place Type を呼び出します。

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

park

0.6

3

clothing_store（衣料品店）

0.3

32

museum

0.2

8

coffee_shop

0.5

41

カスタム ロケーション スコアを生成する

これで、場所の数と、場所の種類ごとに場所ごとの重み付けが得られたので、カスタム ロケーション スコアを生成できます。このセクションでは、ローカル アルゴリズムを使用する方法と Gemini Developer API を使用する方法の 2 つのオプションについて説明します。

オプション 1: アルゴリズムを使用する

最初に説明するオプションは、ローカル アルゴリズムを使用して、各プレイスタイプの重み付けとカウントを使用してスコアを生成する方法です。このスコアを 0 ～ 5 のスケールで正規化します。値が高いほど、基準に基づいて魅力的なエリアであることを示します。この例では、上記のデータから 2 つの 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 桁に丸め）です。

オプション 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 配列を出力するようリクエストします。

  • 場所の緯度と経度
  • カスタム ロケーションのスコア

上記のシステム指示と構造化出力を使用すると、1 つのロケーションに対する Gemini からのレスポンスは次のようになります。score はカスタム ロケーション スコアです。

[
  {
    "location": {
      "latitude": 51.51611,
      "longitude": -0.12726
    },
    "score": "4.13"
  }
]

スコアを表示する

上記の方法のいずれかを使用して各ロケーションのカスタム ロケーション スコアを生成したら、ホテルの詳細とともに表示したり、検索フィルタ オプションとして使用したりできます。たとえば、「観光に適しているスコアが高い場所を教えて」と話しかけます。これにより、ユーザーは予約時にデータに基づいて意思決定できるようになります。

まとめ

カスタム ロケーション スコアを使用すると、地域の適合性をユーザーに簡単に概要として示すことができます。このドキュメントでは、5 つの個別の場所タイプを使用して、さまざまな場所のカスタム ロケーション スコアを生成する方法を示しました。この実装は、ニーズに合わせて変更できます。また、類似する場所のタイプを 1 つのリクエストにまとめ、それらのタイプの集計数を返して、カスタム ロケーション スコアリング ソリューションに提供することもできます。

Places Aggregate API を今すぐお試しください。有益な位置情報スコアを生成して、ユーザーが十分な情報に基づいて位置情報に基づく意思決定を行えるようにしましょう。

寄与者

Henrik Valve | DevX エンジニア