هشدار امنیتی : ما از یک مشکل امنیتی آگاه شده‌ایم که ممکن است وب‌سایت‌هایی را که از کتابخانه‌های شخص ثالث خاصی استفاده می‌کنند (از جمله polyfill.io) تحت تأثیر قرار دهد. این مشکل گاهی اوقات می‌تواند بازدیدکنندگان را بدون اطلاع یا اجازه صاحب وب‌سایت از وب‌سایت مورد نظر دور کند. بسیاری از نمونه‌های جاوا اسکریپت ما قبلاً شامل اعلان اسکریپت polyfill.io بودند. ما این را از نمونه های خود حذف کرده ایم. اگر از نمونه های جاوا اسکریپت ما که حاوی این اعلان هستند استفاده کرده اید، توصیه می کنیم اعلان را حذف کنید.

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

این صفحه به‌وسیله ‏Cloud Translation API‏ ترجمه شده است.

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

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

توجه: کتابخانه های سمت سرور

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

مقدمه

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

شروع کردن

قبل از استفاده از کتابخانه Places در Maps JavaScript API، ابتدا مطمئن شوید که Places API در Google Cloud Console، در همان پروژه ای که برای Maps JavaScript API تنظیم کرده اید، فعال است.

برای مشاهده لیست API های فعال:

به Google Cloud Console بروید.
روی دکمه Select a project کلیک کنید، سپس همان پروژه ای را که برای Maps JavaScript API تنظیم کرده اید انتخاب کنید و روی Open کلیک کنید.
از لیست APIها در داشبورد ، Places API را جستجو کنید.
اگر API را در لیست مشاهده کردید، همه چیز آماده است. اگر API در لیست نیست ، آن را فعال کنید:
1. در بالای صفحه، ENABLE API را انتخاب کنید تا تب Library نمایش داده شود. یا از منوی سمت چپ، کتابخانه را انتخاب کنید.
2. Places API را جستجو کنید، سپس آن را از لیست نتایج انتخاب کنید.
3. ENABLE را انتخاب کنید. پس از پایان فرآیند، Places API در فهرست APIها در داشبورد ظاهر می‌شود.

در حال بارگیری کتابخانه

سرویس Places یک کتابخانه مستقل و جدا از کد اصلی Maps JavaScript API است. برای استفاده از عملکرد موجود در این کتابخانه، ابتدا باید آن را با استفاده از پارامتر libraries در URL بوت استرپ 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 یک فیلد ورودی متن را به صفحه وب شما اضافه می کند و آن فیلد را برای ورود کاراکترها کنترل می کند. همانطور که کاربر متن را وارد می کند، تکمیل خودکار پیش بینی های مکان را در قالب یک لیست انتخاب کشویی برمی گرداند. هنگامی که کاربر مکانی را از لیست انتخاب می کند، اطلاعات مربوط به مکان به شی تکمیل خودکار بازگردانده می شود و می تواند توسط برنامه شما بازیابی شود. جزئیات را در زیر مشاهده کنید.
شکل 1: تکمیل خودکار فیلد متن و لیست انتخاب
شکل 2: فرم آدرس تکمیل شده
SearchBox یک فیلد ورودی متن را به صفحه وب شما اضافه می کند، تقریباً مانند Autocomplete . تفاوت ها به شرح زیر است:
- تفاوت اصلی در نتایجی است که در لیست انتخاب ظاهر می شوند. SearchBox فهرست گسترده‌ای از پیش‌بینی‌ها را ارائه می‌کند که می‌تواند شامل مکان‌ها (همانطور که توسط Places API تعریف شده است) به همراه عبارات جستجوی پیشنهادی باشد. برای مثال، اگر کاربر «پیتزا در جدید» را وارد کند، فهرست انتخاب ممکن است شامل عبارت «پیتزا در نیویورک، نیویورک» و همچنین نام فروشگاه‌های مختلف پیتزا باشد.
- SearchBox گزینه های کمتری نسبت به Autocomplete برای محدود کردن جستجو ارائه می دهد. در حالت اول، می توانید جستجو را به سمت LatLngBounds معین سوگیری کنید. در حالت دوم، می‌توانید جستجو را به یک کشور خاص و انواع مکان‌های خاص محدود کنید، و همچنین محدودیت‌ها را تعیین کنید. برای اطلاعات بیشتر، زیر را ببینید.
شکل 3: یک SearchBox عبارات جستجو و پیش بینی مکان را ارائه می دهد.
جزئیات را در زیر مشاهده کنید.
شما می توانید یک شی AutocompleteService برای بازیابی پیش بینی ها به صورت برنامه ای ایجاد کنید. برای بازیابی مکان‌های منطبق با getPlacePredictions() یا برای بازیابی مکان‌های منطبق و عبارات جستجوی پیشنهادی getQueryPredictions() را تماس بگیرید. توجه: AutocompleteService هیچ کنترل رابط کاربری اضافه نمی کند. در عوض، روش‌های فوق آرایه‌ای از اشیاء پیش‌بینی را برمی‌گردانند. هر شیء پیش‌بینی حاوی متن پیش‌بینی، و همچنین اطلاعات مرجع و جزئیات نحوه مطابقت نتیجه با ورودی کاربر است. جزئیات را در زیر مشاهده کنید.

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

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

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

