जगहों के सुझाव ऑटोकंप्लीट करने की सुविधा

प्लैटफ़ॉर्म चुनें: Android iOS JavaScript वेब सेवा

Android के लिए Places SDK टूल में ऑटोकंप्लीट की सुविधा से, उपयोगकर्ता की खोज क्वेरी के जवाब में जगह के हिसाब से सुझाव दिखाए जाते हैं. उपयोगकर्ता टाइप के तौर पर, ऑटोकंप्लीट सुविधा से कारोबार, पते, प्लस कोड, और पसंदीदा जगहों जैसी जगहों के लिए सुझाव दिखाए जाते हैं.

ऐप्लिकेशन में ऑटोकंप्लीट की सुविधा जोड़ने के लिए, ये तरीके अपनाएं:

ऑटोकंप्लीट विजेट जोड़ना

ऑटोकंप्लीट विजेट, पहले से मौजूद ऑटोकंप्लीट फ़ंक्शन की सुविधा वाला खोज डायलॉग है. जैसे-जैसे उपयोगकर्ता खोज के लिए शब्दों को डालता है, विजेट उन जगहों की सूची दिखाता है जिनके बारे में अनुमान लगाया गया है. जब उपयोगकर्ता किसी आइटम को चुनता है, तो Place इंस्टेंस दिखाया जाता है. इसका इस्तेमाल करके, आपका ऐप्लिकेशन चुनी गई जगह के बारे में जानकारी पाने के लिए इस्तेमाल कर सकता है.

ऐप्लिकेशन में ऑटोकंप्लीट विजेट जोड़ने के दो तरीके हैं:

पहला विकल्प: AutocompleteSupportFragment एम्बेड करना

अपने ऐप्लिकेशन में AutocompleteSupportFragment जोड़ने के लिए, यह तरीका अपनाएं:

  1. अपनी गतिविधि के एक्सएमएल लेआउट में कोई फ़्रैगमेंट जोड़ें.
  2. अपनी गतिविधि या फ़्रैगमेंट में किसी दर्शक को जोड़ें.

किसी गतिविधि में AutocompleteSupportFragment जोड़ें

किसी गतिविधि में AutocompleteSupportFragment जोड़ने के लिए, एक्सएमएल लेआउट में नया फ़्रैगमेंट जोड़ें. उदाहरण के लिए:

<fragment android:id="@+id/autocomplete_fragment"
  android:layout_width="match_parent"
  android:layout_height="wrap_content"
  android:name="com.google.android.libraries.places.widget.AutocompleteSupportFragment"
  />
  • डिफ़ॉल्ट रूप से, फ़्रैगमेंट में कोई बॉर्डर या बैकग्राउंड नहीं है. एक जैसी विज़ुअल दिखाने के लिए, फ़्रैगमेंट को किसी अन्य लेआउट एलिमेंट में नेस्ट करें, जैसे कि CardView.
  • अगर आप अपने-आप पूरा होने वाले फ़्रैगमेंट का इस्तेमाल कर रहे हैं और आपको onActivityResult को बदलना है, तो आपको super.onActivityResult को कॉल करना होगा. ऐसा न करने पर, फ़्रैगमेंट सही तरीके से काम नहीं करेगा.

किसी गतिविधि में PlaceSelectionListener जोड़ें

उपयोगकर्ता के चुने गए विकल्प के हिसाब से, PlaceSelectionListener हैंडल वाली जगह को लौटाता है. नीचे दिया गया कोड फ़्रैगमेंट का रेफ़रंस देने के साथ-साथ AutocompleteSupportFragment में एक पहचानकर्ता जोड़ने का तरीका भी बताता है:

Java


    // Initialize the AutocompleteSupportFragment.
    AutocompleteSupportFragment autocompleteFragment = (AutocompleteSupportFragment)
            getSupportFragmentManager().findFragmentById(R.id.autocomplete_fragment);

    // Specify the types of place data to return.
    autocompleteFragment.setPlaceFields(Arrays.asList(Place.Field.ID, Place.Field.NAME));

    // Set up a PlaceSelectionListener to handle the response.
    autocompleteFragment.setOnPlaceSelectedListener(new PlaceSelectionListener() {
        @Override
        public void onPlaceSelected(@NonNull Place place) {
            // TODO: Get info about the selected place.
            Log.i(TAG, "Place: " + place.getName() + ", " + place.getId());
        }


        @Override
        public void onError(@NonNull Status status) {
            // TODO: Handle the error.
            Log.i(TAG, "An error occurred: " + status);
        }
    });

      

Kotlin


    // Initialize the AutocompleteSupportFragment.
    val autocompleteFragment =
        supportFragmentManager.findFragmentById(R.id.autocomplete_fragment)
                as AutocompleteSupportFragment

    // Specify the types of place data to return.
    autocompleteFragment.setPlaceFields(listOf(Place.Field.ID, Place.Field.NAME))

    // Set up a PlaceSelectionListener to handle the response.
    autocompleteFragment.setOnPlaceSelectedListener(object : PlaceSelectionListener {
        override fun onPlaceSelected(place: Place) {
            // TODO: Get info about the selected place.
            Log.i(TAG, "Place: ${place.name}, ${place.id}")
        }

        override fun onError(status: Status) {
            // TODO: Handle the error.
            Log.i(TAG, "An error occurred: $status")
        }
    })

      

विकल्प 2: ऑटोकंप्लीट गतिविधि लॉन्च करने के लिए, इंटेंट का इस्तेमाल करना

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

इंटेंट का इस्तेमाल करके अपने-आप पूरा होने वाले विजेट को लॉन्च करने के लिए, यह तरीका अपनाएं:

  1. मनचाहे Autocomplete मोड को पास करने वाला एक इंटेंट बनाने के लिए Autocomplete.IntentBuilder का इस्तेमाल करें.
  2. गतिविधि के नतीजे दिखाने वाला लॉन्चर तय करेंregisterForActivityResult. इसका इस्तेमाल इंटेंट को लॉन्च करने और उपयोगकर्ता की चुनी हुई जगह के अनुमान को मैनेज करने के लिए किया जा सकता है.

