अनुरोध पैरामीटर

इस दस्तावेज़ में, Places Aggregate API के अनुरोध पैरामीटर के बारे में बताया गया है. साथ ही, इस सेवा का इस्तेमाल करने के बारे में अहम जानकारी और सबसे सही तरीके भी बताए गए हैं.

Places Aggregate API की मदद से, कई अहम काम किए जा सकते हैं:

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

ज़रूरी पैरामीटर

इस सेक्शन में, Places Aggregate API को अनुरोध भेजने के लिए ज़रूरी पैरामीटर के बारे में बताया गया है. हर अनुरोध में यह जानकारी शामिल होनी चाहिए:

• यह एक तरह की अहम जानकारी है.
• जगह के हिसाब से फ़िल्टर करने की सुविधा और टाइप के हिसाब से फ़िल्टर करने की सुविधा.

अहम जानकारी का टाइप

इससे यह तय किया जाता है कि आपको किस तरह की अहम जानकारी का हिसाब लगाना है. यहां दी गई अहम जानकारी के टाइप काम करते हैं:

• INSIGHT_COUNT: फ़िल्टर करने की शर्त से मेल खाने वाली जगहों की संख्या दिखाता है.
• INSIGHT_PLACES: यह फ़िल्टर के मानदंड से मेल खाने वाले जगह के आईडी दिखाता है.

फ़िल्टर

इससे जगहों को फ़िल्टर करने की शर्तों के बारे में पता चलता है. आपको कम से कम LocationFilter और TypeFilter एट्रिब्यूट की वैल्यू देनी होगी.

स्थान फ़िल्टर

जगह के हिसाब से फ़िल्टर, इनमें से किसी एक तरह का हो सकता है:

• circle: यह किसी इलाके को एक वृत्त के तौर पर दिखाता है. इसमें केंद्र और त्रिज्या होती है.
• region: किसी इलाके को क्षेत्र के तौर पर तय करता है.
• customArea: किसी इलाके को कस्टम पॉलीगॉन के तौर पर तय करता है.

सर्कल

अगर आपने अपने भौगोलिक क्षेत्र को सर्कल के तौर पर चुना है, तो आपको center और radius की जानकारी देनी होगी. center, अक्षांश और देशांतर या सर्कल के बीच की जगह का प्लेस आईडी हो सकता है. इस तरीके से, आपके तय किए गए गोलाकार क्षेत्र के आधार पर सटीक और सही तरीके से फ़िल्टर किया जा सकता है.

• center:
  • latLng: सर्कल के केंद्र का अक्षांश और देशांतर. अक्षांश, -90 से 90 के बीच की कोई संख्या होनी चाहिए. देशांतर, -180 से 180 के बीच की कोई संख्या होनी चाहिए.
  • place: सर्कल के सेंटर का प्लेस आईडी. ध्यान दें कि सिर्फ़ पॉइंट प्लेस काम करते हैं. यह स्ट्रिंग, places/ प्रीफ़िक्स से शुरू होनी चाहिए.
• radius: सर्कल का दायरा, मीटर में. यह संख्या पॉज़िटिव होनी चाहिए.

क्षेत्र

place पैरामीटर में जगह का आईडी पास करके, अपने इलाके को क्षेत्र के तौर पर तय करें. जगह का आईडी, किसी भौगोलिक क्षेत्र को दिखाता है. जैसे, कोई ऐसा क्षेत्र जिसे पॉलीगॉन से दिखाया जा सकता है. उदाहरण के लिए, टैंपा, फ़्लोरिडा का प्लेस आईडी places/ChIJ4dG5s4K3wogRY7SWr4kTX6c है. ध्यान दें कि सभी जगह के आईडी की ज्यामिति अच्छी तरह से तय नहीं की गई है. ऐसे मामलों में, Places Aggregate API, 400 गड़बड़ी कोड दिखाता है. साथ ही, एक मैसेज दिखाता है, जिसमें बताया जाता है कि यह क्षेत्र काम नहीं करता है. इसके अलावा, जटिल भौगोलिक क्षेत्रों के लिए, इंटरनल प्रोसेसिंग ऑप्टिमाइज़ेशन की वजह से, क्षेत्र का थोड़ा ज़्यादा अनुमान (दो से तीन प्रतिशत तक) लगाया जा सकता है.