یک عنصر input HTML از نوع text . این فیلد ورودی است که سرویس تکمیل خودکار نتایج آن را نظارت کرده و به آن پیوست می کند.
یک آرگومان اختیاری AutocompleteOptions که می تواند حاوی ویژگی های زیر باشد:
- آرایه ای از fields داده که باید در پاسخ Place Details برای PlaceResult انتخابی کاربر گنجانده شود. اگر ویژگی تنظیم نشده باشد یا اگر ['ALL'] وارد شود، همه فیلدهای موجود برگردانده شده و برای آنها صورت‌حساب دریافت می‌شود (این برای استقرار تولید توصیه نمی‌شود). برای فهرستی از فیلدها، PlaceResult را ببینید.
- آرایه ای از types که نوع صریح یا مجموعه نوع را مشخص می کند، همانطور که در انواع پشتیبانی شده فهرست شده است. اگر نوع مشخص نشده باشد، همه انواع برگردانده می شوند.
- bounds یک شی google.maps.LatLngBounds است که منطقه ای را برای جستجوی مکان ها مشخص می کند. نتایج به سمت مکان‌هایی که در این محدوده‌ها قرار دارند، تعصب دارند، اما محدود به آن‌ها نیستند.
- strictBounds یک boolean است که مشخص می‌کند آیا API باید فقط مکان‌هایی را برگرداند که دقیقاً در منطقه تعریف‌شده با bounds داده شده هستند یا خیر. API نتایج خارج از این منطقه را حتی اگر با ورودی کاربر مطابقت داشته باشد برنمی‌گرداند.
  توجه: محدودیت مکان فقط برای کل مسیرها اعمال می شود، نتایج مصنوعی واقع در خارج از محدودیت مکان ممکن است بر اساس مسیری که با محدودیت مکان همپوشانی دارد، برگردانده شوند.
- componentRestrictions می تواند برای محدود کردن نتایج به گروه های خاص استفاده شود. در حال حاضر، می‌توانید از componentRestrictions برای فیلتر کردن حداکثر ۵ کشور استفاده کنید. کشورها باید به عنوان کد کشوری دو کاراکتری و سازگار با ISO 3166-1 Alpha-2 ارسال شوند. چندین کشور باید به عنوان فهرستی از کدهای کشور ارسال شوند.
  توجه: اگر نتایج غیرمنتظره‌ای را با کد کشور دریافت کردید، بررسی کنید که از کدی استفاده می‌کنید که شامل کشورها، مناطق وابسته و مناطق خاص جغرافیایی مورد نظر شما می‌شود. اطلاعات کد را می‌توانید در ویکی‌پدیا بیابید: فهرست کدهای کشورها ISO 3166 یا پلتفرم مرور آنلاین ISO .
