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

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

این صفحه کتابخانه سمت کارخواه دردسترس با Maps JavaScript API را شرح می‌دهد. اگر می‌خواهید با سرویس وب «میانای برنامه‌سازی کاربردی مکان‌ها» در سرورتان کار کنید، کارخواه Node.js برای سرویس‌های Google Maps را ببینید. صفحه آن پیوند همچنین «کارخواه Java»، «کارخواه Python»، و «کارخواه Go» را برای «سرویس‌های Google Maps» معرفی می‌کند.

مقدمه

«تکمیل خودکار» یکی از ویژگی‌های کتابخانه «مکان‌ها» در Maps JavaScript API است. می‌توانید از تکمیل خودکار استفاده کنید تا به برنامه‌هایتان رفتار جستجوی پیش‌از تایپ فیلد جستجوی Google Maps را بدهید. سرویس تکمیل خودکار می‌تواند براساس کلمات کامل و زیررشته‌ها مطابقت پیدا کند و نام مکان‌ها، نشانی‌ها، و کدهای پلاس را حل کند. بنابراین برنامه‌ها می‌توانند هم‌زمان با تایپ کاربر پُرسمان ارسال کنند تا پیش‌بینی‌های مکان را درجا ارائه دهند. طبق تعریف «میانای برنامه‌سازی کاربردی مکان‌ها»، «مکان» می‌تواند یک مؤسسه، یک مکان جغرافیایی، یا یک نقطه موردعلاقه برجسته باشد.

درحال شروع کردن

قبل‌از استفاده از کتابخانه «مکان‌ها» در Maps JavaScript API، ابتدا تأیید کنید که Places API در کنسول Google Cloud، در همان پروژه‌ای که برای Maps JavaScript API راه‌اندازی کرده‌اید، فعال باشد.

برای مشاهده فهرست میاناهای برنامه‌سازی کاربردی فعال‌شده:

  1. به کنسول Google Cloud بروید.
  2. روی دکمه انتخاب پروژه کلیک کنید، سپس همان پروژه‌ای را که برای «میانای برنامه‌سازی کاربردی جاوا اسکریپت در Maps» راه‌اندازی کرده‌اید انتخاب کنید و روی باز کردن کلیک کنید.
  3. از فهرست میاناهای برنامه‌سازی کاربردی در داشبورد، میانای برنامه‌سازی کاربردی مکان‌ها را پیدا کنید.
  4. اگر API را در فهرست می‌بینید، همه چیز آماده است. بااین‌حال، این پروژه در وضعیت «قدیمی» است. برای اطلاعات بیشتر درباره مرحله «قدیمی» و نحوه انتقال از «قدیمی» به سرویس‌های جدیدتر، محصولات و ویژگی‌های قدیمی را ببینید. برای ابزارک‌های تکمیل خودکار و SearchBox استثنایی وجود دارد که هنوز به‌عنوان محصول GA در «میانای برنامه‌سازی کاربردی مکان‌ها (جدید)» دردسترس نیستند.

بار کردن کتابخانه

سرویس «مکان‌ها» کتابخانه‌ای خوداتکا است که از کد اصلی Maps JavaScript API جدا است. برای استفاده از ویژگی‌های موجود در این کتابخانه، ابتدا باید آن را بااستفاده از libraries پارامتر در نشانی وب راه‌اندازی Maps API بار کنید:

<script async
    src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&loading=async&libraries=places&callback=initMap">
</script>

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

خلاصه کلاس‌ها

این API دو نوع ابزارک تکمیل خودکار ارائه می‌دهد که می‌توانید بااستفاده از کلاس‌های Autocomplete و SearchBox به ترتیب آن‌ها را اضافه کنید. علاوه‌براین، می‌توانید از کلاس AutocompleteService برای بازیابی نتایج تکمیل خودکار به‌صورت برنامه‌ریزی‌شده استفاده کنید (به «مرجع Maps JavaScript API»: کلاس AutocompleteService مراجعه کنید).

