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

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

अपने ऐप्लिकेशन में अपने-आप भरने की सुविधा को इन तरीकों से जोड़ा जा सकता है:

• ऑटोकंप्लीट विजेट जोड़ें, ताकि डेवलपमेंट में लगने वाला समय बचाया जा सके. साथ ही, यह पक्का किया जा सके कि सभी लोगों को एक जैसा अनुभव मिले.
• उपयोगकर्ता को उसकी पसंद के मुताबिक अनुभव देने के लिए, जगह के अनुमानों को प्रोग्राम के हिसाब से पाएं.

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

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

अपने ऐप्लिकेशन में अपने-आप पूरा होने वाला विजेट जोड़ने के लिए, आपके पास दो विकल्प हैं:

• पहला विकल्प: AutocompleteSupportFragment को एम्बेड करें.
• दूसरा विकल्प: ऑटोकंप्लीट गतिविधि लॉन्च करने के लिए इंटेंट का इस्तेमाल करना.

पहला विकल्प: 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 में लिसनर जोड़ने का तरीका दिखाया गया है:

    // 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.DISPLAY_NAME))

    // Set up a PlaceSelectionListener to handle the response.
    autocompleteFragment.setOnPlaceSelectedListener(object : PlaceSelectionListener {
        override fun onPlaceSelected(place: Place) {
            binding.autocompleteResult.text = getString(
                R.string.place_selection,
                place.displayName,
                place.id,
                place.formattedAddress
            )
            Log.i(TAG, "Place: ${place.displayName}, ${place.id}")
        }

        override fun onError(status: Status) {
            binding.autocompleteResult.text = getString(R.string.an_error_occurred, status)
            Log.i(TAG, "An error occurred: $status")
        }
    })

      

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

    // Specify the types of place data to return.
    assert autocompleteFragment != null;
    autocompleteFragment.setPlaceFields(Arrays.asList(Place.Field.ID, Place.Field.DISPLAY_NAME, Place.Field.FORMATTED_ADDRESS));

    // Set up a PlaceSelectionListener to handle the response.
    autocompleteFragment.setOnPlaceSelectedListener(new PlaceSelectionListener() {
        @Override
        public void onPlaceSelected(@NonNull Place place) {
            binding.autocompleteResult.setText(
                    getString(
                            R.string.place_selection,
                            place.getDisplayName(),
                            place.getId(),
                            place.getFormattedAddress()
                    )
            );
            Log.i(TAG, "Place: " + place.getDisplayName() + ", " + place.getId());
        }


        @Override
        public void onError(@NonNull Status status) {
            binding.autocompleteResult.setText(getString(R.string.an_error_occurred, status));
            Log.e(TAG, "An error occurred: " + status);
        }
    });

      

दूसरा विकल्प: अपने-आप पूरा होने की सुविधा वाली गतिविधि को लॉन्च करने के लिए इंटेंट का इस्तेमाल करना

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

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

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

अपने-आप पूरा होने वाला इंटेंट बनाना

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

    // 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.DISPLAY_NAME, Place.Field.FORMATTED_ADDRESS)

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

    startAutocomplete.launch(intent)

      

    // 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.DISPLAY_NAME, Place.Field.FORMATTED_ADDRESS);

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

      

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

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

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

private val startAutocomplete =
    registerForActivityResult(ActivityResultContracts.StartActivityForResult()) { result: ActivityResult ->
        if (result.resultCode == RESULT_OK) {
            val intent = result.data
            if (intent != null) {
                val place = Autocomplete.getPlaceFromIntent(intent)
                binding.autocompleteResult.text = getString(
                    R.string.place_selection,
                    place.displayName,
                    place.id,
                    place.formattedAddress)
                Log.i(
                    TAG, "Place: ${place.displayName}, ${place.id}"
                )
            }
        } else if (result.resultCode == RESULT_CANCELED) {
            // The user canceled the operation.
            binding.autocompleteResult.setText(R.string.user_canceled_autocomplete)
            Log.i(TAG, "User canceled autocomplete")
        }
    }

      

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);
                    binding.autocompleteResult.setText(
                            getString(
                                    R.string.place_selection,
                                    place.getDisplayName(),
                                    place.getId(),
                                    place.getFormattedAddress()
                            )
                    );
                    Log.i(TAG, "Place: " + place.getDisplayName() + ", " + place.getId());
                }
            } else if (result.getResultCode() == Activity.RESULT_CANCELED) {
                // The user canceled the operation.
                binding.autocompleteResult.setText(R.string.user_canceled_autocomplete);
                Log.i(TAG, "User canceled autocomplete");
            }
        });

      

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

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

