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

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