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

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

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

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

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

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

پُرسمان

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

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

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

انواع اصلی

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

هر مکان فقط می‌تواند یک نوع اصلی از انواع جدول الف یا جدول ب مرتبط با آن داشته باشد. برای مثال، نوع اصلی ممکن است "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());
        })
    );

استفاده از انواع اصلی

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

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

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

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

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

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

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

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

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

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

«تکمیل خودکار» (جدید) مبتنی بر جلسه با «جزئیات مکان» (جدید)

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

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

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

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

Per-request Autocomplete (New) with the Geocoding API

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

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

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

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

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

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

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

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

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

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

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

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

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

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