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

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

Places Aggregate API की मदद से, ये मुख्य काम किए जा सकते हैं:

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

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

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

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

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

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

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

ध्यान दें: अगर आपने INSIGHT_PLACES चुना है, तो Places Aggregate API, जगह के आईडी सिर्फ़ तब दिखाता है, जब count 100 या इससे कम हो.

फ़िल्टर

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

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

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

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

अहम जानकारी: किसी भी जगह के लिए लोकेशन फ़िल्टर का एरिया, 1556.86 वर्ग मीटर (लगभग एक छोटे शहर के ब्लॉक के साइज़ के बराबर) और 20 खरब वर्ग मीटर (लगभग अलास्का के साइज़ के बराबर) के बीच होना चाहिए. इस रेंज से बाहर के इलाकों के लिए किए गए अनुरोधों पर, INVALID_ARGUMENT गड़बड़ी

दिखेगी.

ध्यान दें: पार्क या एयरपोर्ट जैसी इकाइयों के लिए, अगर पॉलीगोनल बाउंड्री तय की गई है, तो इकाई को खोज के दायरे में तब माना जाता है, जब उसके पॉलीगॉन का कोई भी हिस्सा, खोज के लिए तय किए गए दायरे (सर्कल, क्षेत्र या कस्टम पॉलीगॉन) से मेल खाता हो. The entity's center point does not need to be within the search area.

सर्कल

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

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

क्षेत्र

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

अहम जानकारी: INSIGHT_PLACES इनसाइट टाइप के साथ region फ़िल्टर का इस्तेमाल करने पर, विवादित इलाकों से जुड़े अनुरोध अपने-आप अस्वीकार कर दिए जाते हैं. ऐसा Google की सेवाओं को सटीक और निष्पक्ष बनाए रखने के लिए किया जाता है. विवादित इलाके ऐसे क्षेत्र होते हैं जिनकी सीमाओं को लेकर अलग-अलग देशों या इकाइयों के बीच विवाद होता है. इसके अलावा, इन इलाकों पर मालिकाना हक को लेकर भी विवाद होता है. विवादित सीमाओं को Google Maps पर स्लेटी रंग की डैश वाली लाइन से दिखाया जाता है.

विवादित क्षेत्रों की पहचान कैसे की जाती है, इस बारे में ज़्यादा जानने के लिए, देश की सीमाओं और उनके नाम के बारे में जानकारी लेख पढ़ें.

अहम जानकारी: Google, कुछ ऐसे प्लेस आईडी के साथ काम नहीं करता जो इस तरह के क्षेत्र के टाइप से जुड़े होते हैं:

• ऐसे बड़े क्षेत्र जिनके लिए अनुरोध पूरा होने में ज़्यादा समय लगता है.
• ऐसे क्षेत्र जो इतने छोटे हैं कि वे निजता से जुड़े कानूनों का पालन नहीं करते.

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

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

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

ध्यान दें: ऊपर दी गई सूची में शामिल नहीं होने पर भी, कुछ जगहों को अस्वीकार किया जा सकता है. ऐसा तब होता है, जब उनमें पॉलीगॉन की ज्यामिति सही तरीके से तय न की गई हो. इस तरह की गड़बड़ी, neighborhood, locality, sublocality जैसे टाइप और उनके नंबर वाले वैरिएंट (sublocality_level_1, sublocality_level_2, sublocality_level_3, sublocality_level_4) के साथ ज़्यादा होती है. इस मामले में, गड़बड़ी का कोड 400 दिखता है.

कस्टम एरिया

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

अहम जानकारी: बहुभुज के वर्टिस को तय करने वाले निर्देशांकों को घड़ी की सुई की उलटी दिशा में क्रम से लगाया जाना चाहिए. यह पॉलीगॉन तय करने के लिए, इंडस्ट्री स्टैंडर्ड के नियमों का पालन करता है. इसमें घड़ी की सुई की उलटी दिशा में क्रम से लगाने पर, पॉलीगॉन के अंदर का हिस्सा, सीमा के किनारों के बाईं ओर दिखता है.

अहम जानकारी: कस्टम एरिया में 7,000 या इससे कम वर्टेक्स होने चाहिए.

कस्टम पॉलीगॉन बनाने और उन निर्देशांकों को अनुरोध में डालने के लिए, 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 गड़बड़ी दिखती है.