ऑटोकंप्लीट इंटेंट बनाएं

नीचे दिए गए उदाहरण में, इंटेंट के तौर पर ऑटोकंप्लीट विजेट लॉन्च करने के इंटेंट को बनाने के लिए Autocomplete.IntentBuilder का इस्तेमाल किया गया है:

Java



    // Set the fields to specify which types of place data to
    // return after the user has made a selection.
    List<Place.Field> fields = Arrays.asList(Place.Field.ID, Place.Field.NAME);

    // Start the autocomplete intent.
    Intent intent = new Autocomplete.IntentBuilder(AutocompleteActivityMode.FULLSCREEN, fields)
            .build(this);
    startAutocomplete.launch(intent);

      

Kotlin



    // Set the fields to specify which types of place data to
    // return after the user has made a selection.
    val fields = listOf(Place.Field.ID, Place.Field.NAME)

    // Start the autocomplete intent.
    val intent = Autocomplete.IntentBuilder(AutocompleteActivityMode.FULLSCREEN, fields)
        .build(this)
    startAutocomplete.launch(intent)

      

ऑटोकंप्लीट विजेट लॉन्च करने के इंटेंट का इस्तेमाल करते समय, ओवरले या फ़ुल-स्क्रीन डिसप्ले मोड में से चुना जा सकता है. नीचे दिए गए स्क्रीनशॉट में, हर डिसप्ले मोड को क्रम से दिखाया गया है:

ओवरले मोड में दिखाए जाने पर, ऑटोकंप्लीट विजेट, कॉलिंग यूज़र इंटरफ़ेस (यूआई) पर सुपरइंपोज़्ड दिखता है.
पहली इमेज: विजेट को ओवरले मोड में अपने-आप पूरा करें
फ़ुलस्क्रीन मोड में दिखाने पर, ऑटोकंप्लीट विजेट पूरी स्क्रीन पर दिख जाता है.
दूसरी इमेज: फ़ुलस्क्रीन मोड में, ऑटोकंप्लीट विजेट

इंटेंट के नतीजे के लिए कॉलबैक रजिस्टर करें

जब उपयोगकर्ता ने कोई जगह चुनी हो, तो इसकी सूचना पाने के लिए एक registerForActivityResult() लॉन्चर बनाएं, जो गतिविधि को लॉन्च करता है. साथ ही, नतीजे को उसी तरह मैनेज करता है जैसा कि नीचे दिए गए उदाहरण में दिखाया गया है. अगर उपयोगकर्ता ने किसी सुझाव को चुना है, तो वह नतीजे के ऑब्जेक्ट में शामिल इंटेंट के मुताबिक भेजा जाएगा. इंटेंट Autocomplete.IntentBuilder से बनाया गया है, इसलिए मैथडAutocomplete.getPlaceFromIntent() इसकी मदद से प्लेस ऑब्जेक्ट निकाल सकता है.

Java


private final ActivityResultLauncher<Intent> startAutocomplete = registerForActivityResult(
        new ActivityResultContracts.StartActivityForResult(),
        result -> {
            if (result.getResultCode() == Activity.RESULT_OK) {
                Intent intent = result.getData();
                if (intent != null) {
                    Place place = Autocomplete.getPlaceFromIntent(intent);
                    Log.i(TAG, "Place: ${place.getName()}, ${place.getId()}");
                }
            } else if (result.getResultCode() == Activity.RESULT_CANCELED) {
                // The user canceled the operation.
                Log.i(TAG, "User canceled autocomplete");
            }
        });

      

Kotlin


private val startAutocomplete =
    registerForActivityResult(ActivityResultContracts.StartActivityForResult()) { result: ActivityResult ->
        if (result.resultCode == Activity.RESULT_OK) {
            val intent = result.data
            if (intent != null) {
                val place = Autocomplete.getPlaceFromIntent(intent)
                Log.i(
                    TAG, "Place: ${place.name}, ${place.id}"
                )
            }
        } else if (result.resultCode == Activity.RESULT_CANCELED) {
            // The user canceled the operation.
            Log.i(TAG, "User canceled autocomplete")
        }
    }

      

प्रोग्राम के हिसाब से, जगहों के बारे में सुझाव पाना