در زیر خلاصه‌ای از کلاس‌های دردسترس آمده است:

  • Autocomplete فیلد ورودی نوشتاری را به صفحه وب شما اضافه می‌کند، و آن فیلد را برای ورودی‌های نویسه پایش می‌کند. وقتی کاربر نوشتار وارد می‌کند، تکمیل خودکار پیش‌بینی‌های مکان را به‌صورت فهرست کرکره‌ای برمی‌گرداند. وقتی کاربر مکانی را از فهرست انتخاب می‌کند، اطلاعات مربوط به آن مکان به شیء تکمیل خودکار برگردانده می‌شود و برنامه شما می‌تواند آن را بازیابی کند. جزئیات را در زیر ببینید.
    فیلد نوشتاری تکمیل خودکار و فهرست انتخاب پیش‌بینی‌های مکان که با وارد کردن پُرسمان جستجو توسط کاربر ارائه می‌شود.
    شکل ۱: فیلد نوشتار تکمیل خودکار و فهرست انتخاب
    فرم نشانی تکمیل‌شده.
    شکل ۲: فرم نشانی تکمیل‌شده
  • SearchBox فیلد ورودی نوشتار را به صفحه وب شما اضافه می‌کند، به همان روش Autocomplete. تفاوت‌ها به شرح زیر است:
    • تفاوت اصلی در نتایجی است که در فهرست انتخاب ظاهر می‌شود. SearchBox فهرست گسترده‌ای از پیش‌بینی‌ها را ارائه می‌دهد که می‌تواند شامل مکان‌ها (طبق تعریف Places API) و همچنین عبارت‌های جستجوی پیشنهادی باشد. برای مثال، اگر کاربر عبارت «پیتزا در تهران» را وارد کند، فهرست انتخاب ممکن است عبارت «پیتزا در تهران» و همچنین نام‌های مختلف پیتزافروشی‌ها را شامل شود.
    • ‫SearchBox نسبت به Autocomplete گزینه‌های کمتری برای محدود کردن جستجو ارائه می‌دهد. در حالت اول، می‌توانید جستجو را به‌سمت LatLngBounds خاصی متمایل کنید. در مورد دوم، می‌توانید جستجو را به کشور خاص و انواع مکان خاص محدود کنید و همچنین محدوده‌ها را تنظیم کنید. برای اطلاعات بیشتر، به زیر مراجعه کنید.
    فرم نشانی تکمیل‌شده.
    شکل ۳: «چارگوش جستجو» عبارات جستجو و پیش‌بینی‌های مکان را ارائه می‌دهد.
    جزئیات را در زیر ببینید.
  • می‌توانید شیء AutocompleteService ایجاد کنید تا پیش‌بینی‌ها را به‌صورت برنامه‌نویسی بازیابی کنید. برای بازیابی مکان‌های منطبق، با getPlacePredictions() تماس بگیرید، یا برای بازیابی مکان‌های منطبق به‌علاوه عبارت‌های جستجوی پیشنهادی، با getQueryPredictions() تماس بگیرید. توجه: AutocompleteService هیچ کنترل واسط کاربری اضافه نمی‌کند. درعوض، روش‌های بالا آرایه‌ای از اشیای پیش‌بینی را برمی‌گردانند. هر شیء پیش‌بینی حاوی نوشتار پیش‌بینی، و همچنین اطلاعات مرجع و جزئیات مربوط به نحوه مطابقت نتیجه با ورودی کاربر است. جزئیات را در زیر ببینید.

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

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

سازنده Autocomplete دو آرگومان می‌گیرد:

  • عنصر HTML input از نوع text. این فیلد ورودی است که سرویس تکمیل خودکار آن را پایش می‌کند و نتایجش را به آن پیوست می‌کند.
  • یک آرگومان اختیاری AutocompleteOptions که می‌تواند شامل ویژگی‌های زیر باشد:
    • آرایه‌ای از داده‌های fields که باید در پاسخ Place Details برای PlaceResult انتخاب‌شده کاربر گنجانده شود. اگر دارایی تنظیم نشده باشد یا اگر ['ALL'] ارسال شود، همه فیلدهای دردسترس برگردانده می‌شوند و هزینه آن‌ها محاسبه می‌شود (این کار برای استقرار تولید توصیه نمی‌شود). برای فهرست فیلدها، PlaceResult را ببینید.
    • آرایه‌ای از types که نوع صریح یا مجموعه نوع را مشخص می‌کند، همان‌طور که در انواع پشتیبانی‌شده فهرست شده است. اگر نوعی مشخص نشده باشد، همه انواع برگردانده می‌شوند.
    • ‫bounds یک شیء google.maps.LatLngBounds است که منطقه‌ای را که باید در آن مکان‌ها را جستجو کرد مشخص می‌کند. نتایج به مکان‌های درون این محدوده گرایش دارد، اما به آن‌ها محدود نمی‌شود.
    • ‫strictBounds یک boolean است که مشخص می‌کند آیا «میانای برنامه‌سازی کاربردی» باید فقط مکان‌هایی را برگرداند که دقیقاً در منطقه تعریف‌شده توسط bounds داده‌شده قرار دارند یا نه. این «میانای برنامه‌سازی کاربردی» نتایج خارج از این منطقه را برنمی‌گرداند، حتی اگر با ورودی کاربر مطابقت داشته باشند.
    • از componentRestrictions می‌توان برای محدود کردن نتایج به گروه‌های خاص استفاده کرد. می‌توانید از componentRestrictions برای فیلتر کردن حداکثر ۵ کشور استفاده کنید. کشورها باید به‌عنوان کد کشور دوحرفی سازگار با ISO 3166-1 Alpha-2 ارسال شوند. چندین کشور باید به‌عنوان فهرستی از کدهای کشور ارسال شوند.

      توجه: اگر با کد کشور نتایج غیرمنتظره‌ای دریافت کردید، بررسی کنید که از کدی استفاده می‌کنید که شامل کشورها، مناطق وابسته، و مناطق ویژه موردنظر شما باشد. می‌توانید اطلاعات کد را در ویکی‌پدیا: فهرست کدهای کشور استاندارد سازمان بین‌المللی استانداردسازی ۳۱۶۶ یا پلاتفرم مرور آنلاین استاندارد سازمان بین‌المللی استانداردسازی پیدا کنید.

    • از placeIdOnly می‌توان برای دستور دادن به ابزارک Autocomplete استفاده کرد تا فقط «شناسه‌های مکان» را بازیابی کند. در تماس با getPlace() در شیء Autocomplete، PlaceResult دردسترس قرارگرفته فقط ویژگی‌های place id، types، و name را تنظیم خواهد کرد. می‌توانید از شناسه مکان برگشتی در تماس با سرویس‌های «مکان‌ها»، «زمین‌کدینگ»، «مسیرها»، یا «ماتریس فاصله» استفاده کنید.

