ऑटोकंप्लीट (नई सुविधा), किसी अनुरोध के जवाब में जगह के सुझाव दिखाती है. इस अनुरोध में, खोज के लिए इस्तेमाल होने वाली टेक्स्ट स्ट्रिंग और खोज के दायरे को कंट्रोल करने वाली भौगोलिक सीमाएं शामिल होती हैं. ऑटोकंप्लीट की सुविधा, इनपुट के पूरे शब्दों और सबस्ट्रिंग से मैच कर सकती है. इससे जगहों के नाम, पते, और प्लस कोड का पता चलता है. आपका ऐप्लिकेशन, उपयोगकर्ता के टाइप करते ही क्वेरी भेज सकता है, ताकि जगह और क्वेरी के अनुमान तुरंत दिए जा सकें.
उदाहरण के लिए, आपने अपने-आप पूरी होने वाली खोज की सुविधा को कॉल करने के लिए, "सिसिलियन पिज़" जैसी किसी स्ट्रिंग का इस्तेमाल किया है. इसमें उपयोगकर्ता का कुछ हिस्सा शामिल है. साथ ही, खोज के लिए सिर्फ़ सैन फ़्रांसिस्को, कैलिफ़ोर्निया को चुना गया है. इसके बाद, जवाब में जगह के उन सुझावों की सूची दिखती है जो खोज स्ट्रिंग और खोज के इलाके से मेल खाते हैं. जैसे, "Sicilian Pizza Kitchen" नाम का रेस्टोरेंट.
जगह के सुझावों को इस तरह से डिज़ाइन किया गया है कि उपयोगकर्ता को अपनी पसंद की जगह चुनने में मदद मिल सके. जगह के सुझावों के बारे में ज़्यादा जानकारी पाने के लिए, जगह की जानकारी (नया) का अनुरोध किया जा सकता है.
ऑटोकंप्लीट (नया) अनुरोध
आपका ऐप्लिकेशन, ऑटोकंप्लीट एपीआई से जगह के नाम और/या पतों के सुझावों की सूची पा सकता है. इसके लिए, उसे PlacesClient.findAutocompletePredictions()
को कॉल करके, FindAutocompletePredictionsRequest
ऑब्जेक्ट को पास करना होगा. नीचे दिए गए उदाहरण में, PlacesClient.findAutocompletePredictions()
को पूरा कॉल दिखाया गया है.
Places.initializeWithNewPlacesApiEnabled(context, apiKey); final List<Field> placeFields = getPlaceFields(); LatLng center = new LatLng(37.7749, -122.4194); CircularBounds circle = CircularBounds.newInstance(center, /* radius = */ 5000); final FindAutocompletePredictionsRequest autocompletePlacesRequest = FindAutocompletePredictionsRequest.builder() .setQuery("Sicilian piz") .setRegionCode("ES") .setLocationRestriction(circle) .build()); placesClient.findAutocompletePredictions(autoCompletePlacesRequest) .addOnSuccessListener( (response) -> { List<AutocompletePrediction> predictions = response.getResult().getAutocompletePredictions(); } ).addOnFailureListener( exception -> { Log.e(TAG, "some exception happened" + exception.getMessage()); }) );
जवाबों को अपने-आप पूरा करने की सुविधा (नई)
एपीआई, Task
में FindAutocompletePredictionsResponse
दिखाता है.
FindAutocompletePredictionsResponse
में, अनुमानित जगहों को दिखाने वाले ज़्यादा से ज़्यादा पांच AutocompletePrediction
ऑब्जेक्ट की सूची होती है. अगर क्वेरी और फ़िल्टर की शर्तों से मेल खाने वाली कोई जगह नहीं है, तो हो सकता है कि सूची खाली हो.
अनुमानित जगह की जानकारी पाने के लिए, इन तरीकों का इस्तेमाल किया जा सकता है:
getFullText(CharacterStyle)
जगह की जानकारी का पूरा टेक्स्ट दिखाता है. यह प्राइमरी और सेकंडरी टेक्स्ट का कॉम्बिनेशन है. उदाहरण: "आइफ़िल टावर, एवेन्यू अनातोल फ़्रांस, पेरिस, फ़्रांस". इसके अलावा, इस तरीके से,CharacterStyle
का इस्तेमाल करके, खोज के नतीजों से मैच होने वाले ब्यौरे के सेक्शन को अपनी पसंद के स्टाइल में हाइलाइट किया जा सकता है.CharacterStyle
पैरामीटर का इस्तेमाल करना ज़रूरी नहीं है. अगर आपको किसी भी तरह की हाइलाइटिंग की ज़रूरत नहीं है, तो इसे शून्य पर सेट करें.getPrimaryText(CharacterStyle)
, किसी जगह के बारे में बताने वाला मुख्य टेक्स्ट दिखाता है. आम तौर पर, यह जगह का नाम होता है. उदाहरण: "आइफ़िल टावर" और "123 पिट स्ट्रीट".getSecondaryText(CharacterStyle)
जगह की जानकारी का सहायक टेक्स्ट दिखाता है. उदाहरण के लिए, ऑटोकंप्लीट की सुविधा से मिलने वाले सुझावों को दिखाते समय, यह दूसरी लाइन के तौर पर काम आता है. उदाहरण: "Avenue Anatole France, Paris, France" और "Sydney, New South Wales".getPlaceId()
जगह का अनुमान लगाने के लिए, जगह का आईडी दिखाता है. जगह का आईडी, टेक्स्ट वाला एक आइडेंटिफ़ायर होता है. इससे किसी जगह की यूनीक पहचान की जा सकती है. इसका इस्तेमाल, बाद मेंPlace
ऑब्जेक्ट को फिर से पाने के लिए किया जा सकता है. ऑटोमैटिक भरने की सुविधा में जगह के आईडी के बारे में ज़्यादा जानने के लिए, जगह की जानकारी (नया) देखें. जगह के आईडी के बारे में सामान्य जानकारी पाने के लिए, जगह के आईडी की खास जानकारी देखें.getTypes()
इससे, इस जगह से जुड़ी जगह के टाइप की सूची मिलती है.getDistanceMeters()
, इस जगह और अनुरोध में बताए गए ऑरिजिन के बीच की सीधी दूरी को मीटर में दिखाता है.
ज़रूरी पैरामीटर
-
क्वेरी
वह टेक्स्ट स्ट्रिंग जिस पर खोजना है. पूरे शब्द और सबस्ट्रिंग, जगहों के नाम, पते, और प्लस कोड डालें. ऑटोकंप्लीट (नई) सेवा, इस स्ट्रिंग के आधार पर मिलते-जुलते नाम दिखाती है. साथ ही, नतीजों को उनके काम के होने के हिसाब से क्रम में लगाती है.
क्वेरी पैरामीटर सेट करने के लिए,
FindAutocompletePredictionsRequest
ऑब्जेक्ट बनाते समयsetQuery()
तरीका इस्तेमाल करें.
ज़रूरी नहीं पैरामीटर
-
मुख्य टाइप
टेबल A या टेबल B के टाइप से, टाइप की पांच वैल्यू की सूची. इसका इस्तेमाल, जवाब में दिखाई गई जगहों को फ़िल्टर करने के लिए किया जाता है. जवाब में शामिल करने के लिए, जगह की जानकारी, प्राइमरी टाइप की बताई गई वैल्यू में से किसी एक से मेल खानी चाहिए.
किसी जगह के लिए, टेबल A या टेबल B में से किसी एक टेबल में मौजूद प्राइमरी टाइप का इस्तेमाल किया जा सकता है. उदाहरण के लिए, प्राइमरी टाइप
"mexican_restaurant"
या"steak_house"
हो सकता है.INVALID_REQUEST
गड़बड़ी की वजह से अनुरोध अस्वीकार किया जाता है, अगर:- पांच से ज़्यादा टाइप तय किए गए हैं.
- ऐसे सभी टाइप के बारे में बताया गया है जिनकी पहचान नहीं हो सकी.
प्राइमरी टाइप पैरामीटर सेट करने के लिए,
FindAutocompletePredictionsRequest
ऑब्जेक्ट बनाते समयsetTypesFilter()
मेथड को कॉल करें. -
देश
सिर्फ़ उन देशों की सूची में शामिल नतीजे शामिल करें जिनके लिए खोज की गई है. यह सूची, 15 ccTLD ("टॉप-लेवल डोमेन") की दो वर्णों वाली वैल्यू की सूची के तौर पर दी गई है. अगर इस एट्रिब्यूट को शामिल नहीं किया जाता है, तो जवाब पर कोई पाबंदी नहीं लगाई जाती. उदाहरण के लिए, जर्मनी और फ़्रांस तक क्षेत्रों को सीमित करने के लिए:
अगर आपने
locationRestriction
औरincludedRegionCodes
, दोनों की वैल्यू दी है, तो नतीजे, दोनों सेटिंग के इंटरसेक्शन वाले एरिया में दिखेंगे.देशों के पैरामीटर को सेट करने के लिए,
FindAutocompletePredictionsRequest
ऑब्जेक्ट बनाते समयsetCountries()
तरीका इस्तेमाल करें. -
इनपुट ऑफ़सेट
शून्य पर आधारित यूनिकोड कैरेक्टर ऑफ़सेट, जो क्वेरी में कर्सर की पोज़िशन दिखाता है. कर्सर की पोज़िशन से यह तय हो सकता है कि आपको कौनसे सुझाव मिलेंगे. अगर यह फ़ील्ड खाली है, तो यह डिफ़ॉल्ट रूप से क्वेरी की लंबाई पर सेट होता है.
इनपुट ऑफ़सेट पैरामीटर सेट करने के लिए,
FindAutocompletePredictionsRequest
ऑब्जेक्ट बनाते समयsetInputOffset()
तरीका कॉल करें. जगह के हिसाब से पक्षपात या जगह से जुड़ी पाबंदी
खोज के लिए जगह तय करने के लिए, जगह के हिसाब से रुझान या जगह से जुड़ी पाबंदी तय की जा सकती है. हालांकि, दोनों को एक साथ नहीं तय किया जा सकता. जगह की पाबंदी को उस इलाके के तौर पर देखें जहां के नतीजे चाहिए. साथ ही, जगह के हिसाब से नतीजों के पक्षपात को उस इलाके के तौर पर देखें जहां के नतीजे चाहिए. मुख्य अंतर यह है कि जगह के हिसाब से खोज के नतीजे दिखाने की सुविधा के तहत, तय किए गए इलाके से बाहर के नतीजे भी दिख सकते हैं.
जगह के हिसाब से बायस
खोजने के लिए कोई इलाका तय करता है. यह जगह, किसी पाबंदी के तौर पर नहीं, बल्कि किसी खास जगह के हिसाब से काम करती है. इसलिए, तय किए गए इलाके से बाहर के नतीजे भी दिख सकते हैं.
लोकेशन बायस पैरामीटर सेट करने के लिए,
FindAutocompletePredictionsRequest
ऑब्जेक्ट बनाते समयsetLocationBias()
तरीके को कॉल करें.जगह की जानकारी से जुड़ी पाबंदी
खोजने के लिए कोई इलाका तय करता है. तय किए गए इलाके से बाहर के नतीजे नहीं दिखाए जाते.
जगह की पाबंदी वाला पैरामीटर सेट करने के लिए,
FindAutocompletePredictionsRequest
ऑब्जेक्ट बनाते समयsetLocationRestriction()
तरीका कॉल करें.
जगह के हिसाब से रुझान या जगह की पाबंदी वाले इलाके की जानकारी, रेक्टैंगल व्यूपोर्ट या सर्कल के तौर पर दें.
किसी वृत्त को उसके केंद्र बिंदु और त्रिज्या से तय किया जाता है. त्रिज्या को मीटर में दिखाया जाता है. त्रिज्या, 0.0 और 50,000.0 के बीच होनी चाहिए. डिफ़ॉल्ट वैल्यू 0.0 होती है. जगह की पाबंदी के लिए, आपको 0.0 से ज़्यादा की त्रिज्या सेट करनी होगी. ऐसा न करने पर, अनुरोध से कोई नतीजा नहीं मिलता.
रेक्टैंगल, अक्षांश-देशांतर व्यूपोर्ट होता है. इसे डायगनल के दो बिंदुओं
low
औरhigh
के तौर पर दिखाया जाता है. व्यूपोर्ट को एक बंद क्षेत्र माना जाता है. इसका मतलब है कि इसमें उसकी सीमा भी शामिल होती है. अक्षांश की सीमाएं -90 से 90 डिग्री के बीच होनी चाहिए. साथ ही, देशांतर की सीमाएं -180 से 180 डिग्री के बीच होनी चाहिए:- अगर
low
=high
है, तो व्यूपोर्ट में सिर्फ़ एक पॉइंट होता है. - अगर
low.longitude
>high.longitude
है, तो देशांतर की रेंज उलट जाती है (व्यूपोर्ट, देशांतर की 180 डिग्री वाली लाइन को पार कर जाता है). - अगर
low.longitude
= -180 डिग्री औरhigh.longitude
= 180 डिग्री है, तो व्यूपोर्ट में सभी देशांतर शामिल होते हैं. - अगर
low.longitude
= 180 डिग्री औरhigh.longitude
= -180 डिग्री है, तो देशांतर की सीमा खाली है.
low
औरhigh
, दोनों में जानकारी होनी चाहिए. साथ ही, दिखाया गया बॉक्स खाली नहीं होना चाहिए. खाली व्यूपोर्ट की वजह से गड़बड़ी होती है.- अगर
-
शुरुआत की जगह
ऑरिजिन पॉइंट, जहां से डेस्टिनेशन तक की सीधी दूरी का हिसाब लगाया जाता है. इसे
getDistanceMeters()
का इस्तेमाल करके ऐक्सेस किया जाता है. अगर इस वैल्यू को छोड़ा जाता है, तो सीधी दूरी का हिसाब नहीं लगाया जाएगा. इसे अक्षांश और देशांतर के निर्देशांक के तौर पर डालना ज़रूरी है:ऑरिजिन पैरामीटर सेट करने के लिए,
FindAutocompletePredictionsRequest
ऑब्जेक्ट बनाते समयsetOrigin()
तरीके को कॉल करें. -
क्षेत्र कोड
जवाब को फ़ॉर्मैट करने के लिए इस्तेमाल किया जाने वाला क्षेत्र कोड. इसमें पते को फ़ॉर्मैट करने की सुविधा भी शामिल है. इसे ccTLD ("टॉप लेवल डोमेन") के तौर पर दो वर्णों की वैल्यू के तौर पर दिखाया जाता है. ज़्यादातर सीसीटीएलडी कोड, आईएसओ 3166-1 कोड से मिलते-जुलते होते हैं. हालांकि, कुछ कोड अलग होते हैं. उदाहरण के लिए, यूनाइटेड किंगडम का सीसीटीएलडी "uk" (.co.uk) है, जबकि उसका आईएसओ 3166-1 कोड "gb" है. तकनीकी तौर पर, यह कोड "यूनाइटेड किंगडम ऑफ़ ग्रेट ब्रिटेन ऐंड नॉर्दन आयरलैंड" इकाई के लिए है.
अगर आपने क्षेत्र का अमान्य कोड डाला है, तो एपीआई
INVALID_ARGUMENT
के साथ गड़बड़ी का मैसेज दिखाता है. लागू कानून के आधार पर, इस पैरामीटर से नतीजों पर असर पड़ सकता है.क्षेत्र कोड पैरामीटर सेट करने के लिए,
FindAutocompletePredictionsRequest
ऑब्जेक्ट बनाते समयsetRegionCode()
तरीके को कॉल करें. -
सेशन टोकन
सेशन टोकन, उपयोगकर्ता से जनरेट हुई स्ट्रिंग होती हैं. ये ऑटोमैटिक भरने की सुविधा (नया) के कॉल को "सेशन" के तौर पर ट्रैक करती हैं. ऑटोकंप्लीट की सुविधा, बिलिंग के मकसद से, उपयोगकर्ता की ऑटोकंप्लीट की गई खोज की क्वेरी और चुनने के चरणों को अलग-अलग सेशन में ग्रुप करने के लिए, सेशन टोकन का इस्तेमाल करती है. सेशन तब शुरू होता है, जब उपयोगकर्ता कोई क्वेरी टाइप करना शुरू करता है और तब खत्म होता है, जब वह कोई जगह चुनता है. हर सेशन में कई क्वेरी हो सकती हैं. इसके बाद, एक जगह चुनी जा सकती है. किसी सेशन के खत्म होने के बाद, टोक़न अमान्य हो जाता है. इसलिए, आपके ऐप्लिकेशन को हर सेशन के लिए नया टोक़न जनरेट करना होगा. हमारा सुझाव है कि प्रोग्राम के हिसाब से काम करने वाले सभी ऑटोमैटिक भरने वाले सेशन के लिए, सेशन टोकन का इस्तेमाल करें. जब किसी फ़्रैगमेंट को एम्बेड किया जाता है या किसी इंटेंट का इस्तेमाल करके ऑटोमैटिक भरने की सुविधा को लॉन्च किया जाता है, तो एपीआई अपने-आप इसकी देखभाल करता है.
ऑटोमैटिक भरने की सुविधा, हर सेशन की पहचान करने के लिए
AutocompleteSessionToken
का इस्तेमाल करती है. आपके ऐप्लिकेशन को हर नए सेशन की शुरुआत में एक नया सेशन टोकन पास करना चाहिए. इसके बाद, उपयोगकर्ता की चुनी गई जगह की जानकारी पाने के लिए,fetchPlace()
को कॉल करते समय, उसी टोकन को प्लेस आईडी के साथ पास करना चाहिए.सेशन टोकन पैरामीटर सेट करने के लिए,
FindAutocompletePredictionsRequest
ऑब्जेक्ट बनाते समयsetSessionToken()
तरीके को कॉल करें.ज़्यादा जानकारी के लिए, सेशन टोकन देखें.
ऑटोकंप्लीट (नया) के उदाहरण
जगह की जानकारी से जुड़ी पाबंदी और जगह के हिसाब से बायस का इस्तेमाल करना
ऑटोकंप्लीट (नया) सुविधा, खोज के लिए जगह को कंट्रोल करने के लिए, डिफ़ॉल्ट रूप से आईपी बायसिंग का इस्तेमाल करती है. आईपी बायसिंग की मदद से, एपीआई नतीजों में बायस करने के लिए डिवाइस के आईपी पते का इस्तेमाल करता है. खोज के लिए कोई इलाका तय करने के लिए, जगह से जुड़ी पाबंदी या जगह के हिसाब से खोज का इस्तेमाल किया जा सकता है. हालांकि, दोनों का एक साथ इस्तेमाल नहीं किया जा सकता.
जगह की पाबंदी से पता चलता है कि किस इलाके में खोज करनी है. तय किए गए इलाके से बाहर के नतीजे नहीं दिखाए जाते. इस उदाहरण में, जगह की जानकारी की पाबंदी का इस्तेमाल करके, अनुरोध को सैन फ़्रांसिस्को के आस-पास 5,000 मीटर के दायरे में सीमित किया गया है:
Places.initializeWithNewPlacesApiEnabled(context, apiKey); final List<Field> placeFields = getPlaceFields(); LatLng center = new LatLng(37.7749, -122.4194); CircularBounds circle = CircularBounds.newInstance(center, /* radius = */ 5000); final FindAutocompletePredictionsRequest autocompletePlacesRequest = FindAutocompletePredictionsRequest.builder() .setQuery("Amoeba") .setLocationRestriction(circle) .build()); placesClient.findAutocompletePredictions(autoCompletePlacesRequest) .addOnSuccessListener( (response) -> { List<AutocompletePrediction> predictions = response.getResult().getAutocompletePredictions(); } ).addOnFailureListener( exception -> { Log.e(TAG, "some exception happened" + exception.getMessage()); }) );
जगह के हिसाब से, खोज के नतीजे दिखाने की सुविधा में जगह को प्राथमिकता दी जाती है. इसका मतलब है कि खोज के नतीजे, तय की गई जगह के आस-पास के इलाकों के साथ-साथ, तय की गई जगह से बाहर के इलाकों के भी हो सकते हैं. अगले उदाहरण में, जगह के हिसाब से जानकारी का इस्तेमाल करने के लिए, पिछले अनुरोध में बदलाव किया गया है:
Places.initializeWithNewPlacesApiEnabled(context, apiKey); final List<Field> placeFields = getPlaceFields(); LatLng center = new LatLng(37.7749, -122.4194); CircularBounds circle = CircularBounds.newInstance(center, /* radius = */ 5000); final FindAutocompletePredictionsRequest autocompletePlacesRequest = FindAutocompletePredictionsRequest.builder() .setQuery("Amoeba") .setLocationBias(circle) .build()); placesClient.findAutocompletePredictions(autoCompletePlacesRequest) .addOnSuccessListener( (response) -> { List<AutocompletePrediction> predictions = response.getResult().getAutocompletePredictions(); } ).addOnFailureListener( exception -> { Log.e(TAG, "some exception happened" + exception.getMessage()); }) );
प्राइमरी टाइप का इस्तेमाल करना
प्राइमरी टाइप पैरामीटर का इस्तेमाल करके, अनुरोध के नतीजों को किसी खास टाइप तक सीमित करें. इन टाइप के बारे में टेबल A और टेबल B में बताया गया है. ज़्यादा से ज़्यादा पांच वैल्यू का ऐरे दिया जा सकता है. अगर इस विकल्प को छोड़ दिया जाता है, तो सभी टाइप के आइटम दिखाए जाते हैं.
यहां दिए गए उदाहरण में, "फ़ुटबॉल" की क्वेरी स्ट्रिंग दी गई है. साथ ही, "sporting_goods_store"
टाइप के कारोबारों के नतीजों पर पाबंदी लगाने के लिए, primary types पैरामीटर का इस्तेमाल किया गया है:
Places.initializeWithNewPlacesApiEnabled(context, apiKey); final List<Field> placeFields = getPlaceFields(); final List<Place.Field> primaryTypes = Arrays.asList("sporting_goods_store"); LatLng center = new LatLng(37.7749, -122.4194); CircularBounds circle = CircularBounds.newInstance(center, /* radius = */ 5000); final FindAutocompletePredictionsRequest autocompletePlacesRequest = FindAutocompletePredictionsRequest.builder() .setQuery("Soccer") .setIncludedPrimaryTypes(primaryTypes) .setLocationBias(circle) .build()); placesClient.findAutocompletePredictions(autoCompletePlacesRequest) .addOnSuccessListener( (response) -> { List<AutocompletePrediction> predictions = response.getResult().getAutocompletePredictions(); } ).addOnFailureListener( exception -> { Log.e(TAG, "some exception happened" + exception.getMessage()); }) );
अगर आपने प्राइमरी टाइप पैरामीटर को शामिल नहीं किया है, तो हो सकता है कि नतीजों में ऐसी जगहें शामिल हों जो आपको नहीं चाहिए, जैसे कि "athletic_field"
.
ऑरिजिन का इस्तेमाल करना
अनुरोध में origin पैरामीटर को शामिल करने पर, अक्षांश और देशांतर के निर्देशांक के तौर पर दिखाया जाता है. साथ ही, एपीआई रिस्पॉन्स में ऑरिजिन से डेस्टिनेशन तक की सीधी दूरी दिखाता है. इस दूरी को getDistanceMeters()
का इस्तेमाल करके ऐक्सेस किया जाता है. इस उदाहरण में, ऑरिजिन को सैन फ़्रांसिस्को के बीच में सेट किया गया है:
Places.initializeWithNewPlacesApiEnabled(context, apiKey); final List<Field> placeFields = getPlaceFields(); LatLng center = new LatLng(37.7749, -122.4194); CircularBounds circle = CircularBounds.newInstance(center, /* radius = */ 5000); final FindAutocompletePredictionsRequest autocompletePlacesRequest = FindAutocompletePredictionsRequest.builder() .setQuery("Amoeba") .setOrigin(center) .setLocationRestriction(circle) .build()); placesClient.findAutocompletePredictions(autoCompletePlacesRequest) .addOnSuccessListener( (response) -> { List<AutocompletePrediction> predictions = response.getResult().getAutocompletePredictions(); } ).addOnFailureListener( exception -> { Log.e(TAG, "some exception happened" + exception.getMessage()); }) );
एट्रिब्यूशन
मैप के बिना भी, अपने-आप पूरा होने वाले सुझावों की सुविधा (नई) का इस्तेमाल किया जा सकता है. अगर आपने कोई मैप दिखाया है, तो वह Google मैप होना चाहिए. मैप के बिना ऑटोकंप्लीट (नई) सेवा से मिले सुझाव दिखाते समय, आपको खोज फ़ील्ड/नतीजों के साथ इनलाइन में दिखाया गया Google लोगो शामिल करना होगा. ज़्यादा जानकारी के लिए, Google का लोगो और एट्रिब्यूशन दिखाना लेख पढ़ें.