تکمیل خودکار (جدید)

پلاتفرم را انتخاب کنید: Android iOS JavaScript سرویس وب

توسعه‌دهندگان منطقه اقتصادی اروپا (EEA)

«تکمیل خودکار» (جدید) پیش‌بینی‌های مکان را در پاسخ به درخواستی که شامل رشته جستجوی نوشتاری و مرزهای جغرافیایی کنترل‌کننده منطقه جستجو است برمی‌گرداند. تکمیل خودکار می‌تواند با کلمات کامل و رشته‌های فرعی ورودی مطابقت داشته باشد و نام مکان‌ها، نشانی‌ها، و پلاس‌کدها را حل کند. برنامه شما می‌تواند هم‌زمان با تایپ کردن کاربر پُرسمان ارسال کند تا پیش‌بینی‌های پُرسمان و مکان را درلحظه ارائه دهد.

برای مثال، «تکمیل خودکار» را بااستفاده از رشته‌ای به‌عنوان ورودی که حاوی بخشی از ورودی کاربر است، «Sicilian piz»، فراخوانی می‌کنید و منطقه جستجو را به سان‌فرانسیسکو، کالیفرنیا محدود می‌کنید. سپس پاسخ حاوی فهرستی از پیش‌بینی‌های مکان است که با رشته جستجو و منطقه جستجو مطابقت دارد، مانند رستورانی با نام «Sicilian Pizza Kitchen». پیش‌بینی‌های مکان برگشتی به‌گونه‌ای طراحی شده‌اند که به کاربر ارائه شوند تا در انتخاب مکان موردنظر به او کمک کنند. می‌توانید درخواست جزئیات مکان (جدید) بدهید تا اطلاعات بیشتری درباره هریک از پیش‌بینی‌های مکان برگشتی دریافت کنید.

می‌توانید عملکرد «تکمیل خودکار (جدید)» را به دو روش اصلی در برنامه‌تان ادغام کنید:

افزودن ابزارک «تکمیل خودکار جا»

برای اینکه راحت‌تر بتوانید تجربه تکمیل خودکار مکان یکسانی ارائه دهید، می‌توانید ابزاره «تکمیل خودکار مکان» را به برنامه‌تان اضافه کنید. این ابزاره رابط اختصاصی تمام‌صفحه‌ای ارائه می‌دهد که ورودی کاربر را مدیریت می‌کند و پیش‌بینی‌های مکان را به کاربر نمایش می‌دهد و درعین‌حال AutocompletePrediction اشیا را به برنامه برمی‌گرداند. سپس می‌توانید درخواست جزئیات مکان (جدید) را برای دریافت اطلاعات بیشتر درباره هریک از پیش‌بینی‌های مکان ارسال کنید.

ابزاره تکمیل خودکار جا

برای مثال، وقتی پیش‌بینی‌های مکان را به‌صورت برنامه‌ریزی‌شده دریافت می‌کنید، ابزارک «تکمیل خودکار مکان» به شما امکان می‌دهد از نشانه جلسه برای گروه‌بندی درخواست‌های تکمیل خودکار در جلسه برای اهداف صدور صورت‌حساب استفاده کنید. می‌توانید با فراخوانی setAutocompleteSessionToken()، هنگام ایجاد قصد برای ابزاره، یک کد جلسه ارسال کنید. اگر کد جلسه ارائه نکنید، ابزاره کد جلسه‌ای برایتان ایجاد می‌کند که با فراخوانی getSessionTokenFromIntent() می‌توانید به آن دسترسی پیدا کنید. برای اطلاعات بیشتر درباره استفاده از نشان‌های جلسه، به درباره نشان‌های جلسه مراجعه کنید.