- placeIdOnly می‌تواند برای دستور دادن به ویجت تکمیل Autocomplete برای بازیابی فقط شناسه‌های مکان استفاده شود. هنگام فراخوانی getPlace() در شیء Autocomplete ، PlaceResult موجود تنها دارای place id ، types و خصوصیات name است. می‌توانید از شناسه مکان برگشتی با تماس‌هایی که با سرویس‌های مکان‌ها، کدگذاری جغرافیایی، مسیرها یا ماتریس فاصله دارد استفاده کنید.
  توجه: ویژگی name حاوی description مربوط به پیش‌بینی‌های تکمیل خودکار مکان‌ها خواهد بود. می‌توانید درباره description در مستندات AutocompleteService بیشتر بخوانید.
  توجه: placeIdOnly از 15 ژانویه 2019 منسوخ شده است و در 15 ژانویه 2020 خاموش خواهد شد. به جای آن از آرایه fields در رابط AutocompleteOptions استفاده کنید: fields: ['place_id', 'name', 'types'] .

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

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

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

سازنده 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);index.ts

جاوا اسکریپت

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);
index.js

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

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

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

تعصبات و مرزهای ناحیه جستجو را برای تکمیل خودکار تعریف کنید

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

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

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

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

محدوده یک تکمیل خودکار موجود را تغییر دهید

برای تغییر ناحیه جستجو در یک 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);index.ts

جاوا اسکریپت

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);
index.js

محدوده ها را برای نمای نقشه تنظیم کنید

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

TypeScript

autocomplete.bindTo("bounds", map);index.ts

جاوا اسکریپت

autocomplete.bindTo("bounds", map);
index.js

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

TypeScript

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

جاوا اسکریپت

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

مشاهده نمونه

جستجو را به محدوده فعلی محدود کنید

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

autocomplete.setOptions({ strictBounds: true });

پیش بینی ها را به یک کشور خاص محدود کنید

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

TypeScript

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

جاوا اسکریپت

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

مشاهده نمونه

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

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

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

آرایه ای حاوی حداکثر پنج مقدار از جدول 1 یا جدول 2 از انواع مکان . به عنوان مثال:
```
types: ['hospital', 'pharmacy', 'bakery', 'country']
```
یا:
```
autocomplete.setTypes(['hospital', 'pharmacy', 'bakery', 'country']);
```
هر یک از فیلترها در جدول 3 از انواع مکان . شما فقط می توانید یک مقدار را از جدول 3 مشخص کنید.

درخواست رد می شود در صورتی که:

شما بیش از پنج نوع را مشخص می کنید.
شما انواع ناشناخته را مشخص می کنید.
هر نوع از جدول 1 یا جدول 2 را با هر فیلتری از جدول 3 مخلوط می کنید.

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

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

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

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

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

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

مهم: استفاده از تکمیل خودکار برای بازخوانی شناسه‌های مکان توصیه نمی‌شود، زیرا هر جلسه هزینه‌ای را در پی خواهد داشت. در عوض، getDetails() را فراخوانی کنید و فقط قسمت place_id را مشخص کنید.

ویژگی 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();
}index.ts

جاوا اسکریپت

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;
index.js

مشاهده نمونه

ممکن است جزء آدرس street_number در پاسخ‌های Place Details برای شناسه‌های مکان در برخی از پیش‌بینی‌های تکمیل خودکار وجود نداشته باشد. این معمولاً زمانی اتفاق می‌افتد که آدرس را نمی‌توان برای یک مکان درون‌یابی کرد. در این موارد، آرایه types پیش بینی حاوی "مسیر" خواهد بود. برای پیش‌بینی‌های تکمیل خودکار با یک عدد در توضیحات (پرسمان ورودی مطابقت دارد)، پاسخ جزئیات مکان برای شناسه مکان فقط در صورتی حاوی شماره خیابان است که آرایه types پیش‌بینی حداقل یکی از موارد زیر را داشته باشد:

آدرس_خیابان
مقدمه
استقرار

سفارشی کردن متن مکان نگهدار

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

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

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

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

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

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

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

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

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

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);
});index.ts