محدود کردن پیش‌بینی‌های «تکمیل خودکار»

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

تنظیم گزینه‌ها در زمان ساخت

سازنده Autocomplete پارامتر AutocompleteOptions را برای تنظیم محدودیت‌ها در زمان ایجاد ابزارک می‌پذیرد. مثال زیر گزینه‌های bounds،‏ componentRestrictions، و types را روی درخواست مکان‌های نوع establishment تنظیم می‌کند و مکان‌های داخل منطقه جغرافیایی مشخص‌شده را ترجیح می‌دهد و پیش‌بینی‌ها را به مکان‌های داخل ایالات متحده محدود می‌کند. تنظیم گزینه fields مشخص می‌کند چه اطلاعاتی درباره مکان انتخابی کاربر برگردانده شود.

برای تغییر مقدار گزینه ابزاره موجود، با setOptions() تماس بگیرید.

TypeScript

const center = { lat: 50.064192, lng: -130.605469 };
// Create a bounding box with sides ~10km away from the center point
const defaultBounds = {
  north: center.lat + 0.1,
  south: center.lat - 0.1,
  east: center.lng + 0.1,
  west: center.lng - 0.1,
};
const input = document.getElementById("pac-input") as HTMLInputElement;
const options = {
  bounds: defaultBounds,
  componentRestrictions: { country: "us" },
  fields: ["address_components", "geometry", "icon", "name"],
  strictBounds: false,
};

const autocomplete = new google.maps.places.Autocomplete(input, options);

JavaScript

const center = { lat: 50.064192, lng: -130.605469 };
// Create a bounding box with sides ~10km away from the center point
const defaultBounds = {
  north: center.lat + 0.1,
  south: center.lat - 0.1,
  east: center.lng + 0.1,
  west: center.lng - 0.1,
};
const input = document.getElementById("pac-input");
const options = {
  bounds: defaultBounds,
  componentRestrictions: { country: "us" },
  fields: ["address_components", "geometry", "icon", "name"],
  strictBounds: false,
};
const autocomplete = new google.maps.places.Autocomplete(input, options);

مشخص کردن فیلدهای داده

فیلدهای داده را مشخص کنید تا برای واحد نگهداری موجودی داده‌های مکان که نیاز ندارید صورت‌حساب دریافت نکنید. دارایی fields را در AutocompleteOptions که به سازنده ابزاره منتقل می‌شود اضافه کنید، همان‌طور که در مثال قبلی نشان داده شده است، یا setFields() را در شیء Autocomplete موجود فراخوانی کنید.

autocomplete.setFields(["place_id", "geometry", "name"]);

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

می‌توانید نتایج تکمیل خودکار را به‌نفع مکان یا ناحیه تقریبی به روش‌های زیر متمایل کنید:

  • محدودیت‌هایی برای ایجاد شیء Autocomplete تنظیم کنید.
  • محدوده‌های Autocomplete موجود را تغییر دهید.
  • محدوده‌ها را روی ناحیه نمایش نقشه تنظیم کنید.
  • جستجو را به محدوده‌ها محدود کنید.
  • جستجو را به یک کشور خاص محدود کنید.

مثال قبلی تنظیم محدوده‌ها را در زمان ایجاد نشان می‌دهد. مثال‌های زیر تکنیک‌های دیگر سوگیری را نشان می‌دهند.

تغییر دادن محدوده‌های «تکمیل خودکار» موجود

برای تغییر دادن محدوده جستجو در Autocomplete موجود به محدوده مستطیلی، با setBounds() تماس بگیرید.

TypeScript

const southwest = { lat: 5.6108, lng: 136.589326 };
const northeast = { lat: 61.179287, lng: 2.64325 };
const newBounds = new google.maps.LatLngBounds(southwest, northeast);

autocomplete.setBounds(newBounds);

JavaScript

const southwest = { lat: 5.6108, lng: 136.589326 };
const northeast = { lat: 61.179287, lng: 2.64325 };
const newBounds = new google.maps.LatLngBounds(southwest, northeast);

autocomplete.setBounds(newBounds);
تنظیم مرزها برای ناحیه نمایش نقشه

از bindTo() برای گرایش دادن نتایج به ناحیه نمایش نقشه استفاده کنید، حتی وقتی ناحیه نمایش تغییر می‌کند.

TypeScript

autocomplete.bindTo("bounds", map);

JavaScript

autocomplete.bindTo("bounds", map);

از unbind() برای لغو اتصال پیش‌بینی‌های «تکمیل خودکار» از درگاه دید نقشه استفاده کنید.

TypeScript

autocomplete.unbind("bounds");
autocomplete.setBounds({ east: 180, west: -180, north: 90, south: -90 });

JavaScript

autocomplete.unbind("bounds");
autocomplete.setBounds({ east: 180, west: -180, north: 90, south: -90 });

مشاهده مثال

محدود کردن جستجو به محدوده کنونی

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

autocomplete.setOptions({ strictBounds: true });
محدود کردن پیش‌بینی‌ها به یک کشور خاص

از گزینه componentRestrictions استفاده کنید یا با setComponentRestrictions() تماس بگیرید تا جستجوی تکمیل خودکار را به مجموعه خاصی از حداکثر پنج کشور محدود کنید.

