जगह का कस्टम स्कोर बनाने के लिए, 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 आज़माएं. इससे, आपके ग्राहक जगह के हिसाब से सही फ़ैसले ले पाएंगे!

योगदानकर्ता

Henrik Valve | DevX के इंजीनियर