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

इस दस्तावेज़ में, Places Insights API के अनुरोध पैरामीटर के बारे में बताया गया है. साथ ही, इसमें इस सेवा को इस्तेमाल करने के बारे में अहम जानकारी और सबसे सही तरीके भी शामिल हैं.

Places Insights API की मदद से, कई अहम काम किए जा सकते हैं:

• जगहों की संख्या: खास शर्तों से मैच करने वाली जगहों की संख्या तय करें. जैसे, जगह का टाइप, कारोबार की स्थिति, कीमत का लेवल, और रेटिंग.
• जगह की जानकारी पाना: तय किए गए फ़िल्टर से मैच करने वाली जगहों के नाम पाएं. इसके बाद, Places API का इस्तेमाल करके ज़्यादा जानकारी पाएं.
• फ़िल्टर करने की सुविधा: सटीक जानकारी पाने के लिए, ज़्यादा जानकारी वाले फ़िल्टर लागू करें. उपलब्ध फ़िल्टर में ये शामिल हैं:
  • भौगोलिक इलाका (सर्कल, क्षेत्र या कस्टम पॉलीगॉन)
  • जगह के टाइप
  • कारोबार की स्थिति
  • कीमत के लेवल
  • रेटिंग की सीमाएं

ज़रूरी पैरामीटर

इस सेक्शन में, Places Insights API को अनुरोध करते समय ज़रूरी पैरामीटर के बारे में बताया गया है. हर अनुरोध में यह जानकारी होनी चाहिए:

• अहम जानकारी का एक टाइप.
• जगह और टाइप का फ़िल्टर.

अहम जानकारी का टाइप

इससे यह तय होता है कि आपको किस तरह की अहम जानकारी का हिसाब लगाना है. इनसाइट के ये टाइप काम करते हैं:

• INSIGHT_COUNT: फ़िल्टर की शर्तों से मैच करने वाली जगहों की संख्या दिखाता है.
• INSIGHT_PLACES: फ़िल्टर की शर्तों से मैच करने वाले जगह के आईडी दिखाता है.

ध्यान दें: अगर INSIGHT_PLACES चुना जाता है, तो Places Insights 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 Insights API, गड़बड़ी का कोड 400 दिखाता है. साथ ही, एक मैसेज भी दिखाता है, जिसमें बताया जाता है कि यह इलाका काम नहीं करता. इसके अलावा, मुश्किल भौगोलिक इलाकों के लिए, डेटा प्रोसेस करने के तरीके को ऑप्टिमाइज़ करने की वजह से, इलाके के बारे में थोड़ा ज़्यादा अनुमान लगाया जा सकता है. यह अनुमान, इलाके के बारे में बताने वाले डेटा से 2-3% तक ज़्यादा हो सकता है.

अहम जानकारी: INSIGHT_PLACES अहम जानकारी के टाइप के साथ region फ़िल्टर का इस्तेमाल करने पर, जिन अनुरोधों में विवादित इलाकों की जानकारी शामिल होती है उन्हें अपने-आप अस्वीकार कर दिया जाता है. ऐसा इसलिए किया जाता है, ताकि Google की सेवाओं की सटीक और निष्पक्ष जानकारी दी जा सके. विवादित इलाके ऐसे इलाके होते हैं जिनकी सीमाओं को लेकर विवाद होता है या जिन पर अलग-अलग देश या इकाइयां दावा करती हैं. विवादित सीमाओं को Google Maps पर स्लेटी रंग की डैश वाली लाइन से दिखाया जाता है.

विवादित इलाकों की पहचान करने के तरीके के बारे में ज़्यादा जानने के लिए, देश की सीमाओं और उनके नामों के बारे में जानकारी लेख पढ़ें.

अहम जानकारी: Google, कुछ खास जगहों के आईडी के साथ काम नहीं करता. ये आईडी, इस तरह के इलाकों से जुड़े होते हैं:

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

यह पता लगाने के लिए कि कोई जगह का आईडी, ऐसी जगह की जानकारी दिखाता है जिसे Google Maps पर नहीं दिखाया जा सकता, Geocoding API अनुरोध में जगह का आईडी डालें. जवाब में, type कलेक्शन शामिल होता है, जिसमें जगह के आईडी से जुड़ी जगह के टाइप की सूची होती है. जैसे, city, neighborhood या country.

इन जगहों के लिए, यह सुविधा काम नहीं करती:

• establishment: आम तौर पर, यह ऐसी जगह के बारे में बताता है जिसे अब तक किसी कैटगरी में नहीं रखा गया है.
• street_number: इससे सड़क का सटीक नंबर पता चलता है.
• floor: इमारत के पते में फ़्लोर की जानकारी देता है.
• post_box: किसी खास डाक बॉक्स को दिखाता है.
• street_address: इससे मोहल्ले का सटीक पता पता चलता है.
• room: इमारत के पते में कमरे की जानकारी देता है.
• intersection: आम तौर पर, दो मुख्य सड़कों के चौराहे को दिखाता है.
• landmark: इससे आस-पास की किसी ऐसी जगह का पता चलता है जिसका इस्तेमाल नेविगेट करने में मदद करने के लिए, रेफ़रंस के तौर पर किया जाता है.
• subpremise: यह प्रॉपर्टी, प्राइमिस लेवल के नीचे मौजूद ऐसी इकाई के बारे में बताती है जिसे पते से पहुंचा जा सकता है. जैसे, अपार्टमेंट, यूनिट या सुइट.
• sublocality_level_5: यह सब-लोकलिटी पते के कॉम्पोनेंट का सबसे सटीक लेवल होता है. आम तौर पर, यह किसी शहर के अंदर मौजूद बहुत छोटे इलाके के उप-डिवीज़न या हाइपर-लोकल इलाके को दिखाता है.

कस्टम एरिया

अक्षांश और देशांतर निर्देशांक का इस्तेमाल करके, कस्टम पॉलीगॉन का क्षेत्र तय करता है.

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

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

• includedTypes: शामिल की गई जगहों के टाइप की सूची.
• excludedTypes: उन जगहों की सूची जिन्हें शामिल नहीं किया गया है.
• includedPrimaryTypes: शामिल की गई मुख्य जगहों की सूची.
• excludedPrimaryTypes: उन मुख्य जगहों की सूची जिन्हें शामिल नहीं किया गया है.

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

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

इन फ़िल्टर का इस्तेमाल करना ज़रूरी नहीं है:

• operatingStatus: इसमें उन जगहों की स्थितियां बताई जाती हैं जिन्हें शामिल करना है या बाहर रखना है. डिफ़ॉल्ट रूप से, operatingStatus: OPERATING_STATUS_OPERATIONAL (एक खास वैल्यू) के हिसाब से फ़िल्टर किया जाता है.
• priceLevels: इससे जगहों के किराये के लेवल की जानकारी मिलती है. डिफ़ॉल्ट रूप से, फ़िल्टर नहीं किया जाता (नतीजों में सभी कीमत के लेवल शामिल होते हैं).
• ratingFilter: इससे जगहों की रेटिंग की रेंज का पता चलता है. डिफ़ॉल्ट रूप से, कोई फ़िल्टर नहीं होता (नतीजों में सभी रेटिंग शामिल होती हैं).

कारोबार की स्थिति

operatingStatus फ़िल्टर की मदद से, कारोबार के चालू होने की स्थिति के आधार पर फ़िल्टर किया जा सकता है. जैसे, कारोबार खुला है या कुछ समय के लिए बंद है. अगर operatingStatus फ़िल्टर सेट नहीं है, तो नतीजों में सिर्फ़ ऐसी जगहें शामिल होती हैं जिनका स्टेटस OPERATING_STATUS_OPERATIONAL है.

कीमत स्तर

price_levels फ़िल्टर की मदद से, कीमत के लेवल (जैसे कि मुफ़्त, सामान्य या महंगा) के हिसाब से फ़िल्टर किया जा सकता है. अगर price_levels फ़िल्टर सेट नहीं है, तो नतीजों में कीमत के सभी लेवल शामिल होते हैं.

रेटिंग फ़िल्टर

उपयोगकर्ताओं की औसत रेटिंग के आधार पर जगहों को फ़िल्टर करता है. इन दोनों फ़ील्ड को सबमिट करना ज़रूरी नहीं है. अगर इन्हें शामिल नहीं किया जाता है, तो डिफ़ॉल्ट रूप से उन जगहों को भी शामिल किया जाएगा जिनकी रेटिंग नहीं है.

• minRating: उपयोगकर्ताओं की औसत रेटिंग कम से कम 1.0 और 5.0 के बीच होनी चाहिए.
• maxRating: उपयोगकर्ताओं की सबसे ज़्यादा औसत रेटिंग (1.0 से 5.0 के बीच).

इसके अलावा, minRating की वैल्यू हमेशा maxRating की वैल्यू से कम या उसके बराबर होनी चाहिए. अगर minRating को maxRating से ज़्यादा के तौर पर सेट किया गया है, तो INVALID_ARGUMENT गड़बड़ी का मैसेज दिखता है.