TypeScript

autocomplete.setComponentRestrictions({
  country: ["us", "pr", "vi", "gu", "mp"],
});

JavaScript

autocomplete.setComponentRestrictions({
  country: ["us", "pr", "vi", "gu", "mp"],
});

مشاهده مثال

محدود کردن انواع مکان

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

برای مقدار گزینه types یا مقدار منتقل‌شده به setTypes()، می‌توانید یکی از موارد زیر را مشخص کنید:

  • آرایه‌ای که حداکثر پنج مقدار از جدول ۱ یا جدول ۲ از انواع مکان را دربرمی‌گیرد. برای مثال:

    types: ['hospital', 'pharmacy', 'bakery', 'country']

    یا:

    autocomplete.setTypes(['hospital', 'pharmacy', 'bakery', 'country']);
  • هریک از فیلترهای جدول ۳ از انواع مکان. فقط می‌توانید یک مقدار از «جدول ۳» مشخص کنید.

در شرایط زیر، درخواست رد خواهد شد:

  • بیش‌از پنج نوع را مشخص کنید.
  • هر نوع ناشناخته‌ای را مشخص می‌کنید.
  • هر نوعی را از جدول ۱ یا جدول ۲ با هر فیلتری از جدول ۳ ترکیب کنید.

نسخه نمایشی «تکمیل خودکار مکان‌ها» تفاوت‌های پیش‌بینی بین انواع مکان‌های مختلف را نشان می‌دهد.

بازدید از نسخه نمایشی

درحال دریافت اطلاعات مکان

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

  1. یک کنترل‌کننده رویداد برای رویداد place_changed ایجاد کنید، و addListener() را در شیء Autocomplete فراخوانی کنید تا کنترل‌کننده را اضافه کنید.
  2. برای بازیابی کردن شیء PlaceResult ، در شیء Autocomplete، Autocomplete.getPlace() را فراخوانی کنید، سپس می‌توانید از آن برای دریافت اطلاعات بیشتر درباره مکان انتخاب‌شده استفاده کنید.

به‌طور پیش‌فرض، وقتی کاربر مکانی را انتخاب می‌کند، تکمیل خودکار همه فیلدهای داده دردسترس را برای مکان انتخاب‌شده برمی‌گرداند و هزینه آن از شما کسر می‌شود. از Autocomplete.setFields() برای مشخص کردن اینکه کدام فیلدهای داده مکان برگردانده شود استفاده کنید. درباره PlaceResult شیء، ازجمله فهرستی از فیلدهای داده مکان که می‌توانید درخواست کنید، بیشتر بخوانید. برای اینکه برای داده‌هایی که نیاز ندارید هزینه نکنید، حتماً از Autocomplete.setFields() برای مشخص کردن فقط داده‌های مکانی که استفاده خواهید کرد استفاده کنید.

دارایی name حاوی description از پیش‌بینی‌های «تکمیل خودکار مکان‌ها» است. می‌توانید درباره description در مکان‌ها اسناد تکمیل خودکار بیشتر بخوانید.

برای فرم‌های نشانی، دریافت نشانی در قالب ساختاریافته مفید است. برای برگرداندن نشانی ساختاریافته مکان انتخاب‌شده، Autocomplete.setFields() را فراخوانی کنید و فیلد address_components را مشخص کنید.

مثال زیر از تکمیل خودکار برای پر کردن فیلدهای فرم نشانی استفاده می‌کند.

TypeScript

function fillInAddress() {
  // Get the place details from the autocomplete object.
  const place = autocomplete.getPlace();
  let address1 = "";
  let postcode = "";

  // Get each component of the address from the place details,
  // and then fill-in the corresponding field on the form.
  // place.address_components are google.maps.GeocoderAddressComponent objects
  // which are documented at http://goo.gle/3l5i5Mr
  for (const component of place.address_components as google.maps.GeocoderAddressComponent[]) {
    // @ts-ignore remove once typings fixed
    const componentType = component.types[0];

    switch (componentType) {
      case "street_number": {
        address1 = `${component.long_name} ${address1}`;
        break;
      }

      case "route": {
        address1 += component.short_name;
        break;
      }

      case "postal_code": {
        postcode = `${component.long_name}${postcode}`;
        break;
      }

      case "postal_code_suffix": {
        postcode = `${postcode}-${component.long_name}`;
        break;
      }

      case "locality":
        (document.querySelector("#locality") as HTMLInputElement).value =
          component.long_name;
        break;

      case "administrative_area_level_1": {
        (document.querySelector("#state") as HTMLInputElement).value =
          component.short_name;
        break;
      }

      case "country":
        (document.querySelector("#country") as HTMLInputElement).value =
          component.long_name;
        break;
    }
  }

  address1Field.value = address1;
  postalField.value = postcode;

  // After filling the form with address components from the Autocomplete
  // prediction, set cursor focus on the second address line to encourage
  // entry of subpremise information such as apartment, unit, or floor number.
  address2Field.focus();
}

JavaScript

