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

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