ऑटोकंप्लीट विजेट से मिलने वाले यूज़र इंटरफ़ेस (यूआई) के विकल्प के तौर पर, कस्टम खोज यूज़र इंटरफ़ेस (यूआई) बनाया जा सकता है. ऐसा करने के लिए, आपके ऐप्लिकेशन को प्रोग्राम के ज़रिए जगहों के बारे में अनुमान लगाना चाहिए. आपके ऐप्लिकेशन को, यहां दिए गए पैरामीटर से FindAutocompletePredictionsRequest ऑब्जेक्ट को पास करते समय, PlacesClient.findAutocompletePredictions() को कॉल करके, ऑटोकंप्लीट की सुविधा वाले एपीआई से जगह के अनुमानित नाम और/या पते की सूची मिल सकती है:

  • ज़रूरी है: query स्ट्रिंग, जिसमें उपयोगकर्ता ने टाइप किया गया टेक्स्ट शामिल होता है.
  • सुझाया गया: एक AutocompleteSessionToken, जो किसी बिलिंग के मकसद से, किसी उपयोगकर्ता की क्वेरी और चुने गए चरणों को अलग-अलग सेशन में बांटता है. सेशन की शुरुआत तब होती है, जब उपयोगकर्ता क्वेरी लिखना शुरू करता है. साथ ही, किसी जगह को चुनने पर यह खत्म होता है.
  • सुझाया गया: एक RectangularBounds ऑब्जेक्ट, जो अक्षांश और देशांतर की जानकारी देता है, ताकि बताए गए इलाके के लिए नतीजों को सीमित किया जा सके.
  • ज़रूरी नहीं: एक या दो अक्षर वाले देश के कोड (ISO 3166-1 Alpha-2) होते हैं. यह कोड उन देशों या देशों की जानकारी देता है जहां नतीजों पर पाबंदी लगाई जानी चाहिए.
  • ज़रूरी नहीं: एक TypeFilter. इसका इस्तेमाल करके, नतीजों को बताई गई जगह तक सीमित किया जा सकता है. नीचे दिए गए जगह के फ़ॉर्मैट इस्तेमाल किए जा सकते हैं:

    • TypeFilter.GEOCODE – कारोबारों के बजाय, सिर्फ़ जियोकोडिंग के नतीजे दिखाता है. इस अनुरोध का इस्तेमाल, ऐसे नतीजों की पहचान करने के लिए करें जहां हो सकता है कि यह शहर पहले जैसा न हो.
    • TypeFilter.ADDRESS – सटीक पते के साथ सिर्फ़ अपने-आप पूरा होने वाले नतीजे दिखाता है. इस तरीके का इस्तेमाल तब करें, जब आपको पता हो कि उपयोगकर्ता पूरी तरह से बताया गया पता खोज रहा है.
    • TypeFilter.ESTABLISHMENT – सिर्फ़ ऐसी जगहें दिखाता है जो कारोबार हैं.
    • TypeFilter.REGIONS – यहां सिर्फ़ इस तरह की जगहों से मेल खाने वाली जगहें दिखाता है:

    • LOCALITY

    • SUBLOCALITY

    • POSTAL_CODE

    • COUNTRY

    • ADMINISTRATIVE_AREA_LEVEL_1

    • ADMINISTRATIVE_AREA_LEVEL_2

    • TypeFilter.CITIES – सिर्फ़ LOCALITY या ADMINISTRATIVE_AREA_LEVEL_3 से मिलते-जुलते नतीजे दिखाता है.

  • ज़रूरी नहीं: LatLng, जो अनुरोध भेजने की जगह की जानकारी देता है. setOrigin() को कॉल करने पर, यह सेवा बताए गए ऑरिजिन से मीटर (distanceMeters) में दूरी दिखाती है. अपने-आप दिए गए इस अनुमान के लिए, यह पूरी जानकारी दिखाती है.

अलग-अलग तरह की जगह के बारे में जानकारी पाने के लिए, अलग-अलग तरह की जगहों को जोड़ने की गाइड देखें.

नीचे दिए गए उदाहरण में PlacesClient.findAutocompletePredictions() को पूरा कॉल दिखाया गया है.

Java


    // Create a new token for the autocomplete session. Pass this to FindAutocompletePredictionsRequest,
    // and once again when the user makes a selection (for example when calling fetchPlace()).
    AutocompleteSessionToken token = AutocompleteSessionToken.newInstance();

    // Create a RectangularBounds object.
    RectangularBounds bounds = RectangularBounds.newInstance(
            new LatLng(-33.880490, 151.184363),
            new LatLng(-33.858754, 151.229596));
    // Use the builder to create a FindAutocompletePredictionsRequest.
    FindAutocompletePredictionsRequest request = FindAutocompletePredictionsRequest.builder()
            // Call either setLocationBias() OR setLocationRestriction().
            .setLocationBias(bounds)
            //.setLocationRestriction(bounds)
            .setOrigin(new LatLng(-33.8749937, 151.2041382))
            .setCountries("AU", "NZ")
            .setTypesFilter(Arrays.asList(PlaceTypes.ADDRESS))
            .setSessionToken(token)
            .setQuery(query)
            .build();

    placesClient.findAutocompletePredictions(request).addOnSuccessListener((response) -> {
        for (AutocompletePrediction prediction : response.getAutocompletePredictions()) {
            Log.i(TAG, prediction.getPlaceId());
            Log.i(TAG, prediction.getPrimaryText(null).toString());
        }
    }).addOnFailureListener((exception) -> {
        if (exception instanceof ApiException) {
            ApiException apiException = (ApiException) exception;
            Log.e(TAG, "Place not found: " + apiException.getStatusCode());
        }
    });

      

Kotlin


    // Create a new token for the autocomplete session. Pass this to FindAutocompletePredictionsRequest,
    // and once again when the user makes a selection (for example when calling fetchPlace()).
    val token = AutocompleteSessionToken.newInstance()

    // Create a RectangularBounds object.
    val bounds = RectangularBounds.newInstance(
        LatLng(-33.880490, 151.184363),
        LatLng(-33.858754, 151.229596)
    )
    // Use the builder to create a FindAutocompletePredictionsRequest.
    val request =
        FindAutocompletePredictionsRequest.builder()
            // Call either setLocationBias() OR setLocationRestriction().
            .setLocationBias(bounds)
            //.setLocationRestriction(bounds)
            .setOrigin(LatLng(-33.8749937, 151.2041382))
            .setCountries("AU", "NZ")
            .setTypesFilter(listOf(PlaceTypes.ADDRESS))
            .setSessionToken(token)
            .setQuery(query)
            .build()
    placesClient.findAutocompletePredictions(request)
        .addOnSuccessListener { response: FindAutocompletePredictionsResponse ->
            for (prediction in response.autocompletePredictions) {
                Log.i(TAG, prediction.placeId)
                Log.i(TAG, prediction.getPrimaryText(null).toString())
            }
        }.addOnFailureListener { exception: Exception? ->
            if (exception is ApiException) {
                Log.e(TAG, "Place not found: ${exception.statusCode}")
            }
        }

      