جاوا اسکریپت

// 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);
});index.js

مشاهده نمونه

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

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

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

AutocompleteService روش های زیر را در معرض نمایش قرار می دهد:

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

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

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

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

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;index.ts

جاوا اسکریپت

// 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;index.js

CSS

style.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>index.html

Sample را امتحان کنید

JSFiddle.net Google Cloud Shell

مشاهده نمونه

نشانه های جلسه

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

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

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

مثال زیر ایجاد یک نشانه جلسه، سپس ارسال آن در 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);

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

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

استایل دادن به ویجت های تکمیل خودکار و SearchBox

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

یک تصویر گرافیکی از کلاس‌های CSS برای ویجت‌های تکمیل خودکار و SearchBox — کلاس های CSS برای ویجت های تکمیل خودکار و SearchBox

کلاس 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 کینگ» است. برای جستجوهای مبتنی بر متن مانند "پیتزا در نیویورک"، حاوی متن کامل پرس و جو است. به طور پیش فرض، `pac-item-query` سیاه رنگ است. اگر متن اضافی در `pac-item` وجود داشته باشد، خارج از `pac-item-query` است و استایل خود را از `pac-item` به ارث می برد. به طور پیش فرض خاکستری رنگ است. متن اضافی معمولاً یک آدرس است.
`pac-matched`	بخشی از پیش بینی برگشتی که با ورودی کاربر مطابقت دارد. به طور پیش فرض، این متن مطابق با متن پررنگ برجسته می شود. توجه داشته باشید که متن تطبیق داده شده ممکن است در هر جایی از `pac-item` باشد. لزوماً بخشی از `pac-item-query` نیست و می تواند تا حدی در `pac-item-query` و همچنین بخشی از متن باقی مانده در `pac-item` باشد.

از مولفه Place Picker استفاده کنید

توجه: این نمونه از یک کتابخانه متن باز استفاده می کند. برای پشتیبانی و بازخورد مربوط به کتابخانه به README مراجعه کنید.

کامپوننت های وب را امتحان کنید. از مؤلفه وب Place Picker برای فعال کردن ورودی متن استفاده کنید که به کاربران نهایی امکان می دهد آدرس یا مکان خاصی را با استفاده از تکمیل خودکار جستجو کنند.

GIF با کادر جستجو. کاربر شروع به تایپ یک آدرس به عنوان ورودی می کند و یک منوی کشویی با آدرس های مرتبط ظاهر می شود. کاربر روی یک آدرس از منوی بازشو کلیک می کند و کادر جستجو بقیه آدرس را پر می کند. — شکل 1: ورودی متن برای جستجوی یک آدرس یا مکان خاص با استفاده از تکمیل خودکار

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

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

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

سریعترین راه برای توسعه یک رابط کاربری کارآمد، استفاده از ابزارک تکمیل خودکار Maps JavaScript API، Places SDK برای ویجت تکمیل خودکار Android، یا Places SDK برای کنترل رابط کاربری خودکار iOS است.
از همان ابتدا درک درستی از فیلدهای داده تکمیل خودکار مکان ضروری ایجاد کنید.
فیلدهای بایاس موقعیت و محدودیت مکان اختیاری هستند اما می توانند تأثیر قابل توجهی بر عملکرد تکمیل خودکار داشته باشند.
از مدیریت خطا استفاده کنید تا مطمئن شوید اگر API خطایی را برمی‌گرداند، برنامه شما به خوبی کاهش می‌یابد.
مطمئن شوید که برنامه شما وقتی انتخابی وجود ندارد کنترل می کند و راهی برای ادامه به کاربران ارائه می دهد.

بهترین شیوه های بهینه سازی هزینه

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

برای بهینه‌سازی هزینه استفاده از سرویس تکمیل خودکار مکان، از ماسک‌های فیلد در ویجت‌های Place Details و Place Autocomplete استفاده کنید تا فقط فیلدهای داده مکان مورد نیازتان را برگردانید.

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

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

