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

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

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

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

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

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

برنامه شما می‌تواند با فراخوانی PlacesClient.findAutocompletePredictions() و ارسال یک شی FindAutocompletePredictionsRequest ، فهرستی از نام‌های مکان و/یا آدرس‌های پیش‌بینی‌شده را از API تکمیل خودکار دریافت کند. مثال زیر یک تماس کامل با 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) متن اصلی را که یک مکان را توصیف می کند، برمی گرداند. این معمولاً نام مکان است. به عنوان مثال: " برج ایفل " و " خیابان پیت 123 ".
  • getSecondaryText(CharacterStyle) متن فرعی توضیحات مکان را برمی گرداند. این برای مثال به عنوان خط دوم هنگام نمایش پیش‌بینی‌های تکمیل خودکار مفید است. مثال‌ها: « خیابان آناتول فرانسه، پاریس، فرانسه » و « سیدنی، نیو ساوت ولز ».
  • getPlaceId() شناسه مکان مکان پیش بینی شده را برمی گرداند. شناسه مکان یک شناسه متنی است که مکان را به طور منحصربه‌فرد شناسایی می‌کند و می‌توانید بعداً از آن برای بازیابی مجدد شی Place استفاده کنید. برای اطلاعات بیشتر درباره شناسه‌های مکان در تکمیل خودکار، به جزئیات مکان (جدید) مراجعه کنید. برای اطلاعات کلی درباره شناسه مکان، به نمای کلی شناسه مکان مراجعه کنید.
  • getTypes() لیستی از انواع مکان های مرتبط با این مکان را برمی گرداند.
  • getDistanceMeters() فاصله خط مستقیم را بر حسب متر بین این مکان و مبدا مشخص شده در درخواست برمی گرداند.

پارامترهای مورد نیاز

  • پرس و جو

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

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

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

  • انواع اولیه

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

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

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

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

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

  • کشورها

    فقط شامل نتایج از لیست کشورهای مشخص شده است، که به عنوان لیستی با حداکثر 15 ccTLD ("دامنه سطح بالا") دو نویسه مشخص شده است. در صورت حذف، هیچ محدودیتی برای پاسخ اعمال نمی شود. به عنوان مثال، برای محدود کردن مناطق به آلمان و فرانسه:

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

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

  • افست ورودی

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

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

  • تعصب مکان یا محدودیت مکان

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

    • تعصب مکان

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

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

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

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

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

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

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

    • مستطیل یک نمای عرض-طول جغرافیایی است که به صورت دو نقطه low و high به صورت مورب در مقابل هم نمایش داده می شود. یک viewport یک منطقه بسته در نظر گرفته می شود، به این معنی که شامل مرز آن می شود. محدوده عرض جغرافیایی باید بین 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" است (از لحاظ فنی برای نهاد "پادشاهی متحده بریتانیای کبیر و ایرلند شمالی").

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

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

  • نشانه جلسه

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

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

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

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

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

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

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

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

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

مثال زیر یک رشته جستجو از "فوتبال" را مشخص می کند و از پارامتر انواع اولیه برای محدود کردن نتایج به تاسیساتی از نوع "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());
        })
    );

اسناد

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