برای افزودن ابزاره «تکمیل خودکار مکان» به برنامه‌تان:

  1. (اختیاری) کد جلسه را تعریف کنید. اگر کد جلسه ارائه نکنید، ابزاره یکی برایتان ایجاد خواهد کرد.

  2. autocompleteIntent را با پارامترهای موردنظر و کد جلسه خود تعریف کنید.

  3. ‫ActivityResultLauncher را برای StartActivityForResult تعریف کنید. این راه‌انداز نتیجه برگردانده‌شده از فعالیت تکمیل خودکار را مدیریت خواهد کرد.

  4. نتیجه را در پاسخ‌به‌تماس ActivityResultLauncher مدیریت کنید. این کار شامل استخراج AutocompletePrediction و AutocompleteSessionToken (اگر خودتان ارائه نکرده‌اید)، رسیدگی به خطاها، و درصورت تمایل، ایجاد درخواست fetchPlace() برای دریافت جزئیات بیشتر درباره مکان است.

  5. راه‌اندازی قصد بااستفاده از placeAutocompleteActivityResultLauncher

نمونه‌های زیر نحوه افزودن ابزاره «تکمیل خودکار مکان» را بااستفاده از هم Kotlin و هم Java نشان می‌دهد:

Kotlin

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

پاسخ‌های تکمیل خودکار (جدید)

این API FindAutocompletePredictionsResponse را در Task برمی‌گرداند. این FindAutocompletePredictionsResponse شامل فهرستی از حداکثر پنج AutocompletePrediction شیء است که نشان‌دهنده مکان‌های پیش‌بینی‌شده است. اگر مکان شناخته‌شده‌ای مطابق با پُرسمان و معیارهای فیلتر وجود نداشته باشد، ممکن است فهرست خالی باشد.

برای هر مکان پیش‌بینی‌شده، می‌توانید روش‌های زیر را برای بازیابی جزئیات مکان فراخوانی کنید:

  • getFullText(CharacterStyle) متن کامل شرح مکان را برمی‌گرداند. این ترکیبی از نوشتار اصلی و فرعی است. مثال: «برج ایفل، خیابان آناتول فرانس، پاریس، فرانسه». علاوه‌براین، این روش به شما امکان می‌دهد بخش‌هایی از شرح را که با جستجو مطابقت دارد با سبک انتخابی‌تان و بااستفاده از CharacterStyle برجسته کنید. پارامتر CharacterStyle اختیاری است. اگر به برجسته‌سازی نیاز ندارید، آن را روی null تنظیم کنید.
  • getPrimaryText(CharacterStyle) نوشتار اصلی توصیف‌کننده مکان را برمی‌گرداند. این معمولاً نام مکان است. مثال‌ها: «برج ایفل» و «خیابان پیت ۱۲۳».
  • getSecondaryText(CharacterStyle) نوشتار فرعی شرح مکان را برمی‌گرداند. این کار برای مثال به‌عنوان خط دوم هنگام نمایش پیش‌بینی‌های تکمیل خودکار مفید است. مثال‌ها: «Avenue Anatole France, Paris, France» (خیابان آناتول فرانس، پاریس، فرانسه) و «Sydney, New South Wales» (سیدنی، نیو ساوت ولز).
  • getPlaceId() شناسه مکان پیش‌بینی‌شده را برمی‌گرداند. شناسه مکان یک شناسه متنی است که به‌طور منحصربه‌فرد یک مکان را شناسایی می‌کند و می‌توانید از آن برای بازیابی مجدد شیء Place در آینده استفاده کنید. برای اطلاعات بیشتر درباره شناسه‌های جا در «تکمیل خودکار»، جزئیات جا (جدید) را ببینید. برای اطلاعات کلی درباره شناسه‌های مکان، به نمای کلی شناسه مکان مراجعه کنید.
  • getTypes() فهرست انواع مکان‌های مرتبط با این مکان را برمی‌گرداند.
  • getDistanceMeters() فاصله مستقیم را به متر بین این مکان و مبدأ مشخص‌شده در درخواست برمی‌گرداند.