اگر فقط به طول/طول جغرافیایی یا آدرس مکان انتخابی کاربر نیاز دارید، API Geocoding این اطلاعات را کمتر از یک تماس با جزئیات مکان ارائه می‌کند.
اگر کاربران یک پیش‌بینی تکمیل خودکار را در چهار درخواست پیش‌بینی تکمیل خودکار یا کمتر انتخاب کنند، ممکن است قیمت‌گذاری به ازای هر درخواست مقرون‌به‌صرفه‌تر از قیمت‌گذاری در هر جلسه باشد.

برای کمک به انتخاب پیاده‌سازی تکمیل خودکار مکان که متناسب با نیاز شماست، برگه‌ای را انتخاب کنید که با پاسخ شما به سؤال زیر مطابقت دارد.

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

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

از تکمیل خودکار مکان مبتنی بر جلسه با جزئیات مکان استفاده کنید.
از آنجایی که برنامه شما به جزئیات مکان مانند نام مکان، وضعیت کسب و کار، یا ساعات کاری نیاز دارد، پیاده سازی تکمیل خودکار مکان شما باید از یک نشانه جلسه ( به صورت برنامه نویسی یا تعبیه شده در ویجت های جاوا اسکریپت ، اندروید ، یا iOS ) با هزینه کل 0.017 دلار برای هر استفاده کند. بسته به فیلدهای داده مکانی که درخواست می کنید، session plus SKU های داده مکان های قابل اجرا. ¹

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

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

شناسه مکان از پاسخ تکمیل خودکار مکان
نشانه جلسه مورد استفاده در درخواست تکمیل خودکار مکان
پارامتر fields فیلدهای داده مکان مورد نیاز را مشخص می کند

خیر، فقط به آدرس و مکان نیاز دارد

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

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

آیا کاربران شما پیش‌بینی تکمیل خودکار مکان را به طور متوسط در چهار درخواست یا کمتر انتخاب می‌کنند؟

بله

Place Autocomplete را به صورت برنامه‌نویسی و بدون نشانه‌های جلسه اجرا کنید و API Geocoding را در پیش‌بینی مکان انتخاب‌شده فراخوانی کنید.
Geocoding API آدرس ها و مختصات طول و عرض جغرافیایی را برای هر درخواست 0.005 دلار ارائه می دهد. ایجاد چهار درخواست تکمیل خودکار مکان - به ازای هر درخواست 0.01132 دلار هزینه دارد، بنابراین هزینه کل چهار درخواست به اضافه یک تماس API جغرافیایی در مورد پیش بینی مکان انتخابی 0.01632 دلار خواهد بود که کمتر از قیمت تکمیل خودکار در هر جلسه 0.017 دلار در هر جلسه است. ¹

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

خیر

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

شناسه مکان از پاسخ تکمیل خودکار مکان
نشانه جلسه مورد استفاده در درخواست تکمیل خودکار مکان
پارامتر fields فیلدهای داده های پایه مانند آدرس و هندسه را مشخص می کند

درخواست‌های تکمیل خودکار مکان را به تأخیر بیندازید
می‌توانید از استراتژی‌هایی مانند تأخیر در درخواست تکمیل خودکار مکان استفاده کنید تا زمانی که کاربر سه یا چهار کاراکتر اول را تایپ کند تا برنامه شما درخواست‌های کمتری داشته باشد. برای مثال، ایجاد درخواست‌های تکمیل خودکار مکان برای هر کاراکتر پس از اینکه کاربر نویسه سوم را تایپ کرد به این معنی است که اگر کاربر هفت نویسه را تایپ کند و سپس پیش‌بینی‌ای را انتخاب کند که برای آن یک درخواست API Geocoding انجام دهید، کل هزینه 0.01632 دلار (4 * 0.00283 خودکار تکمیل خودکار) خواهد بود. در هر درخواست + 0.005 دلار رمزگذاری جغرافیایی). ¹

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

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

هزینه های ذکر شده در اینجا به USD هستند. لطفاً برای اطلاعات کامل قیمت به صفحه صورت‌حساب پلتفرم Google Maps مراجعه کنید.

