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

目標

画像

理想的な場所を見つけるには、次の休暇に利用するホテルや家族向けのマンションなど、多くの選択肢を比較する面倒で時間のかかるプロセスが必要になることがよくあります。観光客に適したホテルを特定するカスタム指標を提供したり、家族連れに優しいアパートのリスティングをランク付けしたりすることで、ユーザーが簡単に決断できるようにサポートできるとしたらどうでしょうか。面倒な作業が、簡単に決められるようになります。

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

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

  • レストラン、コーヒー ショップ
  • 公園と博物館
  • 衣料品店

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

前提条件

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

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

デモ

このデモでは、カスタムの場所スコアの例を示します。プルダウンから都市を選択し、[Calculate Custom Score] ボタンをクリックすると、事前入力された 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 には地域フィルタが必要です。この例では、中心の latLng がホテルの位置で、radius が 500 m の circle を使用します。また、ratingFilter を設定して、評価が 3.8 ～ 5 の場所を返し、評価の低い場所をカウントから除外します。

特定のユースケースに合わせて、位置情報フィルタの設定を調整してみてください。たとえば、半径の値を大きくすると、中心の緯度と経度からより広い範囲の場所をキャプチャできます。別の方法（地域やカスタム エリアなど）で検索エリアを設定することもできます。

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

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

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: アルゴリズムを使用する

最初に説明するのは、ローカル アルゴリズムを使用して、各 Place Type の重み付けとカウントを使用してスコアを生成する方法です。このスコアを 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 デベロッパー 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 を今すぐお試しください。位置情報に関する有益なスコアを生成し、お客様が位置情報に基づいて十分な情報に基づいた意思決定を行えるようサポートします。

寄稿者

DevX エンジニア | Henrik Valve