پارامترهای الزامی

  • پُرسمان

    رشته نوشتاری که باید جستجو شود. کلمات کامل و رشته‌های فرعی، نام مکان‌ها، نشانی‌ها، و کدهای پلاس را مشخص کنید. سرویس «تکمیل خودکار (جدید)» مطابقت‌های احتمالی را براساس این رشته برمی‌گرداند و نتایج را براساس ارتباط درک‌شده آن‌ها مرتب می‌کند.

    برای تنظیم پارامتر پُرسمان، هنگام ساختن شیء FindAutocompletePredictionsRequest، روش setQuery() را فراخوانی کنید.

پارامترهای اختیاری

  • انواع اصلی

    فهرستی از حداکثر پنج مقدار نوع از انواع جدول الف یا جدول ب که برای فیلتر کردن مکان‌های برگردانده‌شده در پاسخ استفاده می‌شود. مکان باید با یکی از مقادیر نوع اصلی مشخص‌شده مطابقت داشته باشد تا در پاسخ گنجانده شود.

    مکان فقط می‌تواند یک نوع اصلی از انواع جدول A یا جدول B منسوب به خود داشته باشد. برای مثال، نوع اصلی ممکن است "mexican_restaurant" یا "steak_house" باشد.

    درخواست با خطای INVALID_REQUEST رد می‌شود اگر:

    • بیش‌از پنج نوع مشخص شده است.
    • هر نوع ناشناخته‌ای مشخص شده است.

    برای تنظیم پارامتر انواع اصلی، هنگام ساختن شیء FindAutocompletePredictionsRequest، روش setTypesFilter() را فراخوانی کنید.

  • کشورها

    فقط نتایج فهرست کشورهای مشخص‌شده را اضافه کنید، که به‌صورت فهرستی از حداکثر ۱۵ مقدار دو نویسه‌ای ccTLD («دامنه سطح بالا») مشخص شده است. اگر حذف شود، هیچ محدودیتی بر پاسخ اعمال نمی‌شود. برای مثال، برای محدود کردن مناطق به آلمان و فرانسه:

    اگر هم locationRestriction و هم includedRegionCodes را مشخص کنید، نتایج در منطقه تقاطع این دو تنظیم قرار می‌گیرند.

    برای تنظیم پارامتر کشورها، هنگام ساختن شیء FindAutocompletePredictionsRequest، روش setCountries() را فراخوانی کنید.

  • فاصله ورودی

    انحراف نویسه یونی‌کد مبتنی بر صفر که موقعیت مکان‌نما را در پُرسمان نشان می‌دهد. موقعیت مکان‌نما می‌تواند بر پیش‌بینی‌های برگشتی تأثیر بگذارد. اگر خالی باشد، به‌طور پیش‌فرض طول پُرسمان را می‌گیرد.

    برای تنظیم پارامتر جبران ورودی، هنگام ساختن شیء FindAutocompletePredictionsRequest، روش setInputOffset() را فراخوانی کنید.

  • سوگیری مکانی یا محدودیت مکانی

    برای تعریف کردن محدوده جستجو، می‌توانید گرایش مکانی یا محدودیت مکانی را مشخص کنید، اما نمی‌توانید هر دو را مشخص کنید. محدودیت مکان را به‌عنوان مشخص کردن منطقه‌ای که نتایج باید در آن قرار داشته باشند درنظر بگیرید، و سوگیری مکان را به‌عنوان مشخص کردن منطقه‌ای که نتایج باید نزدیک آن باشند درنظر بگیرید. تفاوت کلیدی این است که با سوگیری مکان، نتایج خارج از منطقه مشخص‌شده ممکن است همچنان برگردانده شود.

    • سوگیری مکان

      منطقه‌ای را برای جستجو مشخص می‌کند. این مکان به‌عنوان گرایش عمل می‌کند، نه محدودیت، بنابراین نتایج خارج از منطقه مشخص‌شده ممکن است همچنان برگردانده شود.

      برای تنظیم پارامتر سوگیری مکان، هنگام ساختن شیء FindAutocompletePredictionsRequest، روش setLocationBias() را فراخوانی کنید.

    • محدودیت مکان

      منطقه‌ای را برای جستجو مشخص می‌کند. نتایج خارج از منطقه مشخص‌شده برگردانده نمی‌شود.

      برای تنظیم پارامتر محدودیت مکان، هنگام ساختن شیء FindAutocompletePredictionsRequest، روش setLocationRestriction() را فراخوانی کنید.

    منطقه سوگیری مکان یا محدودیت مکان را به‌صورت «نمای مستطیلی» یا دایره مشخص کنید.

    • دایره با نقطه مرکزی و شعاع برحسب متر تعریف می‌شود. شعاع باید بین ۰٫۰ و ۵۰۰۰۰٫۰ باشد و می‌تواند این دو عدد را نیز دربر بگیرد. مقدار پیش‌فرض ۰٫۰ است. برای محدودیت مکان، باید شعاع را روی مقداری بزرگ‌تر از ۰٫۰ تنظیم کنید. درغیراین‌صورت، درخواست هیچ نتیجه‌ای برنمی‌گرداند.

    • مستطیل نمای درگاه طول و عرض جغرافیایی است که به‌صورت دو نقطه low و high در مقابل قطری نشان داده می‌شود. ناحیه نمایش به‌عنوان یک منطقه بسته درنظر گرفته می‌شود، یعنی مرز آن را دربرمی‌گیرد. محدوده عرض جغرافیایی باید بین ۹۰- تا ۹۰ درجه (شامل این مقادیر) باشد، و محدوده طول جغرافیایی باید بین ۱۸۰- تا ۱۸۰ درجه (شامل این مقادیر) باشد:

      • اگر low = high، ناحیه نمایش از آن نقطه واحد تشکیل می‌شود.
      • اگر low.longitude > high.longitude، محدوده طول جغرافیایی معکوس می‌شود (ناحیه نمایش از خط طول جغرافیایی ۱۸۰ درجه عبور می‌کند).
      • اگر low.longitude = -۱۸۰ درجه و high.longitude = ۱۸۰ درجه باشد، درگاه دید همه طول‌های جغرافیایی را دربرمی‌گیرد.
      • اگر low.longitude = ۱۸۰ درجه و high.longitude = ۱۸۰- درجه باشد، محدوده طول جغرافیایی خالی است.

      هر دو low و high باید پر شوند و کادر نشان‌داده‌شده نباید خالی باشد. درگاه دید خالی منجر به خطا می‌شود.

  • مبدأ

    نقطه مبدأ که فاصله مستقیم تا مقصد از آن محاسبه می‌شود (بااستفاده از getDistanceMeters() قابل‌دسترسی است). اگر این مقدار حذف شود، فاصله مستقیم برگردانده نخواهد شد. باید به‌صورت مختصات طول و عرض جغرافیایی مشخص شود:

    برای تنظیم پارامتر مبدأ، هنگام ساختن شیء FindAutocompletePredictionsRequest، روش setOrigin() را فراخوانی کنید.

  • کد منطقه

    کد منطقه استفاده‌شده برای قالب‌بندی پاسخ، ازجمله قالب‌بندی نشانی، که به‌صورت مقدار دو نویسه‌ای ccTLD («دامنه سطح بالا») مشخص شده است. اکثر کدهای ccTLD با کدهای ISO 3166-1 یکسان هستند، با چند استثنای قابل‌توجه. برای مثال، دامنه سطح بالای کد کشور پادشاهی متحد «uk»‏ (co.uk.) است، درحالی‌که کد ISO 3166-1 آن «gb» است (ازنظر فنی برای نهاد «پادشاهی متحد بریتانیای کبیر و ایرلند شمالی»).

    اگر کد منطقه نامعتبری را مشخص کنید، API خطای INVALID_ARGUMENT برمی‌گرداند. این پارامتر می‌تواند بر نتایج براساس قانون ذی‌ربط تأثیر بگذارد.

    برای تنظیم پارامتر کد منطقه، هنگام ساختن شیء FindAutocompletePredictionsRequest، روش setRegionCode() را فراخوانی کنید.

  • داده‌واحد جلسه

    کدهای جلسه رشته‌های تولیدشده توسط کاربر هستند که تماس‌های «تکمیل خودکار (جدید)» را (هم تماس‌های برقرارشده ازطریق ابزاره و هم تماس‌های برنامه‌ای) به‌عنوان «جلسه» ردیابی می‌کنند. «تکمیل خودکار» از کد جلسه برای گروه‌بندی مراحل پُرسمان و انتخاب جستجوی تکمیل خودکار کاربر در یک جلسه مجزا برای اهداف صورت‌حساب استفاده می‌کند. جلسه زمانی شروع می‌شود که کاربر شروع به تایپ کردن پُرسمان می‌کند و زمانی پایان می‌یابد که مکانی را انتخاب می‌کند. هر جلسه می‌تواند چندین پُرسمان داشته باشد که به‌دنبال آن یک مکان انتخاب می‌شود. وقتی جلسه‌ای به پایان می‌رسد، کد دیگر معتبر نیست؛ برنامه‌تان باید برای هر جلسه کد جدیدی تولید کند. توصیه می‌کنیم برای همه جلسه‌های تکمیل خودکار برنامه‌ریزی‌شده از نشان‌های جلسه استفاده کنید (وقتی تکه‌ای را جاسازی می‌کنید یا تکمیل خودکار را بااستفاده از هدف راه‌اندازی می‌کنید، API به‌طور خودکار از این کار مراقبت می‌کند).

    «تکمیل خودکار» از AutocompleteSessionToken برای شناسایی هر جلسه استفاده می‌کند. برنامه شما باید با شروع هر جلسه جدید، نشانه جلسه جدیدی را ارسال کند، سپس همان نشانه را به‌همراه «شناسه مکان» در تماس بعدی با fetchPlace() ارسال کند تا «جزئیات مکان» برای مکانی که کاربر انتخاب کرده است بازیابی شود.

    برای تنظیم پارامتر کد جلسه، هنگام ساختن شیء FindAutocompletePredictionsRequest، روش setSessionToken() را فراخوانی کنید.

    برای اطلاعات بیشتر، به کدهای جلسه مراجعه کنید.

