Places Aggregate özel konum puanları

Hedef

İster yaklaşan tatiliniz için bir otel ister aileye uygun bir apartman dairesi olsun, ideal konumu bulmak genellikle çok sayıda seçeneği karşılaştırmayı gerektiren, can sıkıcı ve zaman alan bir süreçtir. Bir otelin turistler için uygunluğunu gösteren özelleştirilmiş bir metrik sunarak veya apartman dairesi ilanlarını ailelere uygunluklarına göre sıralayarak kullanıcılarınızın işini kolaylaştırabilir, sıkıcı bir görevi zahmetsiz bir karara dönüştürebilirsiniz.

Bu belgede, tanımlı bir coğrafi bölgedeki yerlerin yoğunluğuna göre dinamik, özel konum puanları oluşturmak için Places Aggregate API'nin nasıl kullanılacağı açıklanmaktadır. Belirttiğiniz ölçütlere göre sayısal bir sıralama olan puan, konumun ihtiyaçlarına ne kadar uygun olduğunu anında gösterir.

Bir şehirdeki otelleri tanıttığınızı ve turistler için iyi puanı oluşturarak en cazip turistik bölgelerdeki otelleri öne çıkarmak istediğinizi varsayalım. Her otelin yakınında kaç tane alakalı yer türü olduğunu saymak için Places Aggregate API'yi kullanın. Örneğin, müşterilerinizin aşağıdaki yerlere yakın otellere değer verdiğini biliyorsunuz:

• Restoranlar ve kafeler
• Parklar ve Müzeler
• Giyim mağazaları

Seçilen bu yer türlerinin sayılarına önem ağırlıkları uygulayarak her otel konumu için genel bir puan hesaplayabilirsiniz. Puan, yakındaki yerlere göre konumun genel uygunluğunu yansıtır. Her yer türüne atanan ağırlıklar, özel kullanım alanınıza ve hedef kitleniz için önemli olan unsurlara uygun olmalıdır. Bu belgede ana örnek olarak turistler için iyi puanı kullanılacaktır ancak puanınız, kullanıcı demografinizi ve ihtiyaçlarınızı yansıtacak şekilde oluşturulabilir.

Ön koşullar

Bu dokümanı okumadan önce aşağıdaki dokümanları incelemeniz önerilir:

• Teknik ayrıntıları ve kullanılabilir parametreleri anlamak için Places Aggregate API geliştirici belgelerini inceleyin.
• [İsteğe bağlı] Gemini'ı API kullanarak nasıl çağıracağınızı anlamak için Gemini Developer API geliştirici belgeleri. Bu belgeler, özel konum puanı oluşturmak için bir seçenek olarak bu dokümanda kullanılır.

Alakalı yer türlerini seçme

Özel konum puanınızı oluşturmanın ilk adımı, Tablo A'dan müşterilerinizle alakalı yer türlerine karar vermektir. Turistler için uygun puanı oluştururken turistlerin konaklamaları sırasında yakınında bulunmak isteyecekleri aşağıdaki yer türlerini seçtik:

• restoran
• park
• clothing_store
• müze
• coffee_shop

Ardından, bu yer türlerinin her birine nihai puandaki göreceli önemini yansıtan bir ağırlık atayın. Ağırlıklar, kullanım alanınız ve kullanıcılarınızın tercihleri için en önemli olan unsurlara göre belirlenmelidir. Bu örnekte, ağırlıklandırma ölçeği 0 ile 1 arasında olacaktır:

Places Aggregate API'yi çağırma

İlgilendiğiniz yer türlerinin listesini oluşturduktan sonraki adım, Places Aggregate API'yi çağırmaktır.

Places Aggregate API için konum filtresi gerekir. Bu örnekte, otelinizin konumunu merkez (latLng) ve yarıçapı (radius) 500 m olarak belirleyerek circle kullanın. Ayrıca, ratingFilter değerini 3,8 ile 5 arasında puanı olan yerleri döndürecek şekilde ayarlayın ve daha düşük puanlı yerleri sayımlardan hariç tutun.

Kullanım alanınıza göre konum filtresinin ayarlarını değiştirerek denemeler yapın. Örneğin, yarıçap değerini artırarak merkez enlem ve boylamınızdan daha geniş bir yarıçap içindeki yerleri yakalamak isteyebilirsiniz. Alternatif olarak, arama alanını ayarlamak için Bölge veya Özel alan gibi farklı bir yöntem kullanabilirsiniz.

Kullanabileceğiniz seçenekler hakkında bilgi edinmek için Places Aggregate API belgelerinin konum filtresi bölümünü inceleyin.

Özel puan oluşturmak istediğiniz her yer türü ve konum için Places Aggregate API'yi çağırın. Örneğin, otellerinizden biri için restoran yer türünü çağırın:

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'ye yapılan tüm çağrılar tamamlandıktan sonra her konum için aşağıdaki gibi veriler elde edersiniz:

Özel konum puanını oluşturma

Artık her konum için yer sayısına ve her yer türünün ağırlığına sahip olduğunuza göre özel konum puanını oluşturabilirsiniz. Bu bölümde iki seçeneği ele alacağız: yerel bir algoritma kullanmak veya Gemini Developer API'yi kullanmak.

1. seçenek: Algoritma kullanma