function fillInAddress() {
  // Get the place details from the autocomplete object.
  const place = autocomplete.getPlace();
  let address1 = "";
  let postcode = "";

  // Get each component of the address from the place details,
  // and then fill-in the corresponding field on the form.
  // place.address_components are google.maps.GeocoderAddressComponent objects
  // which are documented at http://goo.gle/3l5i5Mr
  for (const component of place.address_components) {
    // @ts-ignore remove once typings fixed
    const componentType = component.types[0];

    switch (componentType) {
      case "street_number": {
        address1 = `${component.long_name} ${address1}`;
        break;
      }

      case "route": {
        address1 += component.short_name;
        break;
      }

      case "postal_code": {
        postcode = `${component.long_name}${postcode}`;
        break;
      }

      case "postal_code_suffix": {
        postcode = `${postcode}-${component.long_name}`;
        break;
      }
      case "locality":
        document.querySelector("#locality").value = component.long_name;
        break;
      case "administrative_area_level_1": {
        document.querySelector("#state").value = component.short_name;
        break;
      }
      case "country":
        document.querySelector("#country").value = component.long_name;
        break;
    }
  }

  address1Field.value = address1;
  postalField.value = postcode;
  // After filling the form with address components from the Autocomplete
  // prediction, set cursor focus on the second address line to encourage
  // entry of subpremise information such as apartment, unit, or floor number.
  address2Field.focus();
}

window.initAutocomplete = initAutocomplete;

مشاهده مثال

سفارشی‌سازی کردن نوشتار جای‌بان

به‌طور پیش‌فرض، فیلد نوشتاری ایجادشده توسط سرویس تکمیل خودکار حاوی نوشتار جای‌بان استاندارد است. برای اصلاح نوشتار، placeholder مشخصه را در عنصر input تنظیم کنید:

<input id="searchTextField" type="text" size="50" placeholder="Anything you want!">

توجه: نوشتار جای‌بان پیش‌فرض به‌طور خودکار بومی‌سازی می‌شود. اگر مقدار جای‌بان خودتان را مشخص کنید، باید بومی‌سازی آن مقدار را در برنامه‌تان انجام دهید. برای کسب اطلاعات درباره اینکه Google Maps JavaScript API چگونه زبان مورد استفاده را انتخاب می‌کند، مستندات مربوط به بومی‌سازی را بخوانید.

برای سفارشی‌سازی ظاهر ابزاره، سبک‌دهی ابزاره‌های «تکمیل خودکار» و «کادر جستجو» را ببینید.

SearchBox به کاربران امکان می‌دهد جستجوی جغرافیایی مبتنی بر نوشتار انجام دهند، مثلاً «پیتزا در تهران» یا «فروشگاه‌های کفش در خیابان روبسون». می‌توانید SearchBox را به فیلد نوشتاری پیوست کنید و، هم‌زمان با وارد شدن نوشتار، سرویس پیش‌بینی‌هایی را در قالب فهرست انتخاب کرکره‌ای برمی‌گرداند.

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

سازنده SearchBox دو آرگومان می‌گیرد:

  • عنصر HTML input از نوع text. این فیلد ورودی است که سرویس SearchBox آن را پایش می‌کند و نتایجش را به آن پیوست می‌کند.
  • یک آرگومان options که می‌تواند حاوی دارایی bounds باشد: bounds یک شیء google.maps.LatLngBounds است که منطقه‌ای را که باید مکان‌ها در آن جستجو شوند مشخص می‌کند. نتایج به‌سمت مکان‌های درون این محدوده متمایل است، اما به آن‌ها محدود نمی‌شود.

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

var defaultBounds = new google.maps.LatLngBounds(
  new google.maps.LatLng(-33.8902, 151.1759),
  new google.maps.LatLng(-33.8474, 151.2631));

var input = document.getElementById('searchTextField');

var searchBox = new google.maps.places.SearchBox(input, {
  bounds: defaultBounds
});

تغییر دادن محدوده جستجو برای «چارگوش جستجو»

برای تغییر دادن محدوده جستجو برای SearchBox موجود، setBounds() را در شیء SearchBox فراخوانی کنید و شیء مربوطه LatLngBounds را ارسال کنید.

مشاهده مثال

درحال دریافت اطلاعات مکان

وقتی کاربر موردی را از پیش‌بینی‌های پیوست‌شده به چارگوش جستجو انتخاب می‌کند، سرویس رویداد places_changed را راه‌اندازی می‌کند. می‌توانید getPlaces() را در شیء SearchBox فراخوانی کنید تا آرایه‌ای حاوی چندین پیش‌بینی را بازیابی کنید که هریک از آن‌ها شیء PlaceResult است.

برای کسب اطلاعات بیشتر درباره شیء PlaceResult، به اسناد مربوط به نتایج جزئیات مکان مراجعه کنید.

TypeScript

// Listen for the event fired when the user selects a prediction and retrieve
// more details for that place.
searchBox.addListener("places_changed", () => {
  const places = searchBox.getPlaces();

  if (places.length == 0) {
    return;
  }

  // Clear out the old markers.
  markers.forEach((marker) => {
    marker.setMap(null);
  });
  markers = [];

  // For each place, get the icon, name and location.
  const bounds = new google.maps.LatLngBounds();

  places.forEach((place) => {
    if (!place.geometry || !place.geometry.location) {
      console.log("Returned place contains no geometry");
      return;
    }

    const icon = {
      url: place.icon as string,
      size: new google.maps.Size(71, 71),
      origin: new google.maps.Point(0, 0),
      anchor: new google.maps.Point(17, 34),
      scaledSize: new google.maps.Size(25, 25),
    };

    // Create a marker for each place.
    markers.push(
      new google.maps.Marker({
        map,
        icon,
        title: place.name,
        position: place.geometry.location,
      })
    );

    if (place.geometry.viewport) {
      // Only geocodes have viewport.
      bounds.union(place.geometry.viewport);
    } else {
      bounds.extend(place.geometry.location);
    }
  });
  map.fitBounds(bounds);
});