نمونه‌های تکمیل خودکار (جدید)

استفاده از محدودیت مکان و سوگیری مکان

«تکمیل خودکار» (جدید) به‌طور پیش‌فرض از «انحراف IP» برای کنترل کردن ناحیه جستجو استفاده می‌کند. با سوگیری نشانی IP، میانای برنامه‌سازی کاربردی از نشانی IP دستگاه برای سوگیری نتایج استفاده می‌کند. می‌توانید به‌دلخواه از محدودیت مکانی یا سوگیری مکانی (اما نه هر دو) برای مشخص کردن ناحیه جستجو استفاده کنید.

محدودیت مکان ناحیه جستجو را مشخص می‌کند. نتایج خارج از منطقه مشخص‌شده برگردانده نمی‌شود. مثال زیر از محدودیت مکان برای محدود کردن درخواست به محدودیت مکان دایره‌ای با شعاع ۵۰۰۰ متر با مرکزیت سان فرانسیسکو استفاده می‌کند:

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 فهرست شده است استفاده کنید. می‌توانید آرایه‌ای با حداکثر پنج مقدار مشخص کنید. اگر حذف شود، همه انواع برگردانده می‌شود.

مثال زیر رشته پُرسمان «فوتبال» را مشخص می‌کند و از پارامتر انواع اصلی برای محدود کردن نتایج به مؤسسه‌های نوع "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".