• ज़रूरी है: query स्ट्रिंग, जिसमें उपयोगकर्ता की ओर से टाइप किया गया टेक्स्ट शामिल हो.
• सुझाया गया: A AutocompleteSessionToken, जो बिलिंग के लिए, उपयोगकर्ता की खोज के क्वेरी और चुनने के चरणों को अलग-अलग सेशन में ग्रुप करता है. सेशन तब शुरू होता है, जब उपयोगकर्ता कोई क्वेरी टाइप करना शुरू करता है. यह तब खत्म होता है, जब वह कोई जगह चुनता है.
• सुझाया गया: यह एक RectangularBounds ऑब्जेक्ट है. इसमें अक्षांश और देशांतर की सीमाएं तय की जाती हैं, ताकि नतीजों को तय की गई जगह तक सीमित किया जा सके.
• ज़रूरी नहीं: एक या उससे ज़्यादा दो अक्षरों वाले देश के कोड (आईएसओ 3166-1 ऐल्फ़ा-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() को पूरा कॉल दिखाया गया है.

    // 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.ESTABLISHMENT))
            .setSessionToken(token)
            .setQuery(query)
            .build()
    placesClient.findAutocompletePredictions(request)
        .addOnSuccessListener { response: FindAutocompletePredictionsResponse ->
            val builder = StringBuilder()
            for (prediction in response.autocompletePredictions) {
                builder.append(prediction.getPrimaryText(null).toString()).append("\n")
                Log.i(TAG, prediction.placeId)
                Log.i(TAG, prediction.getPrimaryText(null).toString())
            }
            binding.autocompleteResult.text = builder.toString()
        }.addOnFailureListener { exception: Exception? ->
            if (exception is ApiException) {
                Log.e(TAG, "Place not found: ${exception.statusCode}")
                binding.autocompleteResult.text = getString(R.string.place_not_found, exception.message)
            }
        }

      

    // 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(List.of(PlaceTypes.ESTABLISHMENT))
            .setSessionToken(token)
            .setQuery(query)
            .build();

    placesClient.findAutocompletePredictions(request).addOnSuccessListener((response) -> {
        StringBuilder builder = new StringBuilder();
        for (AutocompletePrediction prediction : response.getAutocompletePredictions()) {
            builder.append(prediction.getPrimaryText(null).toString()).append("\n");
            Log.i(TAG, prediction.getPlaceId());
            Log.i(TAG, prediction.getPrimaryText(null).toString());
        }
        binding.autocompleteResult.setText(builder.toString());
    }).addOnFailureListener((exception) -> {
        if (exception instanceof ApiException apiException) {
            Log.e(TAG, "Place not found: " + apiException.getStatusCode());
            binding.autocompleteResult.setText(getString(R.string.place_not_found, apiException.getMessage()));
        }
    });

      

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

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

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

सेशन टोकन

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

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

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

ऑटोकंप्लीट के नतीजों को सीमित करना

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

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

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

किसी खास इलाके के हिसाब से नतीजे दिखाना

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

        autocompleteFragment.setLocationBias(bounds)

      

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

      

नतीजों को किसी खास इलाके के लिए सीमित करना

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

        autocompleteFragment.setLocationRestriction(bounds)

      

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

      

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

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

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

अपने-आप पूरा होने की सुविधा के नतीजों को फ़िल्टर करने के लिए, फ़िल्टर सेट करने के लिए setTypesFilter() को कॉल करें.

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

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

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

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

यहां दिए गए कोड के उदाहरण में, AutocompleteSupportFragment पर setTypesFilter() को कॉल किया गया है. साथ ही, टाइप की कई वैल्यू तय की गई हैं.

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

      

    autocompleteFragment.setTypesFilter(List.of("landmark", "restaurant", "store"));

      

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

    autocompleteFragment.setTypesFilter(listOf(PlaceTypes.ADDRESS))

      

    autocompleteFragment.setTypesFilter(List.of(PlaceTypes.ESTABLISHMENT));

      

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

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

      

    Intent intent = new Autocomplete.IntentBuilder(AutocompleteActivityMode.FULLSCREEN, fields)
            .setTypesFilter(List.of(PlaceTypes.ESTABLISHMENT))
            .build(this);

      

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

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

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

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

      

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

      

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

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

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

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

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

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

जगह के शुरुआती अक्षर लिखने पर पूरा नाम सुझाने की सुविधा (लेगसी) को ऑप्टिमाइज़ करना

इस सेक्शन में, Place Autocomplete (लेगसी) सेवा का ज़्यादा से ज़्यादा फ़ायदा पाने के लिए, सबसे सही तरीकों के बारे में बताया गया है.

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

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

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

लागत को ऑप्टिमाइज़ करने की बुनियादी सेटिंग

Place Autocomplete (लेगसी) सेवा का इस्तेमाल करने की लागत को ऑप्टिमाइज़ करने के लिए, Place Details (लेगसी) और Place Autocomplete (लेगसी) विजेट में फ़ील्ड मास्क का इस्तेमाल करें. इससे आपको सिर्फ़ वे Place Autocomplete (लेगसी) डेटा फ़ील्ड मिलेंगे जिनकी आपको ज़रूरत है.

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

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

• अगर आपको सिर्फ़ उपयोगकर्ता की चुनी गई जगह का अक्षांश/देशांतर या पता चाहिए, तो Geocoding API, Place Details (लेगसी) API के कॉल की तुलना में कम समय में यह जानकारी उपलब्ध कराता है.
• अगर उपयोगकर्ता, औसतन चार या इससे कम बार Place Autocomplete (लेगसी) के सुझावों के लिए अनुरोध करते हैं, तो हर अनुरोध के हिसाब से तय की गई कीमत, हर सेशन के हिसाब से तय की गई कीमत से ज़्यादा किफ़ायती हो सकती है.

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

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

यहां दिए गए दिशा-निर्देशों में, Place Autocomplete (लेगसी) की परफ़ॉर्मेंस को ऑप्टिमाइज़ करने के तरीके बताए गए हैं:

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

जगह के हिसाब से नतीजे दिखाना

location पैरामीटर और radius पैरामीटर पास करके, नतीजों को किसी खास इलाके के हिसाब से दिखाएं. इससे Place Autocomplete (लेगसी) को यह निर्देश मिलता है कि वह तय की गई जगह के हिसाब से नतीजे दिखाए. हालांकि, तय की गई जगह से बाहर के नतीजे भी दिख सकते हैं. components पैरामीटर का इस्तेमाल करके, नतीजों को फ़िल्टर किया जा सकता है. इससे सिर्फ़ किसी देश में मौजूद जगहों के नतीजे दिखते हैं.

जगह की जानकारी को सीमित करना

locationRestriction पैरामीटर पास करके, नतीजों को किसी तय जगह के लिए सीमित करें.

location और radius पैरामीटर से तय किए गए क्षेत्र के हिसाब से भी नतीजों को सीमित किया जा सकता है. इसके लिए, strictbounds पैरामीटर जोड़ें. इससे Place Autocomplete (लेगसी) को उस क्षेत्र के सिर्फ़ नतीजे दिखाने का निर्देश मिलता है.

समस्या का हल

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

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