इस दस्तावेज़ में, 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
फ़िल्टर की मदद से, कारोबार के चालू होने की स्थिति के आधार पर फ़िल्टर किया जा सकता है. जैसे, कारोबार खुला है या कुछ समय के लिए बंद है. अगर operatingStatus
फ़िल्टर सेट नहीं है, तो नतीजों में सिर्फ़ ऐसी जगहें शामिल होती हैं जिनका स्टेटस OPERATING_STATUS_OPERATIONAL
है.
कीमत स्तर
price_levels
फ़िल्टर की मदद से, कीमत के लेवल (जैसे कि मुफ़्त, सामान्य या महंगा) के हिसाब से फ़िल्टर किया जा सकता है. अगर price_levels
फ़िल्टर सेट नहीं है, तो नतीजों में कीमत के सभी लेवल शामिल होते हैं.
रेटिंग फ़िल्टर
उपयोगकर्ताओं की औसत रेटिंग के आधार पर जगहों को फ़िल्टर करता है. इन दोनों फ़ील्ड को सबमिट करना ज़रूरी नहीं है. अगर इन्हें शामिल नहीं किया जाता है, तो डिफ़ॉल्ट रूप से उन जगहों को भी शामिल किया जाएगा जिनकी रेटिंग नहीं है.
minRating
: उपयोगकर्ताओं की औसत रेटिंग कम से कम 1.0 और 5.0 के बीच होनी चाहिए.maxRating
: उपयोगकर्ताओं की सबसे ज़्यादा औसत रेटिंग (1.0 से 5.0 के बीच).
इसके अलावा, minRating
की वैल्यू हमेशा maxRating
की वैल्यू से कम या उसके बराबर होनी चाहिए. अगर minRating
को maxRating
से ज़्यादा के तौर पर सेट किया गया है, तो INVALID_ARGUMENT
गड़बड़ी का मैसेज दिखता है.