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

इस दस्तावेज़ में, 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 वर्ग मीटर (लगभग एक छोटे शहर के ब्लॉक के बराबर) से 2 खरब वर्ग मीटर (लगभग अलास्का के बराबर) के बीच होना चाहिए. इस रेंज से बाहर के इलाकों के लिए किए गए अनुरोधों पर, 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, कुछ खास जगहों के आईडी के साथ काम नहीं करता. ये आईडी, इस तरह के इलाकों से जुड़े होते हैं:

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

यह पता लगाने के लिए कि जगह का आईडी, ऐसी जगह की जानकारी दिखाता है जिसे Google Maps पर नहीं दिखाया जा सकता, 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 गड़बड़ी का मैसेज दिखता है.