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

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

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

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

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

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

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

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

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

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

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

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

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

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

यहां दिए गए सैंपल में, Kotlin और Java, दोनों का इस्तेमाल करके, किसी जगह के शुरुआती अक्षर लिखने पर पूरा नाम सुझाने की सुविधा वाला विजेट जोड़ने का तरीका बताया गया है:

// 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);

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

ऑटोकंप्लीट की सुविधा को इंस्टैंशिएट करते समय, ऐसी थीम तय की जा सकती है जो डिफ़ॉल्ट स्टाइल एट्रिब्यूट में से किसी को भी बदल देती है. किसी जगह के शुरुआती अक्षर लिखने पर पूरा नाम सुझाने की सुविधा वाले कॉम्पोनेंट के रंग, टाइपोग्राफ़ी, स्पेसिंग, बॉर्डर, और कोनों को पसंद के मुताबिक बनाया जा सकता है. डिफ़ॉल्ट रूप से, यह कार्रवाई 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);

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

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

Places.initializeWithNewPlacesApiEnabled(context, apiKey);
final List<Field> placeFields = getPlaceFields();
LatLng center = new LatLng(37.7749, -122.4194);
CircularBounds circle = CircularBounds.newInstance(center, /* radius = */ 5000);
final FindAutocompletePredictionsRequest autocompletePlacesRequest =
    FindAutocompletePredictionsRequest.builder()
            .setQuery("Sicilian piz")
            .setRegionCode("ES")
            .setLocationRestriction(circle)
            .build());
placesClient.findAutocompletePredictions(autoCompletePlacesRequest)
    .addOnSuccessListener(
        (response) -> {
            List<AutocompletePrediction> predictions = response.getResult().getAutocompletePredictions();
          }
    ).addOnFailureListener(
        exception -> {
            Log.e(TAG, "some exception happened" + exception.getMessage());
        })
    );

'अपने-आप पूरा होने की सुविधा (नई)' के जवाब

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

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

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

ज़रूरी पैरामीटर

• क्वेरी

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

  क्वेरी पैरामीटर सेट करने के लिए, FindAutocompletePredictionsRequest ऑब्जेक्ट बनाते समय setQuery() तरीके को कॉल करें.

ज़रूरी नहीं पैरामीटर

• प्राइमरी टाइप

  टाइप की वैल्यू की सूची. इसमें ज़्यादा से ज़्यादा पांच वैल्यू हो सकती हैं. ये वैल्यू, टेबल A या टेबल B में मौजूद टाइप से ली जाती हैं. इनका इस्तेमाल, जवाब में दिखाई गई जगहों को फ़िल्टर करने के लिए किया जाता है. जवाब में किसी जगह को शामिल करने के लिए, यह ज़रूरी है कि वह बताई गई प्राइमरी टाइप वैल्यू में से किसी एक से मेल खाती हो.

  किसी जगह के लिए, सिर्फ़ एक मुख्य टाइप हो सकता है. यह टाइप, टेबल A या टेबल B से जुड़ा होना चाहिए. उदाहरण के लिए, मुख्य टाइप "mexican_restaurant" या "steak_house" हो सकता है.

  अगर अनुरोध में ये गड़बड़ियां हैं, तो उसे INVALID_REQUEST गड़बड़ी के साथ अस्वीकार कर दिया जाता है:

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

  प्राइमरी टाइप पैरामीटर सेट करने के लिए, FindAutocompletePredictionsRequest ऑब्जेक्ट बनाते समय setTypesFilter() मेथड को कॉल करें.

• देश

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

  अगर locationRestriction और includedRegionCodes, दोनों की जानकारी दी जाती है, तो नतीजे दोनों सेटिंग के इंटरसेक्शन वाले इलाके में दिखते हैं.

  देशों के पैरामीटर को सेट करने के लिए, FindAutocompletePredictionsRequest ऑब्जेक्ट बनाते समय setCountries() मेथड को कॉल करें.

• इनपुट ऑफ़सेट

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

  इनपुट ऑफ़सेट पैरामीटर सेट करने के लिए, FindAutocompletePredictionsRequest ऑब्जेक्ट बनाते समय setInputOffset() तरीके को कॉल करें.

