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

इस दस्तावेज़ में, 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: किसी इलाके को कस्टम पॉलीगॉन के तौर पर तय करता है.

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

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

सर्कल

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

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

क्षेत्र

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

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