जगह का कस्टम स्कोर बनाने के लिए, Places Aggregate API का इस्तेमाल करना

मकसद

छुट्टियों के लिए होटल या परिवार के साथ रहने के लिए अपार्टमेंट जैसी सही जगह ढूंढना, अक्सर एक मुश्किल और समय लेने वाली प्रक्रिया होती है. इसमें कई विकल्पों की तुलना करनी पड़ती है. अगर आपको अपने उपयोगकर्ताओं के लिए इस काम को आसान बनाना है, तो क्या आपको उनकी ज़रूरत के हिसाब से तैयार की गई मेट्रिक उपलब्ध करानी चाहिए? इस मेट्रिक से यह पता चलेगा कि कोई होटल पर्यटकों के लिए सही है या नहीं. इसके अलावा, अपार्टमेंट की लिस्टिंग को परिवार के हिसाब से रैंक किया जा सकता है. इससे, मुश्किल काम को आसानी से पूरा किया जा सकेगा.

इस दस्तावेज़ में, Places Aggregate API का इस्तेमाल करके, डाइनैमिक और कस्टम लोकेशन स्कोर जनरेट करने का तरीका बताया गया है. ये स्कोर, किसी तय भौगोलिक क्षेत्र में मौजूद जगहों की डेंसिटी के आधार पर जनरेट किए जाते हैं. स्कोर, आपकी तय की गई शर्तों के हिसाब से संख्यात्मक रैंकिंग होती है. इससे खरीदारों को तुरंत पता चल जाएगा कि यह जगह उनकी ज़रूरतों के हिसाब से कितनी सही है.

मान लें कि आपको किसी शहर में होटल का प्रमोशन करना है. साथ ही, आपको उन होटलों को हाइलाइट करना है जो पर्यटकों के लिए सबसे अच्छी जगहों पर मौजूद हैं. इसके लिए, आपको पर्यटकों के लिए अच्छी जगह का स्कोर बनाना होगा. Places Aggregate API का इस्तेमाल करके, यह पता लगाएं कि हर होटल के आस-पास कितने काम के जगह के टाइप मौजूद हैं. उदाहरण के लिए, आपको पता है कि आपके ग्राहक उन होटलों को पसंद करते हैं जो इन जगहों के आस-पास मौजूद हैं:

• रेस्टोरेंट और कॉफ़ी शॉप
• पार्क और म्यूज़ियम
• कपड़े की दुकान

चुनी गई जगहों के टाइप की संख्या के हिसाब से, उन्हें अहमियत के आधार पर वेटेज देकर, हर होटल की जगह के लिए कुल स्कोर का हिसाब लगाया जा सकता है. स्कोर से पता चलता है कि आस-पास की जगहों के आधार पर, कोई जगह कितनी अच्छी है. जगह के हर टाइप को असाइन किए गए वेटेज, आपके इस्तेमाल के खास उदाहरण और आपकी टारगेट ऑडियंस के लिए ज़रूरी बातों के मुताबिक होने चाहिए. इस दस्तावेज़ में, पर्यटकों के लिए अच्छी जगह स्कोर को मुख्य उदाहरण के तौर पर इस्तेमाल किया जाएगा. हालांकि, आपके स्कोर को आपके उपयोगकर्ता के डेमोग्राफ़िक और ज़रूरतों के हिसाब से बनाया जा सकता है.

ज़रूरी शर्तें

इस दस्तावेज़ को पढ़ने से पहले, हमारा सुझाव है कि आप इन दस्तावेज़ों को पढ़ लें:

• तकनीकी जानकारी और उपलब्ध पैरामीटर समझने के लिए, Places Aggregate API डेवलपर के लिए उपलब्ध दस्तावेज़ देखें.
• [ज़रूरी नहीं] Gemini Developer API डेवलपर दस्तावेज़. इससे यह समझने में मदद मिलती है कि एपीआई का इस्तेमाल करके Gemini को कैसे कॉल किया जाता है. साथ ही, इस दस्तावेज़ में इसका इस्तेमाल, कस्टम लोकेशन स्कोर जनरेट करने के विकल्प के तौर पर किया गया है.

डेमो

इस डेमो में, कस्टम लोकेशन स्कोर का एक उदाहरण दिखाया गया है. ड्रॉप-डाउन से कोई शहर चुनें. इसके बाद, कस्टम स्कोर का हिसाब लगाएं बटन पर क्लिक करें. इससे, पहले से भरी गई पांच जगहों के लिए कस्टम लोकेशन स्कोर दिखेगा.

