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

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

उदाहरण के लिए, आपने ऐसी स्ट्रिंग का इस्तेमाल करके ऑटोकंप्लीट की सुविधा को कॉल किया है जिसमें उपयोगकर्ता का आंशिक इनपुट "Sicilian piz" होता है. इसकी मदद से खोज के लिए जगह की जानकारी सिर्फ़ सैन फ़्रांसिस्को, कनाडा में दी जाती है. जवाब में खोज स्ट्रिंग और खोज क्षेत्र से मेल खाने वाले जगह के अनुमानों की सूची शामिल होती है, जैसे कि "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 फ़्रांस, पेरिस, फ़्रांस" और "सिडनी, न्यू साउथ वेल्स".
  • 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 और 50000.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) है, जबकि इसका ISO 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 Maps होना चाहिए. जब मैप के बिना ऑटोकंप्लीट (नई) सेवा से सुझाव दिखाए जाते हैं, तो आपको खोज फ़ील्ड/नतीजों में Google लोगो दिखाना चाहिए. ज़्यादा जानकारी के लिए, Google का लोगो और एट्रिब्यूशन दिखाना देखें.