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

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

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

सर्कल

अगर आपने अपने भौगोलिक इलाके को सर्कल के तौर पर चुना है, तो आपको 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: बाहर रखे गए प्राइमरी प्लेस टाइप की सूची.

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

ध्यान दें: टाइप फ़िल्टर में, तय किए गए टाइप के सबटाइप अपने-आप शामिल हो जाते हैं. उदाहरण के लिए, अगर आपने gym के हिसाब से फ़िल्टर किया है, तो नतीजों में वे जगहें भी शामिल होंगी जिन्हें इसके सब-टाइप, जैसे कि yoga_studio के तहत कैटगरी में रखा गया है.

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

ये फ़िल्टर ज़रूरी नहीं हैं:

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