Özel konum puanı oluşturmak için Places Aggregate API'yi kullanma

Hedef

İster yaklaşan tatiliniz için bir otel ister aile dostu bir daire olsun, ideal yeri bulmak genellikle çok sayıda seçeneği karşılaştırmayı içeren sinir bozucu ve zaman alıcı bir süreçtir. Turistlere uygunluğunu gösteren özelleştirilmiş bir metrik sağlayarak veya apartman listelerini aile dostu olma durumlarına göre sıralayarak kullanıcılarınızın bu süreci kolaylaştırmasına yardımcı olsaydınız ne olurdu? Böylece, sıkıcı bir görev zahmetsiz bir karara dönüşürdü.

Bu belgede, tanımlanmış bir coğrafi alandaki yerlerin yoğunluğuna göre dinamik ve ö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 bildirir.

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

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

Bu seçili 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, belirli kullanım alanınızla ve hedef kitleniz için önemli olan şeylerle uyumlu olmalıdır. Bu belgede ana örnek olarak turistler için uygun puanı kullanılacak ancak puanınız, kullanıcı demografinizi ve ihtiyaçlarınızı yansıtacak şekilde oluşturulabilir.

Ön koşullar

Bu belgeyi okumadan önce aşağıdaki belgeler hakkında bilgi sahibi olmanız önerilir:

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

Demo

Bu demoda, özel konum puanının nasıl kullanıldığına dair bir örnek gösterilmektedir. Açılır listeden bir şehir seçin ve beş önceden doldurulmuş konum için özel konum puanını görüntülemek üzere Özel Puanı Hesapla düğmesini tıklayın.

Alakalı yer türlerini seçin

Ö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şturduğumuzdan, turistlerin konaklamaları sırasında yakınında bulunmak isteyeceği 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 faktörlere 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 örnek için circle kullanın. latLng, otelinizin konumu ve radius 500 m olmalıdır. Ayrıca, daha düşük puanlı yerleri sayımlardan hariç tutarak ratingFilter değerini 3,8 ile 5 arasında puan alan yerleri döndürecek şekilde ayarlayın.

Belirli kullanım alanınız için konum filtresinin ayarlarını değiştirmeyi deneyin. Ö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 dokümanlarının konum filtresi bölümünü inceleyin.

Özel puan oluşturmak istediğiniz her yer türü ve konumu için Places Aggregate API'yi çağırın. Örneğin, otellerinizden birinin yer türü için restoran çağrısı yapı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 verileriniz olur:

Özel konum puanını oluşturma

Artık her konum için yer sayısına ve her yer türü için ağırlıklandırmaya sahip olduğunuzdan özel konum puanını oluşturabilirsiniz. Bu bölümde, yerel bir algoritma kullanma veya Gemini Developer API'yi kullanma olmak üzere iki seçenekten bahsedeceğiz.

1. seçenek: Algoritma kullanma

Ele alacağımız ilk seçenek, her yer türü için ağırlıklandırmaları ve sayıları kullanarak bir puan oluşturmak üzere yerel bir algoritma kullanmaktır. Bu puanı 0 ile 5 arasında bir ölçekte normalleştirin. Daha yüksek değerler, ölçütlerinize göre daha çekici bir alanı gösterir. Bu örnek için 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 çarparak ve 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 konum için 0 ile 5 arasında bir ölçekte nihai puan oluşturmak üzere logaritmik normalleştirme 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 (iki ondalık basamağa yuvarlanmıştır).

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

Gemini Developer API, yerel algoritma kullanmaya alternatif olarak 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 yalnızca sayı ve ağırlıklandırma verilerini girmeniz yeterlidir.

Bu yöntem, özellikle hesaplamaya dahil etmek istediğiniz ayrıntılı bilgiler varsa (ör. aşağıdaki gibi) yararlıdır:

• Her otel konumu için metin açıklamaları (ör. "Bu konum aileler için uygundur ve gece bölgede sessizlik hakimdir").
• Kullanıcınızla ilgili bilgiler (ör. "Bu kullanıcı ailesi için rezervasyon yapıyor ve merkezi bir konumda sessiz bir alan tercih ediyor").

Gemini Developer API, bu niteliksel verileri anlayıp hesaba katarak tamamen matematiksel bir yaklaşımdan daha karmaşık ve alakalı bir puan elde etmenizi sağlar.

Yukarıdaki yer türü ve ağırlıklandırma tablosuna ek olarak Gemini Developer API'yi kullanarak her konum için aşağıdaki gibi görünen açıklama verileri elde edebilirsiniz:

Bu niteliksel açıklamalar, kullanıcı bilgileri veya tercihleriyle birlikte Gemini'a gönderdiğiniz isteme dahil edilebilir.

Sistem talimatları

Gemini'ın, sağlanan veri noktalarına göre her konum için puan oluşturması gerektiğini bilmesi için ham verilerle birlikte talimatlar gerekir. Bunu sağlamak için örnek bir sistem talimatı şu şekilde 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'a hangi verilerin beklendiğini ve yapay zeka modelinden beklenen çıkışın ne olduğunu bildirir. Ayrıca çıkışın JSON biçiminde olmasını ister.

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

Gemini'dan sonucu JSON biçiminde vermesini istesek de çıktının yapısı hakkında daha ayrıntılı bilgi vermemiz gerekiyor. Böylece, kodu sorguladığımızda ne bekleyeceğimizi bilebiliriz. Bunun için Gemini API'deki responseSchema alanını kullanarak isteğe ek bir structured output talimatı ekleyebiliriz. Bu, model çıkışını kısıtlamak 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ğıdakileri içeren bir JavaScript dizisi oluşturması isteniyor:

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

Yukarıdaki sistem talimatlarını ve yapılandırılmış çıkışı kullanarak, bir konum için Gemini'ın yanıtı şu şekilde olur. score, özel konum puanıdır:

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

Puanı gösterme

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, "show me places with a high good for tourists score" ("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ı, kullanıcılarınıza bir alanın uygunluğuyla ilgili genel bir 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ı oluşturma gösterilmiştir. Bu uygulama, ihtiyaçlarınıza uyacak şekilde değiştirilebilir ve benzer yer türleri, özel konum puanlama çözümünüze sağlamak üzere bu türlerin toplu sayısını döndürmek için tek bir istekte birleştirilebilir.

Müşterilerinizin konum tabanlı bilinçli kararlar vermesine yardımcı olmak için Places Aggregate API'yi bugün deneyerek konumla ilgili analizler içeren puanlar oluşturun.

Katkıda bulunanlar

Henrik Valve | DevX Engineer