एपीआई, Task में FindAutocompletePredictionsResponse दिखता है. FindAutocompletePredictionsResponse में, अनुमानित जगहों के बारे में बताने वाले AutocompletePrediction ऑब्जेक्ट की सूची होती है. अगर क्वेरी और फ़िल्टर के लिए कोई शर्तें पूरी नहीं हैं, तो सूची खाली हो सकती है.

हर अनुमानित जगह के लिए, जगह की जानकारी पाने के लिए आप इन तरीकों से कॉल कर सकते हैं:

  • getFullText(CharacterStyle) जगह के ब्यौरे का पूरा टेक्स्ट दिखाता है. यह प्राइमरी और सेकंडरी टेक्स्ट का कॉम्बिनेशन है. उदाहरण: "एफ़िल टावर, एवेन्यू एंटोले फ़्रांस, पेरिस, फ़्रांस". इसके अलावा, इस तरीके से आप CharacterStyle का इस्तेमाल करके, ब्यौरे के उन सेक्शन को हाइलाइट कर सकते हैं जो खोज के हिसाब से चुने गए हैं. CharacterStyle पैरामीटर ज़रूरी नहीं है. अगर आपको किसी हाइलाइटिंग की ज़रूरत नहीं है, तो इसे शून्य पर सेट कर दें.
  • getPrimaryText(CharacterStyle) जगह का ब्यौरा देने वाला मुख्य टेक्स्ट दिखाता है. यह आम तौर पर जगह का नाम होता है. उदाहरण के लिए: "एफ़िल टावर" और "123 पिट स्ट्रीट".
  • getSecondaryText(CharacterStyle) जगह के ब्यौरे की मुख्य टेक्स्ट दिखाता है. उदाहरण के लिए, ऑटोकंप्लीट की सुविधा से मिलने वाले सुझाव दिखाते समय, यह दूसरी लाइन के तौर पर काम आता है. उदाहरण: "Away Anatole France,Paris, France" और "Sydney, New South वेल्स".
  • getPlaceId() अनुमानित जगह का प्लेस आईडी दिखाता है. प्लेस आईडी एक टेक्स्ट आइडेंटिफ़ायर है, जो खास तौर पर किसी जगह की पहचान करता है. इसका इस्तेमाल करके, Place ऑब्जेक्ट को बाद में फिर से पाने के लिए इस्तेमाल किया जा सकता है. Android के लिए Places SDK टूल में, जगह के आईडी के बारे में ज़्यादा जानकारी के लिए जगह की जानकारी देखें. जगह के आईडी के बारे में सामान्य जानकारी के लिए, जगह के आईडी की खास जानकारी देखें.
  • getPlaceTypes() इस जगह से जुड़ी जगहों की सूची दिखाता है.
  • getDistanceMeters() इससे, इस जगह के बीच की दूरी और अनुरोध में बताए गए ऑरिजिन में, मीटर में सीधी रेखा दिखती है.

सेशन के टोकन

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

Android के लिए Places SDK टूल, AutocompleteSessionToken का इस्तेमाल करके हर सेशन की पहचान करता है. हर नए सेशन की शुरुआत में, आपके ऐप्लिकेशन को एक नया सेशन टोकन पास करना होगा. इसके बाद, उसी टोकन के साथ प्लेस आईडी के साथ पास करना होगा. इसके बाद, fetchPlace() को कॉल करना होगा, ताकि उपयोगकर्ता ने जिस जगह को चुना था उसकी जगह की जानकारी फिर से मिल सके.

सेशन टोकन के बारे में ज़्यादा जानें.

ऑटोकंप्लीट की सुविधा से मिलने वाले नतीजों पर पाबंदी लगाएं

ऑटोकंप्लीट की सुविधा से मिलने वाले नतीजों को किसी खास इलाके में सीमित किया जा सकता है और/या नतीजों को एक या एक से ज़्यादा जगहों के हिसाब से फ़िल्टर किया जा सकता है. ज़्यादा से ज़्यादा पांच देशों के लिए भी ऐसा किया जा सकता है. आप इन कंस्ट्रेंट को ऑटोकंप्लीट की गतिविधि, AutocompleteSupportFragment, और प्रोग्रामैटिक ऑटोकंप्लीट एपीआई पर लागू कर सकते हैं.

सीमित नतीजों के लिए, ये काम करें:

  • अगर नतीजे तय किए गए क्षेत्र में हैं, तो प्राथमिकता देने के लिए, setLocationBias() पर कॉल करें (तय किए गए इलाके के बाहर के कुछ नतीजे अब भी दिखाए जा सकते हैं).
  • अगर किसी इलाके के नतीजे सिर्फ़ दिखाने हैं, तो setLocationRestriction() पर कॉल करें (सिर्फ़ तय इलाके में मौजूद नतीजे दिखाए जाएंगे).
  • किसी खास तरह की जगह के मुताबिक नतीजे दिखाने के लिए, setTypesFilter() पर कॉल करें (उदाहरण के लिए, TypeFilter.ADDRESS बताने से सिर्फ़ सटीक पते वाले नतीजे मिलेंगे).
  • ज़्यादा से ज़्यादा पांच देशों में नतीजे दिखाने के लिए, setCountries() को कॉल करें. देशों को दो वर्णों वाले, ISO 3166-1 Alpha-2 के साथ काम करने वाले देश कोड के रूप में पास किया जाना चाहिए.

भेदभाव किसी खास इलाके के नतीजे पर ले जाता है

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

Java


    autocompleteFragment.setLocationBias(RectangularBounds.newInstance(
            new LatLng(-33.880490, 151.184363),
            new LatLng(-33.858754, 151.229596)));

      

Kotlin


    autocompleteFragment.setLocationBias(
        RectangularBounds.newInstance(
            LatLng(-33.880490, 151.184363),
            LatLng(-33.858754, 151.229596)
        )
    )

      

किसी खास क्षेत्र के लिए नतीजे दिखाएं

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