यह पता लगाने के लिए कि कोई जगह का आईडी, जगह के ऐसे टाइप को दिखाता है जो काम नहीं करता, Geocoding API के अनुरोध में जगह का आईडी पास करें. जवाब में type ऐरे शामिल होता है. इसमें जगह के आईडी से जुड़े टाइप की सूची होती है. जैसे, locality, neighborhood या country. अगर किसी जगह का कोई भी टाइप इस सूची से मेल खाता है, तो उसे क्षेत्र के हिसाब से फ़िल्टर करने के लिए अस्वीकार कर दिया जाएगा.

जगह के ऐसे टाइप जिनका इस्तेमाल नहीं किया जा सकता:

• establishment: आम तौर पर, यह ऐसी जगह के लिए इस्तेमाल किया जाता है जिसे अब तक कैटगरी में नहीं रखा गया है.
• intersection: यह दो मुख्य सड़कों के इंटरसेक्शन को दिखाता है.
• subpremise: यह परिसर के लेवल से नीचे की किसी ऐसी इकाई के बारे में बताता है जिसे टारगेट किया जा सकता है. जैसे, अपार्टमेंट, यूनिट या सुइट.

कस्टम एरिया

अक्षांश और देशांतर के निर्देशांकों का इस्तेमाल करके, कस्टम पॉलीगॉन के क्षेत्र को तय करता है.

कस्टम पॉलीगॉन बनाने और अनुरोध में उन निर्देशांकों को डालने के लिए, https://geojson.io/ पर जाएं. पॉलीगॉन में कम से कम चार निर्देशांक होने चाहिए. इसमें पहले और आखिरी निर्देशांक एक जैसे होने चाहिए. दिए गए कम से कम तीन कोऑर्डिनेट यूनीक होने चाहिए.

लगातार एक जैसे कोऑर्डिनेट को एक ही कोऑर्डिनेट माना जाएगा. हालांकि, एक जैसे न होने वाले डुप्लीकेट निर्देशांकों (ज़रूरी एक जैसे पहले और आखिरी निर्देशांकों के अलावा) से गड़बड़ी होगी.

इसके अलावा, आस-पास न होने वाले किनारों को एक-दूसरे को काटने की अनुमति नहीं है. साथ ही, 180 डिग्री की लंबाई वाले किनारों की अनुमति नहीं है. इसका मतलब है कि आस-पास के वर्टिकल, एंटीपोडल नहीं हो सकते.

उदाहरण के लिए:

"coordinates":[
   {
      "latitude":37.776,
      "longitude":-122.666
   },
   {
      "latitude":37.130,
      "longitude":-121.898
   },
   {
      "latitude":37.326,
      "longitude":-121.598
   },
   {
      "latitude":37.912,
      "longitude":-122.247
   },
   {
      "latitude":37.776,
      "longitude":-122.666
   }
]

टाइप फ़िल्टर

इससे यह तय होता है कि किन जगहों को शामिल करना है या बाहर रखना है. Places Aggregate API के साथ काम करने वाले प्राइमरी और सेकंडरी, दोनों तरह के प्लेस टाइप की सूची देखने के लिए, Places API (नया) के प्लेस टाइप में जाकर, टेबल A देखें. आपको कम से कम एक includedTypes या includedPrimaryTypes टाइप बताना होगा.

• includedTypes: इसमें शामिल किए गए प्लेस टाइप की सूची.
• excludedTypes: शामिल नहीं किए गए प्लेस टाइप की सूची.
• includedPrimaryTypes: इसमें शामिल मुख्य जगहों के टाइप की सूची.
• excludedPrimaryTypes: बाहर रखे गए मुख्य जगहों के टाइप की सूची.

टाइप फ़िल्टर और जगह के टाइप के काम करने के तरीके के बारे में ज़्यादा जानने के लिए, टाइप फ़िल्टर के बारे में ज़्यादा जानकारी लेख पढ़ें.

ज़रूरी नहीं पैरामीटर

इन फ़िल्टर का इस्तेमाल करना ज़रूरी नहीं है:

• operatingStatus: इससे उन जगहों की स्थितियों के बारे में पता चलता है जिन्हें शामिल या बाहर करना है. डिफ़ॉल्ट रूप से, operatingStatus: OPERATING_STATUS_OPERATIONAL (कोई एक वैल्यू) के हिसाब से फ़िल्टर किया जाता है.
• priceLevels: इसमें शामिल किए जाने वाले रेस्टोरेंट के लिए, कीमत के लेवल तय किए जाते हैं. डिफ़ॉल्ट रूप से, कीमत के लेवल के हिसाब से फ़िल्टर करने की सुविधा लागू नहीं होती है. साथ ही, सभी जगहों (उन जगहों के साथ-साथ जिनकी कीमत के लेवल की जानकारी मौजूद नहीं है) के नतीजे दिखाए जाते हैं.
• ratingFilter: इससे जगहों की रेटिंग रेंज के बारे में पता चलता है. डिफ़ॉल्ट रूप से, फ़िल्टर नहीं किया जाता. इसका मतलब है कि सभी रेटिंग, नतीजों में शामिल होती हैं.

कारोबार की स्थिति

operatingStatus फ़िल्टर की मदद से, ऑपरेटिंग स्टेटस के आधार पर फ़िल्टर किया जा सकता है. जैसे, OPERATIONAL या TEMPORARILY_CLOSED. operatingStatus फ़िल्टर का तरीका इस तरह काम करता है:

• अगर कोई फ़िल्टर नहीं दिया गया है, तो नतीजों में सिर्फ़ वे जगहें शामिल की जाती हैं जिनका स्टेटस OPERATING_STATUS_OPERATIONAL है.
• अगर एक या उससे ज़्यादा फ़िल्टर दिए गए हैं, तो आपको चालू स्थिति की मान्य वैल्यू (OPERATING_STATUS_OPERATIONAL, OPERATING_STATUS_PERMANENTLY_CLOSED या OPERATING_STATUS_TEMPORARILY_CLOSED) देनी होंगी.

कीमत स्तर

priceLevels फ़िल्टर की मदद से, जगहों को उनके कीमत स्तर के हिसाब से फ़िल्टर किया जा सकता है. कीमत के लेवल की मान्य वैल्यू ये हैं: PRICE_LEVEL_FREE, PRICE_LEVEL_INEXPENSIVE, PRICE_LEVEL_MODERATE, PRICE_LEVEL_EXPENSIVE, और PRICE_LEVEL_VERY_EXPENSIVE.

priceLevels फ़िल्टर इस तरह काम करता है:

• अगर कोई फ़िल्टर नहीं दिया गया है, तो: सभी जगहों की जानकारी दिखाई जाती है. इससे कोई फ़र्क़ नहीं पड़ता कि उन्हें कीमत का लेवल असाइन किया गया है या नहीं. इसमें ऐसी जगहें शामिल हैं जिनके लिए कीमत के लेवल की जानकारी मौजूद नहीं है. ऐसा हो सकता है कि कीमत के लेवल के हिसाब से फ़िल्टर करने पर, ये जगहें न दिखें.
• अगर एक या उससे ज़्यादा फ़िल्टर दिए गए हैं, तो: सिर्फ़ वे जगहें दिखाई जाती हैं जो तय किए गए किराये के लेवल से मेल खाती हैं.

रेटिंग फ़िल्टर

यह जगहें फ़िल्टर करता है. इसके लिए, उपयोगकर्ताओं की दी गई औसत रेटिंग का इस्तेमाल किया जाता है. ये दोनों फ़ील्ड भरने ज़रूरी नहीं हैं. इसलिए, अगर इन्हें नहीं भरा जाता है, तो डिफ़ॉल्ट रूप से उन जगहों को भी शामिल किया जाएगा जिनकी कोई रेटिंग नहीं है.

• minRating: उपयोगकर्ता की औसत रेटिंग (1.0 से 5.0 के बीच) कम से कम होनी चाहिए.
• maxRating: उपयोगकर्ता की औसत रेटिंग (1.0 से 5.0 के बीच).

इसके अलावा, minRating की वैल्यू हमेशा maxRating की वैल्यू से कम या उसके बराबर होनी चाहिए. अगर minRating को maxRating से ज़्यादा के तौर पर सेट किया जाता है, तो INVALID_ARGUMENT गड़बड़ी दिखती है.