Ele alacağımız ilk seçenek, her yer türünün ağırlıklarını ve sayılarını kullanarak puan oluşturmak için yerel bir algoritma kullanmaktır. Bu puanı 0 ile 5 arasında bir ölçeğe normalleştirin. Yüksek değerler, ölçütlerinize göre daha cazip bir alanı gösterir. Bu örnekte, yukarıdaki verilerden iki JavaScript nesnesi oluşturun:

    {
      "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 ile typeWeights değerini çarpıp sonuçları genel bir weightedCount değerine ekleyerek sayılardan ve ağırlıklardan bir puan oluşturun:

let weightedCount = 0;
for (const itemType in itemCounts) {
  weightedCount += itemCounts[itemType] * typeWeights[itemType];
}
weightedCount = weightedCount.toFixed(2);

Bu örnekte, bu adımın sonucu 78,3'tür.

Artık bu konumun nihai puanını 0 ile 5 arasında bir ölçekte oluşturmak için logaritmik normalleştirmeyi kullanabilirsiniz:

if (weightedCount === 0) {
   normalizedScore = 0;
} else {
   normalizedScore = Math.log(weightedCount + 1);
}

// Clamp between 0 and 5
normalizedScore = Math.max(0, Math.min(5, normalizedScore));

Bu örnekte, nihai puan çıkışı 4,36'dır (ondalık basamak sayısı ikiye yuvarlanmıştır).

2. seçenek: Gemini Developer API'yi kullanma

Yerel bir algoritma kullanmaya alternatif olarak Gemini Developer API, tüm konumlar için özel konum puanını hesaplamanın güçlü bir yolunu sunar. Tüm otel konumlarınız için sistem talimatlarıyla birlikte sayı ve ağırlık verilerini sağlamanız yeterlidir.

Bu yöntem, özellikle hesaplamaya dahil etmek istediğiniz ayrıntılı bilgileriniz varsa kullanışlıdır. Örneğin:

• Her otel konumu için metin açıklamaları (ör. "Bu konum aileler için uygundur ve bölge geceleri sessizdir").
• Kullanıcınızla ilgili bilgiler. Örneğin: "Bu kullanıcı bir aile için rezervasyon yapıyor ve merkezi bir konumda sessiz bir bölgeyi tercih ediyor".

Gemini Developer API, bu nitel verileri anlayıp hesaba katarak tamamen matematiksel bir yaklaşımın ötesinde daha gelişmiş ve alakalı bir puan elde edilmesini sağlayabilir.

Gemini Developer API'yi kullanarak yukarıdaki yer türü ve ağırlık tablosuna ek olarak her konum için aşağıdaki gibi açıklama verileri elde edebilirsiniz:

Bu nitel açıklamalar, kullanıcı bilgileri veya tercihleriyle birlikte Gemini isteminize dahil edilebilir.

Sistem talimatları

Gemini'ın, sağlanan veri noktalarına göre her konum için bir puan oluşturması gerektiğini bilmesi için ham verilerle birlikte talimatlara ihtiyacı vardır. Bunu başarmak için örnek bir sistem talimatı aşağıdaki gibi olabilir:

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

Yukarıdaki sistem talimatları, Gemini'ın hangi verileri beklemesi gerektiğini ve yapay zeka modelinden beklenen çıkışın ne olduğunu bildirir. Ayrıca çıkışı JSON biçiminde ister.

Yapılandırılmış çıkış

Gemini'dan sonucu JSON biçiminde vermesini istedik ancak kodla sorguladığımızda ne bekleyeceğimizi bilmemiz için çıktının yapısı hakkında daha spesifik olmamız gerekir. Bunun için Gemini API'deki responseSchema alanını kullanarak isteğe ek bir yapılandırılmış çıkış talimatı ekleyebiliriz. Bu, model çıkışını sınırlamak için OpenAPI şema nesnesi kullanır.

Örneğin:

{
  "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"
    ]
  }
}

Bu örnekte, Gemini'dan aşağıdaki bilgileri içeren bir JavaScript dizisi oluşturması istenmektedir:

• Konumun enlemi ve boylamı
• Özel konum puanı

Yukarıdaki sistem talimatları ve yapılandırılmış çıkış kullanıldığında Gemini'ın bir konum için yanıtı aşağıdaki gibi olur. score, özel konum puanıdır:

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

Puanı göster

Açıklanan yöntemlerden birini kullanarak her konum için özel konum puanını oluşturduktan sonra bu puan, otelinizin ayrıntılarıyla birlikte gösterilebilir veya arama filtreleme seçeneği olarak kullanılabilir. Örneğin, "Bana turistler için iyi puanı yüksek olan yerleri göster". Bu sayede müşterileriniz rezervasyon yaparken verilere dayalı kararlar verebilir.

Sonuç

Özel konum puanlarını kullanmak, kullanıcılarınıza bir bölgenin uygunluğu hakkında hızlı bir genel bakış sunmak için güçlü bir araç olabilir. Bu belgede, beş ayrı yer türü kullanılarak çeşitli konumlar için özel konum puanlarının nasıl oluşturulacağı gösterilmiştir. Bu uygulama, ihtiyaçlarınıza göre değiştirilebilir ve benzer yer türleri tek bir istekte birleştirilerek bu türlerin toplam sayısı döndürülebilir ve özel konum puanlama çözümünüze sağlanabilir.

Müşterilerinizin konuma dayalı bilinçli kararlar vermesine yardımcı olacak faydalı konum puanları oluşturmak için Places Aggregate API'yi hemen deneyin.

Katkıda bulunanlar

Henrik Valve | DevX Mühendisi