JavaScript

// Listen for the event fired when the user selects a prediction and retrieve
// more details for that place.
searchBox.addListener("places_changed", () => {
  const places = searchBox.getPlaces();

  if (places.length == 0) {
    return;
  }

  // Clear out the old markers.
  markers.forEach((marker) => {
    marker.setMap(null);
  });
  markers = [];

  // For each place, get the icon, name and location.
  const bounds = new google.maps.LatLngBounds();

  places.forEach((place) => {
    if (!place.geometry || !place.geometry.location) {
      console.log("Returned place contains no geometry");
      return;
    }

    const icon = {
      url: place.icon,
      size: new google.maps.Size(71, 71),
      origin: new google.maps.Point(0, 0),
      anchor: new google.maps.Point(17, 34),
      scaledSize: new google.maps.Size(25, 25),
    };

    // Create a marker for each place.
    markers.push(
      new google.maps.Marker({
        map,
        icon,
        title: place.name,
        position: place.geometry.location,
      }),
    );
    if (place.geometry.viewport) {
      // Only geocodes have viewport.
      bounds.union(place.geometry.viewport);
    } else {
      bounds.extend(place.geometry.location);
    }
  });
  map.fitBounds(bounds);
});

مشاهده مثال

برای سفارشی‌سازی ظاهر ابزاره، سبک‌دهی ابزاره‌های «تکمیل خودکار» و «کادر جستجو» را ببینید.

بازیابی برنامه‌ریزی‌شده پیش‌بینی‌های «سرویس تکمیل خودکار مکان»

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

‫AutocompleteService روش‌های زیر را آشکار می‌کند:

  • ‫getPlacePredictions() پیش‌بینی مکان را برمی‌گرداند. توجه: «مکان» می‌تواند یک مؤسسه، مکان جغرافیایی، یا نقطه موردعلاقه برجسته باشد، همان‌طور که در «میانای برنامه‌سازی کاربردی مکان‌ها» تعریف شده است.
  • ‫getQueryPredictions() فهرست گسترده‌ای از پیش‌بینی‌ها برمی‌گرداند که می‌تواند شامل مکان‌ها (طبق تعریف «واسط برنامه‌سازی کاربردی مکان‌ها») و همچنین عبارت‌های جستجوی پیشنهادی باشد. برای مثال، اگر کاربر عبارت «پیتزا در تهران» را وارد کند، فهرست انتخاب ممکن است عبارت «پیتزا در تهران» و همچنین نام‌های مختلف فروشگاه‌های پیتزا را دربرگیرد.

هر دو روش بالا آرایه‌ای از پیش‌بینی اشیا را به شکل زیر برمی‌گردانند:

  • ‫description پیش‌بینی منطبق است.
  • ‫distance_meters فاصله مکان از AutocompletionRequest.origin مشخص‌شده برحسب متر است.
  • matched_substrings حاوی مجموعه‌ای از زیررشته‌ها در شرح است که با عناصر ورودی کاربر مطابقت دارد. این کار برای برجسته کردن آن زیررشته‌ها در برنامه شما مفید است. در بسیاری از موارد، پرسمان به‌عنوان زیررشته‌ای از فیلد شرح ظاهر می‌شود.
    • ‫length طول زیررشته است.
    • offset افست نویسه است که از ابتدای رشته شرح اندازه‌گیری می‌شود و در آن زیررشته منطبق ظاهر می‌شود.
  • ‫place_id یک شناسه نوشتاری است که به‌طور یکتا مکانی را شناسایی می‌کند. برای بازیابی اطلاعات درباره مکان، این شناسه را در فیلد placeId درخواست جزئیات مکان قرار دهید. درباره نحوه ارجاع دادن به مکان با شناسه مکان بیشتر بدانید.
  • terms آرایه‌ای است که حاوی عناصر پُرسمان است. برای مکان، هر عنصر معمولاً بخشی از نشانی را تشکیل می‌دهد.
    • offset افست نویسه است که از ابتدای رشته شرح اندازه‌گیری می‌شود و در آن زیررشته منطبق ظاهر می‌شود.
    • ‫value عبارت منطبق است.

مثال زیر درخواست پیش‌بینی پُرسمان را برای عبارت «پیتزا نزدیک» اجرا می‌کند و نتیجه را در فهرستی نمایش می‌دهد.

TypeScript

// This example retrieves autocomplete predictions programmatically from the
// autocomplete service, and displays them as an HTML list.
// This example requires the Places library. Include the libraries=places
// parameter when you first load the API. For example:
// <script src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&libraries=places">
function initService(): void {
  const displaySuggestions = function (
    predictions: google.maps.places.QueryAutocompletePrediction[] | null,
    status: google.maps.places.PlacesServiceStatus
  ) {
    if (status != google.maps.places.PlacesServiceStatus.OK || !predictions) {
      alert(status);
      return;
    }

    predictions.forEach((prediction) => {
      const li = document.createElement("li");

      li.appendChild(document.createTextNode(prediction.description));
      (document.getElementById("results") as HTMLUListElement).appendChild(li);
    });
  };

  const service = new google.maps.places.AutocompleteService();

  service.getQueryPredictions({ input: "pizza near Syd" }, displaySuggestions);
}

