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

इस दस्तावेज़ में, 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, कुछ प्लेस आईडी इस्तेमाल नहीं करता. ये प्लेस आईडी, इन तरह के क्षेत्रों से जुड़े होते हैं:

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

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