Java


    autocompleteFragment.setLocationRestriction(RectangularBounds.newInstance(
            new LatLng(-33.880490, 151.184363),
            new LatLng(-33.858754, 151.229596)));

      

Kotlin


    autocompleteFragment.setLocationRestriction(
        RectangularBounds.newInstance(
            LatLng(-33.880490, 151.184363),
            LatLng(-33.858754, 151.229596)
        )
    )

      

ध्यान दें: यह पाबंदी सिर्फ़ पूरे रास्तों पर लागू होती है. आयताकार सीमाओं के बाहर दिए गए सिंथेटिक नतीजे उस जगह के आधार पर दिखाए जा सकते हैं जहां जगह की पाबंदी लागू होती है.

जगह के टाइप या टाइप कलेक्शन के हिसाब से नतीजे फ़िल्टर करें

आप ऑटोकंप्लीट की सुविधा से अनुरोध करने पर, नतीजों पर पाबंदी लगा सकते हैं. ऐसा करने से, वे चुनिंदा जगहों पर सिर्फ़ जगहों के प्रकार में टेबल 1, 2, और 3 में दिए गए जगह के प्रकारों या प्रकार संग्रह का इस्तेमाल करने वाला फ़िल्टर तय करें. अगर कुछ भी तय नहीं किया गया है, तो सभी प्रकार दिखाए जाएंगे.

ऑटोकंप्लीट की सुविधा से मिले नतीजों को फ़िल्टर करने के लिए, setTypesFilter() को फ़िल्टर करें.

टाइप या टाइप कलेक्शन फ़िल्टर के बारे में बताने के लिए:

  • setTypesFilter() को कॉल करें. साथ ही, टेबल 1 से पांच टाइप की वैल्यू डालें और जगह के टाइप पर दिखाई गई टेबल 2 की वैल्यू डालें. टाइप की वैल्यू, PlaceTypes में कॉन्सटेंट के आधार पर तय होती हैं.

  • setTypesFilter() को कॉल करें और जगह के प्रकार पर दिखाई गई टेबल 3 से प्रकार का संग्रह तय करें. कलेक्शन की वैल्यू, PlaceTypes में मौजूद कॉन्सटेंट के आधार पर तय की जाती हैं.

    अनुरोध में टेबल 3 से सिर्फ़ एक प्रकार की अनुमति है. अगर आप टेबल 3 से कोई मान तय करते हैं, तो आप टेबल 1 या टेबल 2 से कोई मान तय नहीं कर सकते. ऐसा करने से, कोई गड़बड़ी होती है.

यह कोड उदाहरण, AutocompleteSupportFragment को setTypesFilter() पर कॉल करता है और एक से ज़्यादा टाइप वैल्यू बताता है.

Java


    autocompleteFragment.setTypesFilter(Arrays.asList("landmark", "restaurant", "store"));

      

Kotlin


    autocompleteFragment.setTypesFilter(listOf("landmark", "restaurant", "store"))

      

कोड के इस उदाहरण में AutocompleteSupportFragment पर setTypesFilter() को कॉल करने के बारे में बताया गया है, ताकि यह फ़िल्टर सेट किया जा सके कि किसी टाइप कलेक्शन का इस्तेमाल करके सिर्फ़ सही पते के साथ नतीजे दिखाए जाएं.

Java


    autocompleteFragment.setTypesFilter(Arrays.asList(PlaceTypes.ADDRESS, PlaceTypes.ESTABLISHMENT));

      

Kotlin


    autocompleteFragment.setTypesFilter(listOf(PlaceTypes.ADDRESS))

      

कोड के इस उदाहरण में IntentBuilder पर setTypesFilter() को कॉल करने के बारे में बताया गया है. यह फ़िल्टर सेट करने से, सिर्फ़ सही पते वाले नतीजे मिलते हैं. इसके लिए, टाइप कलेक्शन की जानकारी दी जाती है.

Java


    Intent intent = new Autocomplete.IntentBuilder(
            AutocompleteActivityMode.FULLSCREEN, fields)
            .setTypesFilter(Arrays.asList(PlaceTypes.ADDRESS))
            .build(this);

      

Kotlin


    val intent = Autocomplete.IntentBuilder(AutocompleteActivityMode.FULLSCREEN, fields)
        .setTypesFilter(listOf(PlaceTypes.ADDRESS))
        .build(this)

      

देश के हिसाब से नतीजे फ़िल्टर करें

अपने-आप पूरे होने वाले नतीजों को ज़्यादा से ज़्यादा पांच देशों में फ़िल्टर करने के लिए, setCountries() को कॉल करके देश कोड सेट करें. इसके बाद, फ़िल्टर को किसी फ़्रैगमेंट या इंटेंट पर पास करें. देशों को दो-वर्ण वाले, ISO 3166-1 Alpha-2 के साथ काम करने वाले देश कोड में पास किया जाना चाहिए.

कोड के इस उदाहरण में AutocompleteSupportFragment पर setCountries() को कॉल करने का तरीका बताया गया है, ताकि एक ऐसा फ़िल्टर सेट किया जा सके जो सिर्फ़ कुछ खास देशों में ही नतीजे दिखाता है.

Java


    autocompleteFragment.setCountries("AU", "NZ");

      

Kotlin


    autocompleteFragment.setCountries("AU", "NZ")

      

इस्तेमाल करने की सीमा

अब Android के लिए Places SDK टूल सहित Places एपीआई का इस्तेमाल, हर दिन ज़्यादा से ज़्यादा अनुरोध (क्यूपीडी) तक सीमित नहीं है. हालांकि, इस्तेमाल की ये सीमाएं अब भी लागू होती हैं:

  • रेट की सीमा 100 अनुरोध प्रति सेकंड (क्यूपीएस) है. इसकी गिनती एक ही प्रोजेक्ट के क्रेडेंशियल का इस्तेमाल करके, सभी ऐप्लिकेशन के लिए क्लाइंट-साइड और सर्वर-साइड पर किए गए अनुरोधों के योग से की जाती है.

