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

इस दस्तावेज़ में, 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 गड़बड़ी का मैसेज दिखता है.