declare global {
  interface Window {
    initService: () => void;
  }
}
window.initService = initService;

JavaScript

// This example retrieves autocomplete predictions programmatically from the
// autocomplete service, and displays them as an HTML list.
// This example requires the Places library. Include the libraries=places
// parameter when you first load the API. For example:
// <script src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&libraries=places">
function initService() {
  const displaySuggestions = function (predictions, status) {
    if (status != google.maps.places.PlacesServiceStatus.OK || !predictions) {
      alert(status);
      return;
    }

    predictions.forEach((prediction) => {
      const li = document.createElement("li");

      li.appendChild(document.createTextNode(prediction.description));
      document.getElementById("results").appendChild(li);
    });
  };

  const service = new google.maps.places.AutocompleteService();

  service.getQueryPredictions({ input: "pizza near Syd" }, displaySuggestions);
}

window.initService = initService;

CSS

HTML

<html>
  <head>
    <title>Retrieving Autocomplete Predictions</title>

    <link rel="stylesheet" type="text/css" href="./style.css" />
    <script type="module" src="./index.js"></script>
  </head>
  <body>
    <p>Query suggestions for 'pizza near Syd':</p>
    <ul id="results"></ul>
    <!-- Replace Powered By Google image src with self hosted image. https://developers.google.com/maps/documentation/places/web-service/policies#other_attribution_requirements -->
    <img
      class="powered-by-google"
      src="https://storage.googleapis.com/geo-devrel-public-buckets/powered_by_google_on_white.png"
      alt="Powered by Google"
    />

    <!-- 
      The `defer` attribute causes the script to execute after the full HTML
      document has been parsed. For non-blocking uses, avoiding race conditions,
      and consistent behavior across browsers, consider loading using Promises. See
      https://developers.google.com/maps/documentation/javascript/load-maps-js-api
      for more information.
      -->
    <script
      src="https://maps.googleapis.com/maps/api/js?key=AIzaSyB41DRUbKWJHPxaFjMAwdrzWzbVKartNGg&callback=initService&libraries=places&v=weekly"
      defer
    ></script>
  </body>
</html>

مشاهده مثال

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

AutocompleteService.getPlacePredictions() می‌تواند از نشان‌های جلسه (درصورت پیاده‌سازی) برای گروه‌بندی درخواست‌های تکمیل خودکار برای اهداف صدور صورت‌حساب استفاده کند. نشان‌های جلسه مراحل پُرسمان و انتخاب جستجوی تکمیل خودکار کاربر را برای اهداف صدور صورت‌حساب در جلسه مجزایی گروه‌بندی می‌کند. جلسه وقتی شروع می‌شود که کاربر شروع به تایپ کردن پُرسمانی می‌کند و وقتی پایان می‌یابد که مکان را انتخاب می‌کند. هر جلسه می‌تواند چندین پُرسمان داشته باشد که با انتخاب یک مکان دنبال می‌شود. پس‌از پایان جلسه، رمز دیگر معتبر نیست. برنامه شما باید برای هر جلسه یک کد تازه تولید کند. توصیه می‌کنیم برای همه جلسه‌های تکمیل خودکار از نشانه جلسه استفاده کنید. اگر پارامتر sessionToken حذف شود یا اگر از یک کد جلسه مجدداً استفاده کنید، هزینه جلسه به‌گونه‌ای محاسبه می‌شود که انگار کد جلسه ارائه نشده است (هزینه هر درخواست به‌صورت جداگانه محاسبه می‌شود).

می‌توانید از همان نشانه جلسه برای ایجاد یک درخواست جزئیات مکان در مکانی که از تماس با AutocompleteService.getPlacePredictions() به‌دست آمده است استفاده کنید. در این مورد، درخواست تکمیل خودکار با درخواست «جزئیات مکان» ترکیب می‌شود و هزینه تماس به‌عنوان درخواست معمولی «جزئیات مکان» محاسبه می‌شود. برای درخواست تکمیل خودکار هزینه‌ای دریافت نمی‌شود.

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

مثال زیر ایجاد یک کد جلسه و سپس انتقال آن در AutocompleteService (تابع displaySuggestions() برای کوتاه‌تر شدن حذف شده است) را نشان می‌دهد:

// Create a new session token.
var sessionToken = new google.maps.places.AutocompleteSessionToken();

// Pass the token to the autocomplete service.
var autocompleteService = new google.maps.places.AutocompleteService();
autocompleteService.getPlacePredictions({
  input: 'pizza near Syd',
  sessionToken: sessionToken
},
displaySuggestions);

حتماً برای هر جلسه جدید، کد جلسه یکتایی ارسال کنید. استفاده از یک توکن برای بیش از یک جلسه منجر به صورت‌حساب جداگانه برای هر درخواست می‌شود.

درباره نشان‌های جلسه بیشتر بخوانید.

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