• जगह के हिसाब से पक्षपात या जगह के हिसाब से पाबंदी

  खोज के दायरे को तय करने के लिए, जगह के हिसाब से खोज के नतीजों को प्राथमिकता देने या जगह के हिसाब से खोज के नतीजों को सीमित करने की सुविधा का इस्तेमाल किया जा सकता है. हालांकि, दोनों सुविधाओं का एक साथ इस्तेमाल नहीं किया जा सकता. जगह के हिसाब से पाबंदी लगाने का मतलब है कि आपको यह तय करना है कि नतीजे किस इलाके के होने चाहिए. वहीं, जगह के हिसाब से खोज के नतीजों में बदलाव करने का मतलब है कि आपको यह तय करना है कि नतीजे किस इलाके के आस-पास के होने चाहिए. इनमें मुख्य अंतर यह है कि जगह के हिसाब से नतीजे दिखाने की सुविधा का इस्तेमाल करने पर, तय किए गए इलाके से बाहर के नतीजे भी दिखाए जा सकते हैं.

  • लोकेशन बायस

    खोजने के लिए कोई हिस्सा तय करता है. यह लोकेशन, खोज के नतीजों को सीमित करने के बजाय, उन्हें एक खास दिशा देती है. इसलिए, हो सकता है कि आपको बताई गई जगह के बाहर के नतीजे भी दिखें.

    लोकेशन बायस पैरामीटर सेट करने के लिए, FindAutocompletePredictionsRequest ऑब्जेक्ट बनाते समय setLocationBias() तरीके को कॉल करें.

  • जगह के हिसाब से पाबंदी

    खोजने के लिए कोई हिस्सा तय करता है. तय किए गए इलाके से बाहर के नतीजे नहीं दिखाए जाते.

    जगह की जानकारी से जुड़ी पाबंदी का पैरामीटर सेट करने के लिए, FindAutocompletePredictionsRequest ऑब्जेक्ट बनाते समय setLocationRestriction() तरीके को कॉल करें.

  जगह के हिसाब से नतीजों में बदलाव करने या जगह से जुड़ी पाबंदी वाले क्षेत्र को रेक्टैंगल व्यूपोर्ट या सर्कल के तौर पर तय करें.

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

  • रेक्टैंगल, अक्षांश-देशांतर वाला व्यूपोर्ट होता है. इसे डायगनल के तौर पर, एक-दूसरे के सामने मौजूद दो low और high पॉइंट के तौर पर दिखाया जाता है. व्यूपोर्ट को एक बंद क्षेत्र माना जाता है. इसका मतलब है कि इसमें इसकी सीमा शामिल होती है. अक्षांश की सीमाएं -90 से 90 डिग्री के बीच होनी चाहिए. साथ ही, देशांतर की सीमाएं -180 से 180 डिग्री के बीच होनी चाहिए:

    • अगर low = high है, तो व्यूपोर्ट में सिर्फ़ एक पॉइंट होता है.
    • अगर low.longitude > high.longitude है, तो देशांतर की रेंज उल्टी हो जाती है (व्यूपोर्ट, 180 डिग्री देशांतर रेखा को पार कर जाता है).
    • अगर low.longitude = -180 डिग्री और high.longitude = 180 डिग्री है, तो व्यूपोर्ट में सभी देशांतर शामिल होते हैं.
    • अगर low.longitude = 180 डिग्री और high.longitude = -180 डिग्री है, तो देशांतर की रेंज खाली होती है.

    low और high, दोनों फ़ील्ड में वैल्यू डालना ज़रूरी है. साथ ही, बॉक्स में वैल्यू डालना भी ज़रूरी है. व्यू पोर्ट खाली होने पर गड़बड़ी होती है.

• शुरुआत की जगह

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

  ओरिजिन पैरामीटर सेट करने के लिए, FindAutocompletePredictionsRequest ऑब्जेक्ट बनाते समय setOrigin() तरीके को कॉल करें.

• क्षेत्र कोड

  जवाब को फ़ॉर्मैट करने के लिए इस्तेमाल किया गया देश/इलाके का कोड. इसमें पते का फ़ॉर्मैट भी शामिल है. इसे ccTLD ("टॉप-लेवल डोमेन") की दो वर्णों वाली वैल्यू के तौर पर बताया गया है. ज़्यादातर ccTLD कोड, ISO 3166-1 कोड से मिलते-जुलते होते हैं. हालांकि, कुछ अपवाद भी होते हैं. उदाहरण के लिए, यूनाइटेड किंगडम का ccTLD "uk" (.co.uk) है, जबकि इसका ISO 3166-1 कोड "gb" है. तकनीकी तौर पर, यह कोड "द यूनाइटेड किंगडम ऑफ़ ग्रेट ब्रिटेन ऐंड नॉर्दर्न आयरलैंड" के लिए है.

  अगर आपने अमान्य क्षेत्र कोड डाला है, तो एपीआई INVALID_ARGUMENT गड़बड़ी का मैसेज दिखाता है. लागू कानून के आधार पर, इस पैरामीटर से नतीजों पर असर पड़ सकता है.

  देश/इलाके के कोड पैरामीटर को सेट करने के लिए, FindAutocompletePredictionsRequest ऑब्जेक्ट बनाते समय setRegionCode() तरीके को कॉल करें.