अपने ऐप्लिकेशन में एट्रिब्यूशन दिखाएं

  • अगर आपका ऐप्लिकेशन प्रोग्राम के हिसाब से अपने-आप पूरा होने की सुविधा का इस्तेमाल करता है, तो आपके यूज़र इंटरफ़ेस (यूआई) को 'Google की ओर से' एट्रिब्यूशन दिखाया जाना चाहिए या Google के ब्रैंड वाले मैप में दिखना चाहिए.
  • अगर आपका ऐप्लिकेशन अपने-आप पूरा होने वाले विजेट का इस्तेमाल करता है, तो आपको कुछ और करने की ज़रूरत नहीं है (ज़रूरी एट्रिब्यूशन डिफ़ॉल्ट रूप से दिखता है).
  • आईडी के आधार पर जगह की जानकारी पाने के बाद, अगर आप जगह की ज़्यादा जानकारी फिर से हासिल करते और दिखाते हैं, तो आपको तीसरे पक्ष के एट्रिब्यूशन भी दिखाने होंगे.

ज़्यादा जानकारी के लिए, एट्रिब्यूशन से जुड़े दस्तावेज़ देखें.

जगह के लिए, ऑटोकंप्लीट सुविधा का ऑप्टिमाइज़ेशन

इस सेक्शन में, जगह के हिसाब से ऑटोकंप्लीट की सुविधा से ज़्यादा से ज़्यादा फ़ायदा पाने में, सबसे सही तरीकों के बारे में बताया गया है.

यहां इससे जुड़े कुछ सामान्य दिशा-निर्देश दिए गए हैं:

  • काम करने वाले यूज़र इंटरफ़ेस को बनाने का सबसे तेज़ तरीका, Maps JavaScript API ऑटोकंप्लीट विजेट, Android के लिए Places SDK टूल, ऑटोकंप्लीट विजेट या iOS के लिए Places SDK टूल ऑटोकंप्लीट यूज़र इंटरफ़ेस (यूआई) कंट्रोल का इस्तेमाल करना है
  • शुरू से ही, ज़रूरी ऑटोकंप्लीट की सुविधा वाले डेटा फ़ील्ड को समझना.
  • जगह की जानकारी के लिए मापदंड तय करना और जगह की जानकारी पर पाबंदी लगाने वाले फ़ील्ड ज़रूरी नहीं हैं. हालांकि, इनका अपने-आप पूरा होने वाले परफ़ॉर्मेंस पर बहुत ज़्यादा असर पड़ सकता है.
  • गड़बड़ी को ठीक करने के लिए यह पक्का करें कि आपका ऐप्लिकेशन सही तरीके से काम न करे. ऐसा तब करें, जब एपीआई कोई गड़बड़ी दिखाए.
  • पक्का करें कि आपका ऐप्लिकेशन तब हैंडल हो, जब कोई विकल्प न चुना गया हो. साथ ही, उपयोगकर्ताओं को जारी रखने का तरीका भी बताया गया हो.

लागत ऑप्टिमाइज़ेशन के सबसे सही तरीके

कीमत का बुनियादी ऑप्टिमाइज़ेशन

जगह के लिए ऑटोकंप्लीट की सुविधा इस्तेमाल करने की लागत को ऑप्टिमाइज़ करने के लिए, जगह की जानकारी और ऑटोकंप्लीट की सुविधा वाले विजेट में फ़ील्ड मास्क का इस्तेमाल करें. इससे, सिर्फ़ जगह की जानकारी के डेटा फ़ील्ड दिए जा सकेंगे.

लागत का बेहतर ऑप्टिमाइज़ेशन

हर अनुरोध की कीमत को ऐक्सेस करने के लिए, प्लेसमार्क ऑटोकंप्लीट की सुविधा को प्रोग्राम के हिसाब से लागू करें. साथ ही, जगह की जानकारी के बजाय, चुनी गई जगह के बारे में जियोकोडिंग एपीआई के नतीजे पाने का अनुरोध करें. अगर यहां दी गई दोनों शर्तें पूरी होती हैं, तो जियोकोडिंग एपीआई के साथ जोड़े गए हर अनुरोध की कीमत, हर सेशन (सेशन-आधारित) की कीमत की तुलना में ज़्यादा किफ़ायती होती है:

  • अगर आपको उपयोगकर्ता की चुनी हुई जगह के सिर्फ़ अक्षांश/देशांतर या पते की ज़रूरत है, तो जियोकोडिंग एपीआई यह जानकारी, जगह की जानकारी से ज़्यादा कॉल के लिए डिलीवर करता है.
  • अगर उपयोगकर्ता, ऑटोकंप्लीट की सुविधा वाले अनुमानित चार अनुरोधों या उससे कम अनुरोधों के औसत के अंदर, ऑटोकंप्लीट की सुविधा से मिलने वाले सुझावों का इस्तेमाल करते हैं, तो हर अनुरोध की कीमत, हर सेशन की कीमत के मुकाबले ज़्यादा किफ़ायती हो सकती है.
अपनी ज़रूरतों के हिसाब से, 'जगह की जानकारी अपने-आप पूरा होना' विकल्प चुनने में मदद पाने के लिए, वह टैब चुनें जो आपके सवाल के जवाब से जुड़ा है.

आपके आवेदन में चुने गए अनुमान के पते और अक्षांश/देशांतर के अलावा, किसी और जानकारी की ज़रूरत है?

हां, ज़्यादा जानकारी की ज़रूरत है

