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

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

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

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

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

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

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

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

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

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

फ़िल्टर

जगहों को फ़िल्टर करने की शर्तों के बारे में बताता है. कम से कम, आपको LocationFilter और TypeFilter की जानकारी देनी होगी.

स्थान फ़िल्टर

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

• circle: किसी क्षेत्र को केंद्र और त्रिज्या वाले सर्कल के तौर पर दिखाता है.
• region: किसी इलाके को क्षेत्र के तौर पर तय करता है.
• customArea: किसी इलाके को कस्टम पॉलीगॉन के तौर पर दिखाता है.

सर्कल

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

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

क्षेत्र

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

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

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

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

कस्टम एरिया

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

कस्टम पॉलीगॉन बनाने के लिए, 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 फ़िल्टर की मदद से, ऑपरेटिंग स्टेटस के आधार पर फ़िल्टर किया जा सकता है. जैसे, 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 गड़बड़ी का मैसेज दिखता है.