ऑटोकंप्लीट (नया)

अपने-आप पूरा होने वाला टेक्स्ट (नया) सुविधा, किसी अनुरोध के जवाब में जगह के सुझाव दिखाती है. इस अनुरोध में, टेक्स्ट खोज स्ट्रिंग और खोज के लिए तय किए गए इलाके की जानकारी शामिल होती है. ऑटोकंप्लीट की सुविधा, इनपुट के पूरे शब्दों और सबस्ट्रिंग से मैच कर सकती है. इससे जगहों के नाम, पते, और प्लस कोड का पता चलता है. आपका ऐप्लिकेशन, उपयोगकर्ता के टाइप करते ही क्वेरी भेज सकता है, ताकि जगह और क्वेरी के अनुमान तुरंत दिए जा सकें.

उदाहरण के लिए, आपने ऑटोमैटिक भरने की सुविधा को कॉल किया है. इसके लिए, आपने "सिसिलियन पिज़" जैसी किसी स्ट्रिंग का इस्तेमाल किया है. साथ ही, खोज के लिए सिर्फ़ सैन फ़्रांसिस्को, कैलिफ़ोर्निया को चुना है. इसके बाद, जवाब में जगह के उन सुझावों की सूची दिखती है जो खोज स्ट्रिंग और खोज के इलाके से मेल खाते हैं. जैसे, "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) जगह की जानकारी का पूरा टेक्स्ट दिखाता है. यह प्राइमरी और सेकंडरी टेक्स्ट का कॉम्बिनेशन है. उदाहरण: "Eiffel Tower, Avenue Anatole France, Paris, France". इसके अलावा, इस तरीके से खोज के हिसाब से मैच होने वाले ब्यौरे के सेक्शन को हाइलाइट किया जा सकता है. इसके लिए, 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() मेथड को कॉल करें.

• देश

  सिर्फ़ उन देशों की सूची में शामिल नतीजे शामिल करें जिनके लिए खोज की गई है. यह सूची, ccTLD ("टॉप-लेवल डोमेन") के ज़्यादा से ज़्यादा 15 दो वर्णों वाली वैल्यू की सूची के तौर पर दी गई है. अगर इस एट्रिब्यूट को शामिल नहीं किया जाता है, तो जवाब पर कोई पाबंदी नहीं लगाई जाती. उदाहरण के लिए, जर्मनी और फ़्रांस तक क्षेत्रों को सीमित करने के लिए:

  अगर आपने 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 ("टॉप-लेवल डोमेन") के तौर पर दो वर्णों की वैल्यू के तौर पर दिखाया जाता है. ज़्यादातर ccTLD कोड, ISO 3166-1 कोड से मिलते-जुलते होते हैं. हालांकि, कुछ कोड अलग होते हैं. उदाहरण के लिए, यूनाइटेड किंगडम का ccTLD "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" टाइप के कारोबारों के नतीजों पर पाबंदी लगाने के लिए, प्राइमरी टाइप पैरामीटर का इस्तेमाल किया गया है:

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 का लोगो और एट्रिब्यूशन दिखाना लेख पढ़ें.