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

Hedef

Yaklaşan tatiliniz için otel veya aile dostu bir daire gibi ideal bir yer bulmak, genellikle çok sayıda seçeneği karşılaştırma sürecinden geçer. Bu süreç can sıkıcı ve zaman alıcı olabilir. Bir otelin turistler için uygunluğunu gösteren özelleştirilmiş bir metrik sağlayarak veya apartman girişlerini ailelere uygunluk düzeylerine göre sıralayarak bu işlemi kullanıcılarınız için kolaylaştırabilir ve sıkıcı bir görevi zahmetsiz bir karara dönüştürebilirsiniz.

Bu belgede, tanımlanmış bir coğrafi alandaki 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 otellerin tanıtımını yaptığınız ve turistlere uygunluk puanı oluşturarak en ilgi çekici turistik bölgelerdeki otelleri öne çıkarmak istediğiniz bir senaryoyu düşünün. Her otelin yakınında kaç alakalı yer türünün bulunduğunu saymak için Places Aggregate API'yi kullanın. Örneğin, müşterilerinizin aşağıdakilerden bazılarının yakınındaki konumlarda bulunan 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, belirli kullanım alanınız ve hedef kitlenizin önemsediği konularla uyumlu olmalıdır. Bu dokümanda 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ılabilen parametreleri anlamak için Places Aggregate API geliştirici dokümanlarını inceleyin.
• [İsteğe bağlı] Gemini'nin API kullanarak nasıl çağrılacağını anlamak için Gemini Developer API geliştirici belgeleri. Bu belgeler, özel konum puanını oluşturmak için bu dokümanda bir seçenek olarak kullanılır.

Demo

Bu demoda, özel konum puanının kullanımda olduğu bir örnek gösterilmektedir. Açılır menüden bir şehir seçin ve önceden doldurulmuş beş konumun özel konum puanını görüntülemek için Özel Puanı Hesapla düğmesini tıklayın.

Alakalı yer türlerini seçme

Özel konum puanınızı oluşturmanın ilk adımı, A Tablosu'ndaki müşterilerinizle alakalı yer türlerine karar vermektir. Turistler için iyi puanı oluştururken, turistlerin konaklama sırasında yakınında olmak 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ınızın tercihleri için en önemli olana göre belirlenmelidir. Bu örnekte ağırlıklandırma ölçeği 0 ile 1 arasındadır ve aşağıdaki gibidir:

Places Aggregate API'yi çağırma

İlgilendiğiniz yer türlerinin listesine sahip olduğunuza göre bir 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. Merkez latLng, otelinizin konumu ve radius değeri 500 m olsun. Ayrıca ratingFilter parametresini, puanı 3,8 ile 5 arasında olan yerleri döndürecek şekilde ayarlayın.Böylece, puanı daha düşük olan yerler sayımdan hariç tutulur.

Belirli bir kullanım alanınız için 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çinde yer alan yerleri yakalamak isteyebilirsiniz. Alternatif olarak, arama alanını belirlemek için Bölge veya Özel alan gibi farklı bir yöntem de 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 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 her yer türünün sayısını ve ağırlığını biliyorsunuz. Özel konum puanını oluşturabilirsiniz. Bu bölümde, yerel bir algoritma veya Gemini Developer API kullanılarak 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ıkları ve sayıları kullanarak puan oluşturmak üzere yerel bir algoritma kullanmaktır. Bu puanı 0 ile 5 arasında bir ölçekte normalize edin. Ölçeğin yüksek değerleri, ölçütlerinize göre daha çekici 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 değerini typeWeights ile ç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 çıkışı 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 (iki ondalık basamağa yuvarlanı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ıyı ve ağırlık verilerini sağlamanız yeterlidir.

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

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

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

Gemini Developer API'yi kullanarak, yukarıdaki yer türü ve ağırlıklandırma tablosuna ek olarak her konum için şuna benzer bir açıklama verisi elde edebilirsiniz:

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

Sistem talimatları

Gemini, sağlanan veri noktalarına göre her konum için bir puan oluşturması gerektiğini bilmek amacıyla ham verilerle birlikte talimatlara ihtiyaç duyar. Bunu gerçekleştirmek 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'nin hangi verileri bekleyeceğini ve yapay zeka modelinden beklenen çıkışın ne olduğunu öğrenmesini sağlar. Ayrıca çıkışın JSON biçiminde olmasını ister.

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

Gemini'den sonucu JSON biçiminde döndürmesini istedik. Ancak koduyla sorguladığımızda neyle karşılaşacağımızı bilmemiz için çıktının yapısı hakkında daha net bilgi vermemiz gerekiyor. Bunun için Gemini API'deki responseSchema alanını kullanarak isteğe ek bir yapılandırılmış çıkış talimatı ekleyebiliriz. Bu yöntemde, model çıkışını kısıtlamak için bir OpenAPI şeması nesnesi kullanılı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'den aşağıdakileri içeren bir JavaScript dizisi oluşturması istenir:

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

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

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

Puanı görüntüleme

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, "Turistler için iyi puanı yüksek 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ğuna dair bir bakışta 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ı oluşturma gösterilmiştir. Bu uygulama, ihtiyaçlarınıza göre değiştirilebilir ve benzer yer türleri, özel konum puanlama çözümünüze sunmak için bu türlerin birleştirilmiş sayısını döndürmek üzere tek bir istek halinde birleştirilebilir.

Müşterilerinizin konuma dayalı bilinçli kararlar almasına yardımcı olmak için Places Aggregate API'yi hemen deneyin ve yararlı konum puanları oluşturun.

Katkıda bulunanlar

Henrik Valve | DevX Mühendisi