जगह की जानकारी के साथ सेशन पर आधारित जगह की जानकारी के अपने-आप पूरा होने की सुविधा का इस्तेमाल करें.
आपके आवेदन में जगह का नाम, कारोबार की स्थिति या खुलने के समय जैसी जानकारी की ज़रूरत होती है. इसलिए, जगह की जानकारी के अपने-आप लागू होने की प्रोसेस को, सेशन टोकन का इस्तेमाल करना चाहिए (या JavaScript, Android या iOS विजेट) का इस्तेमाल करें. कुल लागत 0.017 हर सेशन और लागू किए गए जगहों के डेटा SKU की वजह से होती है}}

विजेट लागू करना
सेशन मैनेजमेंट, JavaScript, Android या iOS विजेट में अपने-आप पहले से मौजूद होता है. इसमें, जगह के बारे में अपने-आप पूरे होने वाले अनुरोध और चुने गए सुझाव के लिए, जगह की जानकारी का अनुरोध भी शामिल हैं. fields पैरामीटर की जानकारी देना न भूलें, ताकि यह पक्का हो सके कि आपने सिर्फ़ वही फ़ील्ड डेटा फ़ील्ड का अनुरोध किया हो जिसकी आपको ज़रूरत है.

प्रोग्रामैटिक तरीके से लागू करना
जगहों के अपने-आप पूरे होने के अनुरोधों के साथ, सेशन टोकन का इस्तेमाल करें. चुने गए सुझाव के बारे में जगह की जानकारी का अनुरोध करते समय, ये पैरामीटर शामिल करें:

  1. जगह के बारे में अपने-आप मिलने वाले जवाब की जगह का आईडी
  2. जगह के लिए ऑटोकंप्लीट करने के अनुरोध में इस्तेमाल किया गया सेशन टोकन
  3. अपनी ज़रूरत के हिसाब से जगह की जानकारी के डेटा फ़ील्ड के बारे में बताने वाला fields पैरामीटर

नहीं, सिर्फ़ पता और जगह की जानकारी चाहिए

आपके स्थान के लिए ऑटोकंप्लीट की सुविधा के इस्तेमाल के आधार पर, जगह की जानकारी की तुलना में जियोकोडिंग एपीआई, जगह के हिसाब से ज़्यादा किफ़ायती विकल्प हो सकता है. हर ऐप्लिकेशन के अपने-आप पूरा होने की क्षमता, इस बात पर निर्भर करती है कि उपयोगकर्ता क्या डाल रहे हैं, ऐप्लिकेशन कहां इस्तेमाल किया जा रहा है, और परफ़ॉर्मेंस ऑप्टिमाइज़ेशन के सबसे सही तरीके लागू किए गए हैं या नहीं.

निम्न सवाल का जवाब देने के लिए, अपने ऐप्लिकेशन में कोई स्थान ऑटोकंप्लीट सुविधा की मदद से मिलने वाला सुझाव चुनने से पहले, यह पता लगाएं कि औसतन कितने उपयोगकर्ता टाइप करते हैं.

क्या आपके उपयोगकर्ता औसतन चार या उससे कम अनुरोधों के लिए, 'जगह की जानकारी अपने-आप पूरा होना' का अनुमान चुनते हैं?

हां

सेशन के टोकन के बिना, जगह की जानकारी को ऑटोकंप्लीट करने की सुविधा लागू करें. साथ ही, चुनी गई जगह के अनुमान के लिए, जियोकोडिंग एपीआई को कॉल करें.
जियोकोडिंग एपीआई, हर अनुरोध के लिए पते और अक्षांश/देशांतर निर्देशांक को 0.005 डॉलर पर डिलीवर करता है. चार जगह के अपने-आप पूरा होने की सुविधा - हर अनुरोध के लिए, अनुरोध के लिए 0.01132 डॉलर खर्च होते हैं. इसलिए, चुने गए जगह के अनुमान के लिए, जियोकोडिंग एपीआई के चार अनुरोधों की कुल कीमत 0.01632 डॉलर होगी. यह संख्या, हर सेशन के लिए 0.017 डॉलर के ऑटोकंप्लीट की सुविधा से कम होती है.1

परफ़ॉर्मेंस के सबसे सही तरीके अपनाएं, ताकि आपके उपयोगकर्ताओं को यह अनुमान लगाने में मदद मिले कि वे कुछ ही वर्णों में खोज कर रहे हैं.

नहीं

जगह की जानकारी के साथ सेशन पर आधारित जगह की जानकारी के अपने-आप पूरा होने की सुविधा का इस्तेमाल करें.
उपयोगकर्ता, जगह के हिसाब से अपने-आप पूरा होने का अनुमान लगाने से पहले, जितनी बार आपके अनुरोध स्वीकार करेंगे उनकी औसत संख्या, हर सेशन की कीमत के अनुमान से ज़्यादा होगी. इसलिए, जगह की जानकारी के अपने-आप पूरे होने के अनुरोधों और उससे जुड़े स्पेस की जानकारी के अनुरोध के लिए, सेशन टोकन का इस्तेमाल किया जाना चाहिए. इसमें कुल कीमत 0.017 डॉलर हर सेशन होगी.1

विजेट लागू करना
सेशन मैनेजमेंट, JavaScript, Android या iOS विजेट में अपने-आप पहले से मौजूद होता है. इसमें, जगह के बारे में अपने-आप पूरे होने वाले अनुरोध और चुने गए सुझाव के लिए, जगह की जानकारी का अनुरोध भी शामिल हैं. fields पैरामीटर डालने के लिए, बेसिक डेटा फ़ील्ड का अनुरोध करना न भूलें.

प्रोग्रामैटिक तरीके से लागू करना
जगहों के अपने-आप पूरे होने के अनुरोधों के साथ, सेशन टोकन का इस्तेमाल करें. चुने गए सुझाव के बारे में जगह की जानकारी का अनुरोध करते समय, ये पैरामीटर शामिल करें:

  1. जगह के बारे में अपने-आप मिलने वाले जवाब की जगह का आईडी
  2. जगह के लिए ऑटोकंप्लीट करने के अनुरोध में इस्तेमाल किया गया सेशन टोकन
  3. बुनियादी डेटा फ़ील्ड के बारे में बताने वाला fields पैरामीटर, जैसे कि पता और ज्यामिति