काम की जगह के टाइप चुनें

कस्टम लोकेशन स्कोर बनाने के लिए, सबसे पहले यह तय करें कि टेबल A में दिए गए किस तरह के प्लेस टाइप, आपके ग्राहकों के लिए काम के हैं. हम पर्यटकों के लिए अच्छी जगह स्कोर बना रहे हैं. इसलिए, हमने जगह के इन टाइप को चुना है. पर्यटक, होटल में ठहरने के दौरान इन जगहों के आस-पास रहना चाहेंगे:

• रेस्टोरेंट
• पार्क
• clothing_store
• म्यूज़ियम
• coffee_shop

इसके बाद, इन जगहों के टाइप में से हर एक को वेटिंग असाइन करें. इससे, फ़ाइनल स्कोर में उसकी अहमियत का पता चलता है. वज़न तय करते समय, इस बात का ध्यान रखें कि आपके इस्तेमाल के उदाहरण और उपयोगकर्ता की प्राथमिकताओं के हिसाब से सबसे अहम क्या है. इस उदाहरण के लिए, वेटिंग स्केल 0 और 1 के बीच होगा. यह इस तरह से होगा:

Places Aggregate API को कॉल करना

अब आपके पास उन जगहों की सूची है जिनमें आपकी दिलचस्पी है. अगला चरण, Places Aggregate API को कॉल करना है.

Places Aggregate API के लिए, जगह की जानकारी का फ़िल्टर ज़रूरी है. इस उदाहरण के लिए, circle का इस्तेमाल करें. इसमें latLng के तौर पर अपने होटल की जगह और radius के तौर पर 500 मीटर का इस्तेमाल करें. साथ ही, ratingFilter को सेट करें, ताकि 3.8 से 5 के बीच रेटिंग वाले होटल दिखाए जा सकें. साथ ही, कम रेटिंग वाले होटलों को गिनती से बाहर रखा जा सके.

अपनी ज़रूरत के हिसाब से, जगह की जानकारी के फ़िल्टर की सेटिंग में बदलाव करके देखें. उदाहरण के लिए, हो सकता है कि आपको अपने अक्षांश और देशांतर के बीच में मौजूद जगह के आस-पास के बड़े दायरे को कैप्चर करना हो. इसके लिए, आपको दायरे की वैल्यू बढ़ानी होगी. इसके अलावा, खोज के लिए क्षेत्र सेट करने के लिए, किसी दूसरे तरीके का इस्तेमाल किया जा सकता है. जैसे, क्षेत्र या कस्टम क्षेत्र.

आपके पास उपलब्ध विकल्पों के बारे में जानने के लिए, Places Aggregate API के दस्तावेज़ के जगह के हिसाब से फ़िल्टर करने वाले सेक्शन के बारे में जानें.

आपको जिस जगह के टाइप और जगह के लिए कस्टम स्कोर जनरेट करना है उसके लिए, Places Aggregate API को कॉल करें. उदाहरण के लिए, अपने किसी होटल के लिए रेस्टोरेंट प्लेस टाइप के लिए कॉल करें:

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
        }
    }
}'

एपीआई के सभी कॉल पूरे होने के बाद, आपके पास हर जगह के लिए इस तरह का डेटा होता है:

कस्टम लोकेशन स्कोर जनरेट करना

अब आपके पास हर जगह के टाइप के लिए, जगहों की संख्या और वेटिंग की जानकारी है. साथ ही, हर जगह के लिए कस्टम लोकेशन स्कोर जनरेट किया जा सकता है. इस सेक्शन में, हम दो विकल्पों के बारे में बात करेंगे. पहला, स्थानीय एल्गोरिदम का इस्तेमाल करना और दूसरा, Gemini Developer API का इस्तेमाल करना.

पहला विकल्प: एल्गोरिदम का इस्तेमाल करना