به‌طور پیش‌فرض، عناصر رابط کاربری ارائه‌شده توسط Autocomplete و SearchBox برای گنجاندن در نقشه Google سبک‌بندی می‌شوند. شاید بخواهید سبک‌بندی را متناسب با سایت خودتان تنظیم کنید. کلاس‌های CSS زیر دردسترس است. همه کلاس‌های فهرست‌شده در زیر برای هر دو ابزاره Autocomplete و SearchBox اعمال می‌شود.

تصویر گرافیکی از کلاس‌های CSS برای ابزارک‌های «تکمیل خودکار» و «کادر جستجو»
کلاس‌های CSS برای ابزارک‌های «تکمیل خودکار» و «چارگوش جستجو»
کلاس CSS شرح
pac-container عنصر دیداری حاوی فهرست پیش‌بینی‌های برگشتی از سرویس «تکمیل خودکار مکان». این فهرست به‌عنوان فهرست کرکره‌ای در زیر Autocomplete یا ابزارک SearchBox ظاهر می‌شود.
pac-icon نماد نمایش‌داده‌شده در سمت راست هر مورد در فهرست پیش‌بینی‌ها.
pac-item موردی در فهرست پیش‌بینی‌های ارائه‌شده توسط ابزاره Autocomplete یا SearchBox.
pac-item:hover مورد وقتی کاربر نشانگر موشواره را روی آن نگه می‌دارد.
pac-item-selected موردی که کاربر بااستفاده از صفحه‌کلید انتخاب می‌کند. توجه: موارد انتخاب‌شده عضو این کلاس و کلاس pac-item خواهند بود.
pac-item-query گستره‌ای درون pac-item که بخش اصلی پیش‌بینی است. برای مکان‌های جغرافیایی، این فیلد حاوی نام مکان، مثل «سیدنی»، یا نام و شماره خیابان، مثل «10 King Street» است. برای جستجوهای نوشتاری مثل «پیتزا در تهران»، شامل نوشتار کامل پُرسمان است. به‌طور پیش‌فرض، pac-item-query به رنگ سیاه است. اگر نوشتار اضافه‌ای در pac-item وجود داشته باشد، خارج از pac-item-query است و سبک آن را از pac-item به‌ارث می‌برد. به‌طور پیش‌فرض به رنگ خاکستری است. نوشتار اضافی معمولاً نشانی است.
pac-matched بخشی از پیش‌بینی برگشتی که با ورودی کاربر مطابقت دارد. به‌طور پیش‌فرض، این نوشتار منطبق با نوشتار پررنگ برجسته می‌شود. توجه داشته باشید که نوشتار منطبق ممکن است در هر جایی از pac-item باشد. این لزوماً بخشی از pac-item-query نیست و می‌تواند بخشی در pac-item-query و بخشی در نوشتار باقی‌مانده در pac-item باشد.

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

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

در اینجا چند دستورالعمل کلی آمده است:

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

بله

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

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

نه

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

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

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

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

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

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

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

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

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

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

  • محدودیت‌های کشور، گرایش مکان، و (برای پیاده‌سازی‌های برنامه‌ریزی‌شده) اولویت زبان را به پیاده‌سازی «تکمیل خودکار مکان» (قدیمی) اضافه کنید. اولویت زبان برای ابزارک‌ها لازم نیست زیرا اولویت‌های زبان را از مرورگر یا دستگاه همراه کاربر انتخاب می‌کنند.
  • اگر «جای‌آگهی خودکار مکان (قدیمی)» با نقشه همراه باشد، می‌توانید مکان را براساس نمای درگاه نقشه گرایش دهید.
  • در شرایطی که کاربر یکی از پیش‌بینی‌های «تکمیل خودکار مکان» (قدیمی) را انتخاب نمی‌کند، معمولاً به‌دلیل اینکه هیچ‌یک از آن پیش‌بینی‌ها نشانی نتیجه موردنظر نیست، می‌توانید از ورودی کاربر اصلی برای تلاش در جهت دریافت نتایج مرتبط‌تر استفاده مجدد کنید:
    • اگر انتظار دارید کاربر فقط اطلاعات نشانی را وارد کند، ورودی کاربر اصلی را در تماس با Geocoding API دوباره استفاده کنید.
    • اگر انتظار دارید کاربر پُرسمان‌هایی را برای مکان خاصی براساس نام یا نشانی وارد کند، از درخواست «جزئیات مکان» (قدیمی) استفاده کنید. اگر انتظار می‌رود نتایج فقط در منطقه خاصی باشد، از گرایش مکان استفاده کنید.
    سناریوهای دیگری که بهتر است به Geocoding API برگردید عبارت‌اند از:
    • کاربرانی که نشانی‌های فرعی وارد می‌کنند، مثل نشانی‌های واحدهای خاص یا آپارتمان‌ها در یک ساختمان. برای مثال، نشانی چک «Stroupežnického 3191/17, Praha» پیش‌بینی جزئی در «تکمیل خودکار مکان» (قدیمی) ارائه می‌دهد.
    • کاربرانی که نشانی‌هایی با پیشوندهای بخش جاده‌ای مثل «23-30 29th St, Queens» در شهر نیویورک یا «47-380 Kamehameha Hwy, Kaneohe» در جزیره کائوآئی در هاوایی وارد می‌کنند.

انحراف مکانی

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

مکان محدودکننده

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

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

حدود استفاده

سهمیه‌ها

برای اطلاعات مربوط به سهمیه و قیمت‌گذاری، به مستندات «استفاده و صورت‌حساب» برای Places API مراجعه کنید.