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

इस दस्तावेज़ में, 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 गड़बड़ी कोड दिखाता है. साथ ही, एक मैसेज दिखाता है, जिससे पता चलता है कि यह इलाका काम नहीं करता. इसके अलावा, जटिल भौगोलिक क्षेत्रों के लिए, इंटरनल प्रोसेसिंग ऑप्टिमाइज़ेशन की वजह से, क्षेत्र का थोड़ा ज़्यादा अनुमान लगाया जा सकता है. यह क्षेत्र के हिसाब से 2 से 3% तक हो सकता है.

यह पता लगाने के लिए कि कोई जगह का आईडी, ऐसी जगह के टाइप को दिखाता है जो काम नहीं करता, 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 गड़बड़ी का मैसेज दिखता है.