जगह के बारे में जानकारी अपने-आप मिलने के अनुरोध में देरी करें
उपयोगकर्ता के पहले तीन या चार वर्ण टाइप करने तक, 'जगह की जानकारी अपने-आप पूरा होने' का अनुरोध करने जैसी देरी को लागू किया जा सकता है. उदाहरण के लिए, उपयोगकर्ता के तीसरे वर्ण का टाइप करने के बाद हर वर्ण के लिए 'जगह की जानकारी अपने-आप पूरा होने' का अनुरोध करने का मतलब है कि अगर उपयोगकर्ता सात वर्ण टाइप करता है, तो वह सुझाव देता है जिसके लिए आप एक जियोकोडिंग एपीआई अनुरोध करते हैं, कुल लागत 0.01632 (4 * 0.00283 ऑटोकंप्लीट प्रति अनुरोध + 0.005 जियोकोडिंग) होगी.1

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

परफ़ॉर्मेंस करने के सबसे सही तरीके अपनाएं, ताकि आपके उपयोगकर्ताओं को यह अनुमान लगाने में मदद मिले कि वे कुछ ही वर्णों में खोज रहे हैं.


  1. यहां कीमतें डॉलर में दी गई हैं. कीमत की पूरी जानकारी के लिए, कृपया Google Maps Platform का बिलिंग पेज देखें.

परफ़ॉर्मेंस के सबसे सही तरीके

निम्न दिशा-निर्देश स्थान ऑटोकंप्लीट परफ़ॉर्मेंस को ऑप्टिमाइज़ करने के तरीके बताते हैं:

  • जगहों के अपने-आप पूरा होने की सुविधा के लिए, देश से जुड़ी पाबंदियां लागू करें. साथ ही, जगह की जानकारी से जुड़े सुझाव और प्रोग्राम के हिसाब से, अपने-आप लागू होने वाली भाषा को जोड़ें. विजेट की मदद से, भाषा बदलने की ज़रूरत नहीं होती, क्योंकि वे उपयोगकर्ता के ब्राउज़र या मोबाइल डिवाइस से भाषा की पसंद को चुनते हैं.
  • अगर स्थान ऑटोकंप्लीट सुविधा के साथ मैप भी है, तो आप मैप व्यूपोर्ट के हिसाब से जगह की जानकारी का पता लगा सकते हैं.
  • जब कोई उपयोगकर्ता अपने-आप मिलने वाले सुझावों में से किसी एक को नहीं चुनता है, तो आम तौर पर ऐसा इसलिए होता है, क्योंकि उनमें से कोई भी अनुमान मनचाहे नतीजे के तौर पर नहीं दिखता. ज़्यादा काम के नतीजे पाने के लिए, मूल उपयोगकर्ता के इनपुट का फिर से इस्तेमाल किया जा सकता है:
    • अगर आपको लगता है कि उपयोगकर्ता सिर्फ़ पते की जानकारी डाले, तो जियोकोडिंग एपीआई पर भेजे जाने वाले कॉल में मूल उपयोगकर्ता के इनपुट का फिर से इस्तेमाल करें.
    • अगर आपको लगता है कि उपयोगकर्ता किसी खास जगह के बारे में खोजने के लिए, नाम या पते का इस्तेमाल कर सकता है, तो इसके लिए, जगह खोजने का अनुरोध करें विकल्प का इस्तेमाल करें. अगर नतीजे किसी खास इलाके के लिए ही हों, तो जगह के हिसाब से भेदभाव का इस्तेमाल करें.
    अन्य स्थितियों में भी, जियोकोडिंग एपीआई का इस्तेमाल करना बेहतर होता है:
    • उपयोगकर्ता उन देशों में, जहां अपने-आप पूरा होने की सुविधा देने वाले पतों पर काम करने की सुविधा उपलब्ध नहीं है, उन देशों में उप-नगरीय पतों का इस्तेमाल नहीं किया जा सकता. जैसे: चेकिया, एस्टोनिया, और लिथुआनिया. उदाहरण के लिए, चेक के पते "Stroupeżnického 3191/17" की वजह से, जगह के बारे में ऑटोकंप्लीट की सुविधा में, अनुमान के आधार पर कुछ जानकारी दी जाती है.
    • उपयोगकर्ता न्यूयॉर्क शहर के काओआई द्वीप पर "23-30 29वीं स्ट्रीट, क्वींस" या "47-380 कमेमेहा ह्वे, कनेयो" जैसे सड़क-सेगमेंट प्रीफ़िक्स से पते डालते हैं.

समस्या हल करना

हालांकि, कई तरह की गड़बड़ियां हो सकती हैं, लेकिन आपके ऐप्लिकेशन को ज़्यादातर ऐसी गड़बड़ियां हो सकती हैं जो कॉन्फ़िगरेशन की गड़बड़ियों की वजह से होती हैं. उदाहरण के लिए, गलत एपीआई कुंजी का इस्तेमाल किया गया था या एपीआई कुंजी गलत तरीके से कॉन्फ़िगर की गई थी या फिर कोटा से जुड़ी गड़बड़ियां हैं (आपका ऐप्लिकेशन कोटा से ज़्यादा हो गया है). कोटा के बारे में ज़्यादा जानकारी के लिए, इस्तेमाल की सीमाएं देखें.

ऑटोकंप्लीट की सुविधा के कंट्रोल के इस्तेमाल में होने वाली गड़बड़ियां onActivityResult() कॉलबैक में दिखती हैं. नतीजे का स्टेटस मैसेज पाने के लिए, Autocomplete.getStatus() पर कॉल करें.