بهترین شیوه های عملکرد

دستورالعمل‌های زیر راه‌هایی را برای بهینه‌سازی عملکرد تکمیل خودکار مکان توضیح می‌دهند:

محدودیت‌های کشور، سوگیری موقعیت و اولویت زبان (برای اجرای برنامه‌ای) را به پیاده‌سازی تکمیل خودکار مکان خود اضافه کنید. اولویت زبان با ویجت ها مورد نیاز نیست زیرا آنها ترجیحات زبان را از مرورگر کاربر یا دستگاه تلفن همراه انتخاب می کنند.
اگر Place AutoClotte با یک نقشه همراه باشد ، می توانید مکان تعصب را با نمای نقشه تعصب کنید.
در مواقعی که کاربر یکی از پیش بینی های خودکار را انتخاب نمی کند ، به طور کلی به دلیل اینکه هیچ یک از این پیش بینی ها آدرس مطلوب نیست ، می توانید از ورودی کاربر اصلی استفاده کنید تا سعی کنید نتایج مرتبط تری داشته باشید:
- اگر انتظار دارید کاربر فقط اطلاعات آدرس را وارد کند ، از ورودی اصلی کاربر در تماس با API GeoCoding استفاده مجدد کنید.
- اگر انتظار دارید کاربر برای یک مکان خاص با نام یا آدرس ، نمایش داده شود ، از یک درخواست مکان Find استفاده کنید. اگر نتایج فقط در یک منطقه خاص انتظار می رود ، از تعصب مکان استفاده کنید.
سناریوهای دیگر هنگامی که بهتر است به API Geocoding برگردید عبارتند از:
- کاربرانی که آدرس های زیرپرسی را در کشورهایی وارد می کنند که در آن پشتیبانی خودکار از آدرس های زیرزمینی قرار می گیرند ناقص هستند ، به عنوان مثال چک ، استونی و لیتوانی. به عنوان مثال ، آدرس چک "Stroupežnického 3191/17 ، Praha" پیش بینی جزئی در محل را به صورت خودکار انجام می دهد.
- کاربرانی که آدرس هایی را با پیشوندهای قطعه جاده مانند "23-30 29 خیابان ، کوئینز" در شهر نیویورک یا "47-380 Kamehameha Hwy ، Kaneohe" در جزیره Kauai در هاوایی وارد می کنند.

محدودیت ها و سیاست های استفاده

سهمیه ها

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

سیاست ها

استفاده از کتابخانه مکان ها ، نقشه های API JavaScript باید مطابق با سیاست های شرح داده شده برای API مکان ها باشد.

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

مقدمه

شروع کردن

در حال بارگیری کتابخانه

خلاصه کلاس ها

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

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

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

TypeScript

جاوا اسکریپت

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

تعصبات و مرزهای ناحیه جستجو را برای تکمیل خودکار تعریف کنید

محدوده یک تکمیل خودکار موجود را تغییر دهید

TypeScript

جاوا اسکریپت

محدوده ها را برای نمای نقشه تنظیم کنید

TypeScript

جاوا اسکریپت

TypeScript

جاوا اسکریپت

جستجو را به محدوده فعلی محدود کنید

پیش بینی ها را به یک کشور خاص محدود کنید

TypeScript

جاوا اسکریپت

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

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

TypeScript

جاوا اسکریپت

سفارشی کردن متن مکان نگهدار

افزودن ویجت SearchBox

تغییر ناحیه جستجو برای SearchBox

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

TypeScript

جاوا اسکریپت

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

TypeScript

جاوا اسکریپت

CSS

HTML

Sample را امتحان کنید

نشانه های جلسه

استایل دادن به ویجت های تکمیل خودکار و SearchBox

از مولفه Place Picker استفاده کنید

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

بهترین شیوه های بهینه سازی هزینه

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

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

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

خیر، فقط به آدرس و مکان نیاز دارد

بله

خیر

بهترین شیوه های عملکرد

محدودیت ها و سیاست های استفاده

سهمیه ها

سیاست ها