• सेशन टोकन

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

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

  सेशन टोकन पैरामीटर सेट करने के लिए, FindAutocompletePredictionsRequest ऑब्जेक्ट बनाते समय setSessionToken() तरीके को कॉल करें.

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

ऑटोकंप्लीट (नया) के उदाहरण

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

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

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

Places.initializeWithNewPlacesApiEnabled(context, apiKey);
final List<Field> placeFields = getPlaceFields();

LatLng center = new LatLng(37.7749, -122.4194);
CircularBounds circle = CircularBounds.newInstance(center, /* radius = */ 5000);

final FindAutocompletePredictionsRequest autocompletePlacesRequest =
    FindAutocompletePredictionsRequest.builder()
            .setQuery("Amoeba")
            .setLocationRestriction(circle)
            .build());
placesClient.findAutocompletePredictions(autoCompletePlacesRequest)
    .addOnSuccessListener(
        (response) -> {
            List<AutocompletePrediction> predictions = response.getResult().getAutocompletePredictions();
          }
    ).addOnFailureListener(
        exception -> {
            Log.e(TAG, "some exception happened" + exception.getMessage());
        })
    );

जगह के हिसाब से नतीजे दिखाने की सुविधा में, जगह की जानकारी का इस्तेमाल बायस के तौर पर किया जाता है. इसका मतलब है कि चुनी गई जगह के आस-पास के नतीजे दिखाए जा सकते हैं. इनमें, चुनी गई जगह से बाहर के नतीजे भी शामिल हो सकते हैं. इस उदाहरण में, पिछले अनुरोध में बदलाव करके जगह के हिसाब से खोज के नतीजों को प्राथमिकता देने की सुविधा का इस्तेमाल किया गया है:

Places.initializeWithNewPlacesApiEnabled(context, apiKey);
final List<Field> placeFields = getPlaceFields();

LatLng center = new LatLng(37.7749, -122.4194);
CircularBounds circle = CircularBounds.newInstance(center, /* radius = */ 5000);

final FindAutocompletePredictionsRequest autocompletePlacesRequest =
    FindAutocompletePredictionsRequest.builder()
            .setQuery("Amoeba")
            .setLocationBias(circle)
            .build());
placesClient.findAutocompletePredictions(autoCompletePlacesRequest)
    .addOnSuccessListener(
        (response) -> {
            List<AutocompletePrediction> predictions = response.getResult().getAutocompletePredictions();
          }
    ).addOnFailureListener(
        exception -> {
            Log.e(TAG, "some exception happened" + exception.getMessage());
        })
    );

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

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

यहां दिए गए उदाहरण में, "Soccer" की क्वेरी स्ट्रिंग के बारे में बताया गया है. साथ ही, नतीजों को "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 ऑटोकंप्लीट (नया) विजेट, Places SDK for Android ऑटोकंप्लीट (नया) विजेट या Places SDK for iOS ऑटोकंप्लीट (नया) विजेट का इस्तेमाल करना.
• शुरुआत से ही, ऑटोकंप्लीट (नई) के ज़रूरी डेटा फ़ील्ड को समझें.
• जगह के हिसाब से खोज के नतीजों को प्राथमिकता देने और जगह के हिसाब से पाबंदी लगाने वाले फ़ील्ड का इस्तेमाल करना ज़रूरी नहीं है. हालांकि, इससे अपने-आप पूरा होने की सुविधा की परफ़ॉर्मेंस पर काफ़ी असर पड़ सकता है.
• गड़बड़ी को मैनेज करने की सुविधा का इस्तेमाल करें, ताकि एपीआई से गड़बड़ी मिलने पर आपका ऐप्लिकेशन सही तरीके से काम करता रहे.
• पक्का करें कि आपका ऐप्लिकेशन, कोई विकल्प न चुने जाने पर उपयोगकर्ताओं को आगे बढ़ने का तरीका उपलब्ध कराता हो.

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

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

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

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

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

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

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

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

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

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

जगह की जानकारी से जुड़ी पाबंदियां

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

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