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

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

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

अपने ऐप्लिकेशन में, खोज क्वेरी के अपने-आप पूरे होने की सुविधा (नई) को इन दो मुख्य तरीकों से इंटिग्रेट किया जा सकता है:

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

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

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

जैसे, प्रोग्राम के हिसाब से जगह के सुझाव पाने के लिए, Place Autocomplete विजेट आपको सेशन टोकन इस्तेमाल करने की सुविधा देता है. इससे, बिलिंग के लिए ऑटोकंप्लीट अनुरोधों को सेशन में ग्रुप किया जा सकता है. setAutocompleteSessionToken() को कॉल करके, विजेट के लिए इंटेंट बनाते समय सेशन टोकन पास किया जा सकता है. अगर आपने सेशन टोकन नहीं दिया है, तो विजेट आपके लिए एक टोकन बनाएगा. इसे getSessionTokenFromIntent() को कॉल करके ऐक्सेस किया जा सकता है. सेशन टोकन इस्तेमाल करने के बारे में ज़्यादा जानने के लिए, सेशन टोकन के बारे में जानकारी लेख पढ़ें.

अपने ऐप्लिकेशन में जगह के लिए ऑटोकंप्लीट विजेट जोड़ने के लिए:

1. (ज़रूरी नहीं) सेशन टोकन तय करें. अगर आपने सेशन टोकन नहीं दिया है, तो विजेट आपके लिए एक टोकन बना देगा.

2. अपनी पसंद के पैरामीटर और सेशन टोकन के साथ autocompleteIntent तय करें.

3. StartActivityForResult के लिए ActivityResultLauncher तय करें. यह लॉन्चर, अपने-आप पूरा होने वाली सुविधा से मिले नतीजे को मैनेज करेगा.

4. ActivityResultLauncher के कॉलबैक में नतीजे को हैंडल करें. इसमें AutocompletePrediction और AutocompleteSessionToken को निकालना (अगर आपने खुद नहीं दिया है), गड़बड़ियों को ठीक करना, और किसी जगह के बारे में ज़्यादा जानकारी पाने के लिए fetchPlace() अनुरोध करना शामिल है.

5. placeAutocompleteActivityResultLauncher का इस्तेमाल करके इंटेंट लॉन्च करना

यहां दिए गए सैंपल में, Kotlin और Java, दोनों का इस्तेमाल करके Place Autocomplete विजेट जोड़ने का तरीका बताया गया है:

// Provide the API key that has enabled "Places API (New)" in the Google Cloud Console.
Places.initializeWithNewPlacesApiEnabled(/* Context= */ context, /* API Key= */ key)

// Optional, create a session token for Autocomplete request and the followup FetchPlace request.
val sessionToken: AutocompleteSessionToken = AutocompleteSessionToken.newInstance()

val autocompleteIntent: Intent =
    PlaceAutocomplete.createIntent(this) {
        // ... provide input params for origin, countries, types filter ...
        setAutocompleteSessionToken(sessionToken)
    }

val placeAutocompleteActivityResultLauncher: ActivityResultLauncher<Intent> =
    registerForActivityResult(ActivityResultContracts.StartActivityForResult()) { result: ActivityResult ->
        val intent = result.data
        if (intent != null && result.resultCode == PlaceAutocompleteActivity.RESULT_OK) {
            // get prediction object
            val prediction: AutocompletePrediction? =
                PlaceAutocomplete.getPredictionFromIntent(intent!!)

            // get session token
            val sessionToken: AutocompleteSessionToken? =
                PlaceAutocomplete.getSessionTokenFromIntent(intent!!)

            // create PlacesClient to make FetchPlace request (optional)
            val placesClient: PlacesClient = Places.createClient(this)
            val response =
                placesClient.awaitFetchPlace(prediction.placeId, Field.DISPLAY_NAME)
                {
                    sessionToken = sessionToken // optional
                }
        }
    }

// Launch Activity
placeAutocompleteActivityResultLauncher.launch(autocompleteIntent)

// Provide the API key that has enabled "Places API (New)" in the Google Cloud Console.
Places.initializeWithNewPlacesApiEnabled(/* Context= */ context, /* API Key= */ key);

// Optional, create a session token for Autocomplete request and the followup FetchPlace request
AutocompleteSessionToken sessionToken = AutocompleteSessionToken.newInstance();

Intent autocompleteIntent =
    new PlaceAutocomplete.IntentBuilder()
        // ... set input params for origin, countries, types filter ...
        .setSessionToken(sessionToken) // optional
        .build(this);

ActivityResultLauncher<Intent> placeAutocompleteActivityResultLauncher =
    registerForActivityResult(
        new ActivityResultContracts.StartActivityForResult(),
        new ActivityResultCallback<ActivityResult>() {
            @Override
            public void onActivityResult(ActivityResult result) {
                Intent intent = result.getData();
                if (result.getResultCode() == PlaceAutocompleteActivity.RESULT_OK) {
                    // get prediction object
                    AutocompletePrediction prediction =
                        PlaceAutocomplete.getPredictionFromIntent(
                            Preconditions.checkNotNull(intent));

                    // get session token
                    AutocompleteSessionToken sessionToken =
                        PlaceAutocomplete.getSessionTokenFromIntent(
                            Preconditions.checkNotNull(intent));

                    // create PlacesClient to make FetchPlace request (optional)
                    PlacesClient placesClient = Places.createClient(this);
                    FetchPlaceRequest request =
                        FetchPlaceRequest.builder(prediction.getPlaceId(),
                            Arrays.asList(Field.DISPLAY_NAME))
                            .setSessionToken(sessionToken).build();
                    Task<FetchPlaceResponse> task = placesClient.fetchPlace(request);
                }
            }
        }
    );