हमारा पहला विकल्प, स्थानीय एल्गोरिदम का इस्तेमाल करके स्कोर जनरेट करना है. इसके लिए, हर जगह के टाइप के लिए वेटिंग और गिनती का इस्तेमाल किया जाता है. इस स्कोर को 0 से 5 के स्केल पर नॉर्मलाइज़ करें. इसमें ज़्यादा वैल्यू होने का मतलब है कि आपकी शर्तों के हिसाब से, जगह ज़्यादा आकर्षक है. इस उदाहरण के लिए, ऊपर दिए गए डेटा से दो JavaScript ऑब्जेक्ट जनरेट करें:

    {
      "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 (दशमलव के बाद दो अंकों तक पूर्णांक बनाया गया है).

दूसरा विकल्प: Gemini Developer API का इस्तेमाल करना

लोकल एल्गोरिदम का इस्तेमाल करने के बजाय, Gemini Developer API सभी जगहों के लिए, पसंद के मुताबिक़ जगह का स्कोर कैलकुलेट करने का बेहतर तरीका उपलब्ध कराता है. सिस्टम के निर्देशों के साथ, अपने सभी होटल की जगहों के लिए, सिर्फ़ गिनती और वेटिंग डेटा दें.

यह तरीका तब खास तौर पर काम आता है, जब आपको कैलकुलेशन में ऐसी जानकारी शामिल करनी हो जो ज़्यादा बारीकी से दी गई हो. जैसे:

• हर होटल की जगह के बारे में टेक्स्ट में जानकारी. उदाहरण के लिए: "यह जगह परिवारों के लिए अच्छी है और यहां रात में शांति रहती है".
• आपके उपयोगकर्ता के बारे में जानकारी, जैसे कि: "यह उपयोगकर्ता परिवार के लिए बुकिंग कर रहा है और इसे ऐसी जगह चाहिए जो शांत हो और शहर के बीच में हो".

Gemini Developer API, इस गुणात्मक डेटा को समझ सकता है और इसका इस्तेमाल कर सकता है. इससे, सिर्फ़ गणित के आधार पर स्कोर देने के बजाय, ज़्यादा बेहतर और काम का स्कोर मिलता है.

Gemini Developer API का इस्तेमाल करके, ऊपर दी गई जगह के टाइप और वेटिंग टेबल के अलावा, हर जगह के लिए ब्यौरे का डेटा भी पाया जा सकता है. यह डेटा इस तरह दिखता है:

इन क्वालिटीटिव ब्यौरों के साथ-साथ, उपयोगकर्ता की जानकारी या प्राथमिकताओं को भी 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 को यह पता चलता है कि किस तरह के डेटा की उम्मीद की जानी चाहिए और एआई मॉडल से किस तरह के आउटपुट की उम्मीद की जानी चाहिए. इसमें 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 ऐरे को इस तरह से दिखाए:

• जगह का अक्षांश और देशांतर
• कस्टम लोकेशन स्कोर

ऊपर दिए गए सिस्टम के निर्देशों और स्ट्रक्चर्ड आउटपुट का इस्तेमाल करके, किसी एक जगह के लिए Gemini से मिला जवाब इस तरह दिखेगा. इसमें score, पसंद के मुताबिक़ जगह का स्कोर होगा:

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

स्कोर दिखाना

ऊपर बताए गए तरीकों में से किसी एक का इस्तेमाल करके, हर जगह के लिए कस्टम लोकेशन स्कोर जनरेट किया जा सकता है. इसके बाद, इसे आपके होटल की जानकारी के साथ दिखाया जा सकता है. इसके अलावा, इसे खोज के नतीजों को फ़िल्टर करने के विकल्प के तौर पर भी इस्तेमाल किया जा सकता है. उदाहरण के लिए, "मुझे ऐसी जगहें दिखाओ जिन्हें पर्यटकों के लिए अच्छी जगह के तौर पर ज़्यादा रेटिंग मिली है". इससे आपके खरीदारों को बुकिंग करते समय, डेटा के आधार पर फ़ैसले लेने में मदद मिलेगी.

नतीजा

कस्टम लोकेशन स्कोर का इस्तेमाल करके, उपयोगकर्ताओं को किसी इलाके के बारे में एक नज़र में जानकारी दी जा सकती है. इस दस्तावेज़ में, पांच अलग-अलग तरह की जगहों के हिसाब से, अलग-अलग जगहों के लिए कस्टम लोकेशन स्कोर जनरेट करने का तरीका बताया गया है. इस सुविधा को अपनी ज़रूरतों के हिसाब से बदला जा सकता है. साथ ही, एक जैसे प्लेस टाइप को एक अनुरोध में शामिल किया जा सकता है, ताकि उन टाइप की कुल संख्या मिल सके. इससे आपको कस्टम लोकेशन स्कोरिंग की सुविधा मिल पाएगी.

आज ही Places Aggregate API आज़माएं. इससे आपको जगह के बारे में अहम जानकारी देने वाले स्कोर जनरेट करने में मदद मिलेगी. इससे आपके ग्राहक, जगह के हिसाब से बेहतर फ़ैसले ले पाएंगे!

योगदानकर्ता

हेनरिक वाल्व | DevX इंजीनियर