استفاده از مبدأ

وقتی پارامتر مبدأ را در درخواست اضافه می‌کنید، که به‌صورت مختصات عرض و طول جغرافیایی مشخص شده است، API فاصله خط مستقیم از مبدأ تا مقصد را در پاسخ اضافه می‌کند (بااستفاده از 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 است.
  • از همان ابتدا با فیلدهای داده ضروری «تکمیل خودکار» (جدید) آشنا شوید.
  • فیلدهای سوگیری مکان و محدودیت مکان اختیاری هستند اما می‌توانند تأثیر قابل‌توجهی بر عملکرد تکمیل خودکار داشته باشند.
  • از مدیریت خطا استفاده کنید تا مطمئن شوید اگر میانای برنامه‌سازی کاربردی خطا برگرداند، برنامه شما به‌خوبی تنزل می‌یابد.
  • مطمئن شوید که برنامه‌تان شرایطی را که هیچ انتخابی وجود ندارد مدیریت می‌کند و راهی برای ادامه دادن به کاربران ارائه می‌دهد.

روال‌های مطلوب بهینه‌سازی هزینه

بهینه‌سازی هزینه پایه

برای بهینه‌سازی هزینه استفاده از سرویس «تکمیل خودکار (جدید)»، از ماسک‌های فیلد در ابزاره‌های «جزئیات مکان (جدید)» و «تکمیل خودکار (جدید)» استفاده کنید تا فقط فیلدهای داده «تکمیل خودکار (جدید)» موردنیازتان برگردانده شود.

بهینه‌سازی پیشرفته هزینه

برای دسترسی به واحد نگهداری موجودی: قیمت‌گذاری درخواست «تکمیل خودکار» و درخواست نتایج Geocoding API درباره مکان انتخاب‌شده به‌جای «جزئیات مکان» (جدید)، پیاده‌سازی برنامه‌ای «تکمیل خودکار» (جدید) را درنظر بگیرید. اگر هر دو شرط زیر برقرار باشد، قیمت‌گذاری به‌ازای هر درخواست همراه با «میانای برنامه‌سازی کاربردی زمین‌کدیابی» نسبت‌به قیمت‌گذاری به‌ازای هر جلسه (جلسه‌محور) مقرون‌به‌صرفه‌تر است:

  • اگر فقط به طول و عرض جغرافیایی یا نشانی مکان انتخابی کاربر نیاز دارید، Geocoding API این اطلاعات را با هزینه کمتری نسبت‌به فراخوانی Place Details (New)‎ ارائه می‌دهد.
  • اگر کاربران پیش‌بینی تکمیل خودکار را به‌طور میانگین در چهار درخواست پیش‌بینی «تکمیل خودکار» (جدید) یا کمتر انتخاب کنند، قیمت‌گذاری براساس درخواست می‌تواند مقرون‌به‌صرفه‌تر از قیمت‌گذاری براساس جلسه باشد.
برای دریافت راهنمایی در انتخاب پیاده‌سازی «تکمیل خودکار (جدید)» که مناسب نیازهایتان باشد، برگه‌ای را که با پاسخ شما به سؤال زیر مطابقت دارد انتخاب کنید.

آیا برنامه شما به اطلاعات دیگری غیراز نشانی و طول/عرض جغرافیایی پیش‌بینی انتخابی نیاز دارد؟

بله، به جزئیات بیشتری نیاز است

از «تکمیل خودکار» (جدید) مبتنی بر جلسه با «جزئیات مکان» (جدید) استفاده کنید.
ازآنجایی‌که برنامه شما به «جزئیات مکان (جدید)» مثل نام مکان، وضعیت کسب‌وکار، یا ساعات کاری نیاز دارد، پیاده‌سازی «تکمیل خودکار (جدید)» شما باید از نشانه جلسه (برنامه‌ریزی‌شده یا ساخته‌شده در JavaScript، Android، یا ابزارک‌های iOS ) استفاده کند به‌ازای هر جلسه به‌علاوه واحدهای نگهداری انبار «مکان‌ها» ذی‌ربط، بسته به اینکه کدام فیلدهای داده مکان را درخواست می‌کنید.۱

پیاده‌سازی ابزاره
مدیریت جلسه به‌طور خودکار در ابزاره‌های JavaScript، Android، یا iOS ساخته می‌شود. این شامل درخواست‌های «تکمیل خودکار» (جدید) و درخواست «جزئیات مکان» (جدید) در پیش‌بینی انتخاب‌شده می‌شود. حتماً پارامتر fields را مشخص کنید تا مطمئن شوید فقط فیلدهای داده تکمیل خودکار (جدید) موردنیازتان را درخواست می‌کنید.

پیاده‌سازی برنامه‌ریزی‌شده
از کد جلسه با درخواست‌های «تکمیل خودکار» (جدید) استفاده کنید. هنگام درخواست «جزئیات مکان (جدید)» درباره پیش‌بینی انتخاب‌شده، پارامترهای زیر را اضافه کنید:

  1. شناسه جا از پاسخ «تکمیل خودکار» (جدید)
  2. کد جلسه استفاده‌شده در درخواست «تکمیل خودکار (جدید)»
  3. پارامتر fields که فیلدهای داده «تکمیل خودکار (جدید)» موردنیازتان را مشخص می‌کند

نه، فقط به نشانی و مکان نیاز دارد

Geocoding API می‌تواند گزینه مقرون‌به‌صرفه‌تری نسبت‌به Place Details (New) برای برنامه شما باشد، بسته به عملکرد استفاده شما از Autocomplete (New). کارایی «تکمیل خودکار (جدید)» هر برنامه بسته به آنچه کاربران وارد می‌کنند، مکان استفاده از برنامه، و اینکه آیا روال‌های مطلوب بهینه‌سازی عملکرد پیاده‌سازی شده است یا نه متفاوت است.

برای پاسخ دادن به سؤال زیر، تجزیه‌وتحلیل کنید که کاربر به‌طور میانگین چند نویسه تایپ می‌کند تا پیش‌بینی «تکمیل خودکار (جدید)» را در برنامه‌تان انتخاب کند.

آیا کاربران شما به‌طور میانگین در چهار درخواست یا کمتر، پیش‌بینی «تکمیل خودکار (جدید)» را انتخاب می‌کنند؟

بله

«تکمیل خودکار» را به‌صورت برنامه‌نویسی بدون نشان‌های جلسه پیاده‌سازی کنید و «میانای برنامه‌سازی کاربردی» «مکان‌گذاری جغرافیایی» را در پیش‌بینی مکان انتخاب‌شده فراخوانی کنید.
Geocoding API نشانی‌ها و مختصات طول/عرض جغرافیایی را ارائه می‌دهد. انجام چهار درخواست درخواست تکمیل خودکار به‌علاوه یک تماس Geocoding API درباره پیش‌بینی مکان انتخابی کمتر از هزینه «تکمیل خودکار» (جدید) به‌ازای هر جلسه است.۱

بهترین روش‌های عملکرد را به‌کار بگیرید تا به کاربران کمک کنید پیش‌بینی موردنظرشان را با نویسه‌های کمتری دریافت کنند.

نه

از «تکمیل خودکار مبتنی بر جلسه» (جدید) با «جزئیات مکان» (جدید) استفاده کنید.
ازآنجایی‌که میانگین تعداد درخواست‌هایی که انتظار دارید قبل‌از اینکه کاربر پیش‌بینی «تکمیل خودکار (جدید)» را انتخاب کند، از هزینه قیمت‌گذاری هر جلسه فراتر می‌رود، پیاده‌سازی شما از «تکمیل خودکار (جدید)» باید از یک کد جلسه برای هر دو درخواست «تکمیل خودکار (جدید)» و درخواست مرتبط «جزئیات مکان (جدید)» استفاده کند. هر جلسه. ۱

پیاده‌سازی ابزاره
مدیریت جلسه به‌طور خودکار در ابزاره‌های JavaScript، Android، یا iOS ساخته می‌شود. این شامل درخواست‌های «تکمیل خودکار» (جدید) و درخواست «جزئیات مکان» (جدید) در پیش‌بینی انتخاب‌شده می‌شود. حتماً پارامتر fields را مشخص کنید تا مطمئن شوید فقط فیلدهای موردنیازتان را درخواست می‌کنید.

پیاده‌سازی برنامه‌ریزی‌شده
از کد جلسه با درخواست‌های «تکمیل خودکار» (جدید) استفاده کنید. هنگام درخواست «جزئیات مکان (جدید)» درباره پیش‌بینی انتخاب‌شده، پارامترهای زیر را اضافه کنید:

  1. شناسه جا از پاسخ «تکمیل خودکار» (جدید)
  2. کد جلسه استفاده‌شده در درخواست «تکمیل خودکار (جدید)»
  3. پارامتر fields که فیلدهایی مثل نشانی و هندسه را مشخص می‌کند

به‌تأخیر انداختن درخواست‌های «تکمیل خودکار» (جدید) را مدنظر قرار دهید
می‌توانید از استراتژی‌هایی مانند به‌تأخیر انداختن درخواست «تکمیل خودکار» (جدید) تا زمانی که کاربر سه یا چهار نویسه اول را تایپ کند استفاده کنید تا برنامه‌تان درخواست‌های کمتری ارسال کند. برای مثال، ارسال درخواست‌های «تکمیل خودکار (جدید)» برای هر نویسه پس‌از اینکه کاربر نویسه سوم را تایپ کرد به این معنی است که اگر کاربر هفت نویسه تایپ کند و سپس پیش‌بینی‌ای را انتخاب کند که برای آن یک درخواست Geocoding API ارسال می‌کنید، هزینه کل برای ۴ درخواست «تکمیل خودکار (جدید)» به‌ازای هر درخواست + Geocoding خواهد بود.۱

اگر با به‌تأخیر انداختن درخواست‌ها می‌توانید میانگین درخواست‌های برنامه‌ریزی‌شده را به زیر چهار برسانید، می‌توانید راهنمای پیاده‌سازی «تکمیل خودکار (جدید)» با Geocoding API را دنبال کنید. توجه داشته باشید که تأخیر در درخواست‌ها می‌تواند ازسوی کاربر به‌عنوان تأخیر درک شود، زیرا ممکن است کاربر انتظار داشته باشد با هر ضربه کلید جدید، پیش‌بینی‌ها را ببیند.

برای کمک به کاربران در دریافت پیش‌بینی موردنظرشان با نویسه‌های کمتر، روال‌های مطلوب عملکرد را به‌کار بگیرید.

  1. برای اطلاع از هزینه‌ها، فهرست‌های قیمت‌گذاری «پلاتفرم Google Maps» را ببینید.

روال‌های مطلوب عملکرد

دستورالعمل‌های زیر روش‌های بهینه‌سازی عملکرد «تکمیل خودکار (جدید)» را شرح می‌دهد:

  • محدودیت‌های کشور، سوگیری مکان، و (برای پیاده‌سازی‌های برنامه‌ای) اولویت زبان را به پیاده‌سازی «تکمیل خودکار» (جدید) خود اضافه کنید. اولویت زبان برای ابزارک‌ها لازم نیست زیرا اولویت‌های زبان را از مرورگر یا دستگاه همراه کاربر انتخاب می‌کنند.
  • اگر «تکمیل خودکار (جدید)» با نقشه همراه باشد، می‌توانید مکان را براساس نمای نقشه سوگیری کنید.
  • در شرایطی که کاربر یکی از پیش‌بینی‌های Autocomplete (New) را انتخاب نمی‌کند، معمولاً به این دلیل که هیچ‌کدام از آن پیش‌بینی‌ها نشانی نتیجه موردنظر نیست، می‌توانید از ورودی اصلی کاربر مجدداً استفاده کنید تا نتایج مرتبط‌تری دریافت کنید:
    • اگر انتظار دارید کاربر فقط اطلاعات نشانی را وارد کند، ورودی کاربر اصلی را در تماس با Geocoding API دوباره استفاده کنید.
    • اگر انتظار دارید کاربر پُرسمان‌های مربوط به مکان خاصی را براساس نام یا نشانی وارد کند، از درخواست «جزئیات مکان (جدید)» استفاده کنید. اگر انتظار می‌رود نتایج فقط در منطقه خاصی باشد، از گرایش مکان استفاده کنید.
    سایر سناریوهایی که در آن‌ها بهتر است به 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 تعریف شده است محدود کنید. این به «تکمیل خودکار» (جدید) دستور می‌دهد فقط نتایج درون آن منطقه را برگرداند.