// Launch Activity
placeAutocompleteActivityResultLauncher.launch(autocompleteIntent);

थीम को पसंद के मुताबिक बनाना

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

…/res/values/themes.xml में थीम ओवरराइड तय किए जा सकते हैं. उदाहरण के लिए:

<?xml version="1.0" encoding="utf-8"?>
<resources>
  <style name="BrandedTheme" parent="PlacesMaterialTheme">
    <!-- Color tokens. -->
    <item name="placesColorOnNeutralContainer">#5300e8</item>
    <item name="placesColorOnNeutralContainerVariant">#ee6002</item>
    ...

    <!-- Typography tokens. -->
    <item name="placesTextAppearanceTitleLarge">@style/PlacesTextAppearance</item>
    <item name="placesTextAppearanceBodyMedium">@style/PlacesTextAppearance</item>
    ...

    <!-- Spacing tokens. -->
    <item name="placesSpacingSmall">6dp</item>
    <item name="placesSpacingMedium">12dp</item>
    ...

    <!-- Attribution tokens. -->
    <item name="placesColorAttributionLightTheme">white</item>
    <item name="placesColorAttributionDarkTheme">black</item>
  </style>
</resources>

इसके बाद, setAutocompleteUiCustomization को कॉल करके, ओवरराइड की गई स्टाइल का रेफ़रंस दिया जा सकता है:

ActivityResultLauncher<Intent> placeAutocompleteActivityResultLauncher =
  registerForActivityResult(
    new ActivityResultContracts.StartActivityForResult(),
    new ActivityResultCallback<ActivityResult>() {
      @Override
      public void onActivityResult(ActivityResult result) {
        Intent intent = result.getData();
        if (intent != null) {
          AutocompletePrediction prediction =
            PlaceAutocomplete.getPredictionFromIntent(intent);
          AutocompleteSessionToken sessionToken =
            PlaceAutocomplete.getSessionTokenFromIntent(intent);
          Status status = PlaceAutocomplete.getResultStatusFromIntent(intent);
          ...
        }
      }
    }
  );

Intent placeAutocompleteIntent =
  new PlaceAutocomplete.IntentBuilder()
    .setInitialQuery("INSERT_QUERY_TEXT")
    .setOrigin(new LatLng(10.0, 10.0))
    ...

    .setAutocompleteUiCustomization(
      AutocompleteUiCustomization.builder()
        .listItemIcon(AutocompleteUiIcon.noIcon())
        .listDensity(AutocompleteListDensity.MULTI_LINE)
        .theme(R.style.BrandedTheme)
        .build())
  .build(this);

placeAutocompleteActivityResultLauncher.launch(placeAutocompleteIntent);

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

आपका ऐप्लिकेशन, FindAutocompletePredictionsRequest ऑब्जेक्ट पास करके, PlacesClient.findAutocompletePredictions() को कॉल करके, ऑटोकंप्लीट एपीआई से अनुमानित जगहों के नामों और/या पतों की सूची पा सकता है. नीचे दिए गए उदाहरण में, 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 पैरामीटर ज़रूरी नहीं है. अगर आपको कोई भी हाइलाइटिंग नहीं चाहिए, तो इसे null पर सेट करें.
• 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

  • पांच से ज़्यादा टाइप दिए गए हैं.
  • ऐसे टाइप के बारे में बताया जाता है जिनकी पहचान नहीं हुई है.

  primaryTypes पैरामीटर सेट करने के लिए, 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() तरीके को कॉल करें.

  ज़्यादा जानकारी के लिए, सेशन टोकन देखें.

ऑटोकंप्लीट (नई सुविधा) के उदाहरण

जगह के हिसाब से पाबंदी और जगह के हिसाब से खोज के नतीजों में बदलाव करने की सुविधा का इस्तेमाल करना

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

जगह के हिसाब से पाबंदी लगाने पर, खोज के लिए जगह तय की जाती है. तय की गई जगह के बाहर के नतीजे नहीं दिखाए जाते. इस उदाहरण में, सैन फ़्रांसिस्को के 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());
        })
    );

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

primary types पैरामीटर का इस्तेमाल करके, अनुरोध के नतीजों को टेबल A और टेबल B में दिए गए टाइप तक सीमित किया जा सकता है. ज़्यादा से ज़्यादा पांच वैल्यू का कलेक्शन तय किया जा सकता है. अगर इसे शामिल नहीं किया जाता है, तो सभी टाइप दिखाए जाते हैं.

इस उदाहरण में, "फ़ुटबॉल" की क्वेरी स्ट्रिंग दी गई है. साथ ही, इसमें primarytypes पैरामीटर का इस्तेमाल करके, नतीजों को "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());
        })
    );

ऑटोकंप्लीट (नई) सुविधा के लिए ऑप्टिमाइज़ेशन

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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