اعلامیه: سبک نقشه پایه جدید به زودی به پلتفرم نقشه های گوگل می آید. این به‌روزرسانی برای استایل نقشه شامل یک پالت رنگی پیش‌فرض جدید، پین‌های مدرن شده و بهبودهایی در تجربه‌ها و قابلیت استفاده از نقشه است. همه سبک‌های نقشه به‌طور خودکار در مارس 2025 به‌روزرسانی می‌شوند. برای اطلاعات بیشتر در مورد در دسترس بودن و نحوه انتخاب زودتر، به سبک نقشه جدید برای پلتفرم Google Maps مراجعه کنید.
این صفحه کتابخانه سمت سرویس گیرنده موجود با 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 در همان پروژه ای که برای Maps JavaScript API تنظیم کرده اید، فعال است.
روی دکمه Select a project کلیک کنید، سپس همان پروژه ای را که برای Maps JavaScript API تنظیم کرده اید انتخاب کنید و روی Open کلیک کنید.
از لیست APIها در داشبورد ، Places API را جستجو کنید.
اگر API را در لیست مشاهده کردید، همه چیز آماده است. اگر API در لیست نیست ، آن را فعال کنید:
در بالای صفحه، ENABLE API را انتخاب کنید تا تب Library نمایش داده شود. یا از منوی سمت چپ، کتابخانه را انتخاب کنید.
Places API را جستجو کنید، سپس آن را از لیست نتایج انتخاب کنید.
ENABLE را انتخاب کنید. پس از پایان فرآیند، Places API در فهرست APIها در داشبورد ظاهر می‌شود.
در حال بارگیری کتابخانه
سرویس Places یک کتابخانه مستقل و جدا از کد اصلی Maps JavaScript API است. برای استفاده از عملکرد موجود در این کتابخانه، ابتدا باید آن را با استفاده از پارامتر libraries در URL بوت استرپ Maps API بارگیری کنید:
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 . این فیلد ورودی است که سرویس تکمیل خودکار نتایج آن را نظارت کرده و به آن پیوست می کند.
آرایه ای از fields داده که باید در پاسخ Place Details برای PlaceResult انتخابی کاربر گنجانده شود. اگر ویژگی تنظیم نشده باشد یا اگر ['ALL'] وارد شود، همه فیلدهای موجود برگردانده شده و برای آنها صورتحساب دریافت می‌شود (این برای استقرار تولید توصیه نمی‌شود). برای فهرستی از فیلدها، PlaceResult ببینید.
آرایه ای از types که نوع صریح یا مجموعه نوع را مشخص می کند، همانطور که در انواع پشتیبانی شده فهرست شده است. اگر نوع مشخص نشده باشد، همه انواع برگردانده می شوند.
bounds یک شی google.maps.LatLngBounds است که منطقه ای را برای جستجوی مکان ها مشخص می کند. نتایج به سمت مکان‌هایی که در این محدوده‌ها قرار دارند، تعصب دارند، اما محدود به آنها نیستند.
strictBounds یک boolean است که مشخص می‌کند آیا API باید فقط مکان‌هایی را برگرداند که دقیقاً در منطقه تعریف‌شده با bounds داده شده هستند یا خیر. API نتایج خارج از این منطقه را حتی اگر با ورودی کاربر مطابقت داشته باشد برنمی‌گرداند.
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
constcenter={lat:50.064192,lng:-130.605469};// Create a bounding box with sides ~10km away from the center pointconstdefaultBounds={north:center.lat+0.1,south:center.lat-0.1,east:center.lng+0.1,west:center.lng-0.1,};constinput=document.getElementById("pac-input")asHTMLInputElement;constoptions={bounds:defaultBounds,componentRestrictions:{country:"us"},fields:["address_components","geometry","icon","name"],strictBounds:false,};constautocomplete=newgoogle.maps.places.Autocomplete(input,options);
constcenter={lat:50.064192,lng:-130.605469};// Create a bounding box with sides ~10km away from the center pointconstdefaultBounds={north:center.lat+0.1,south:center.lat-0.1,east:center.lng+0.1,west:center.lng-0.1,};constinput=document.getElementById("pac-input");constoptions={bounds:defaultBounds,componentRestrictions:{country:"us"},fields:["address_components","geometry","icon","name"],strictBounds:false,};constautocomplete=newgoogle.maps.places.Autocomplete(input,options);
فیلدهای داده را مشخص کنید تا از دریافت صورتحساب برای مکان‌های SKU داده مکان‌هایی که به آنها نیاز ندارید اجتناب کنید. همانطور که در مثال قبلی نشان داده شد، ویژگی fields را در AutocompleteOptions که به سازنده ویجت ارسال می شود، اضافه کنید، یا setFields() را روی یک شیء Autocomplete موجود فراخوانی کنید.
گزینه strictBounds را تنظیم کنید تا نتایج را به کران های فعلی محدود کنید، چه بر اساس نمای نقشه و چه بر اساس مرزهای مستطیلی.
autocomplete.setOptions({strictBounds:true});
پیش بینی ها را به یک کشور خاص محدود کنید
از گزینه componentRestrictions استفاده کنید یا setComponentRestrictions() را فراخوانی کنید تا جستجوی تکمیل خودکار را به مجموعه خاصی از حداکثر پنج کشور محدود کنید.
از گزینه types یا فراخوانی setTypes() برای محدود کردن پیش‌بینی‌ها به انواع مکان‌های خاص استفاده کنید. این محدودیت یک نوع یا یک مجموعه نوع را مشخص می کند، همانطور که در Place Types فهرست شده است. اگر هیچ محدودیتی مشخص نشده باشد، همه انواع برگردانده می شوند.
برای مقدار گزینه types یا مقدار ارسال شده به setTypes() می توانید یکی از این موارد را مشخص کنید:
وقتی کاربر مکانی را از پیش‌بینی‌های پیوست شده به فیلد متن تکمیل خودکار انتخاب می‌کند، سرویس یک رویداد place_changed را فعال می‌کند. برای دریافت جزئیات مکان:
یک کنترل کننده رویداد برای رویداد place_changed ایجاد کنید، و addListener() را در شی Autocomplete فراخوانی کنید تا کنترل کننده را اضافه کنید.
Autocomplete.getPlace() را در شیء Autocomplete فراخوانی کنید تا یک شی PlaceResult بازیابی کنید، سپس می توانید از آن برای دریافت اطلاعات بیشتر در مورد مکان انتخاب شده استفاده کنید.
به‌طور پیش‌فرض، وقتی کاربر مکانی را انتخاب می‌کند، تکمیل خودکار تمام فیلدهای داده موجود را برای مکان انتخابی برمی‌گرداند و بر اساس آن صورتحساب به شما تعلق می‌گیرد. از Autocomplete.setFields() برای تعیین فیلدهای داده مکان برای بازگشت استفاده کنید. درباره شی PlaceResult ، از جمله لیستی از فیلدهای داده مکان که می توانید درخواست کنید، بیشتر بخوانید. برای جلوگیری از پرداخت هزینه برای داده‌هایی که به آنها نیاز ندارید، حتماً از Autocomplete.setFields() استفاده کنید تا فقط داده‌های مکانی را که استفاده می‌کنید مشخص کنید.
ویژگی name حاوی description مربوط به پیش‌بینی‌های تکمیل خودکار مکان‌ها است. می‌توانید درباره description در مستندات تکمیل خودکار مکان‌ها بیشتر بخوانید.
برای فرم های آدرس، دریافت آدرس در قالب ساختار یافته مفید است. برای برگرداندن آدرس ساخت یافته برای مکان انتخاب شده، Autocomplete.setFields() را فراخوانی کنید و فیلد address_components را مشخص کنید.
مثال زیر از تکمیل خودکار برای پر کردن فیلدها در فرم آدرس استفاده می کند.
TypeScript
functionfillInAddress(){// Get the place details from the autocomplete object.constplace=autocomplete.getPlace();letaddress1="";letpostcode="";// 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/3l5i5Mrfor(constcomponentofplace.address_componentsasgoogle.maps.GeocoderAddressComponent[]){// @ts-ignore remove once typings fixedconstcomponentType=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")asHTMLInputElement).value=component.long_name;break;case"administrative_area_level_1":{(document.querySelector("#state")asHTMLInputElement).value=component.short_name;break;}case"country":(document.querySelector("#country")asHTMLInputElement).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();}
functionfillInAddress(){// Get the place details from the autocomplete object.constplace=autocomplete.getPlace();letaddress1="";letpostcode="";// 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/3l5i5Mrfor(constcomponentofplace.address_components){// @ts-ignore remove once typings fixedconstcomponentType=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 فهرست گسترده‌ای از پیش‌بینی‌ها را ارائه می‌کند که می‌تواند شامل مکان‌ها (همانطور که توسط Places API تعریف شده است) به همراه عبارات جستجوی پیشنهادی باشد. برای مثال، اگر کاربر «پیتزا در جدید» را وارد کند، فهرست انتخاب ممکن است شامل عبارت «پیتزا در نیویورک، نیویورک» و همچنین نام فروشگاه‌های مختلف پیتزا باشد. هنگامی که کاربر مکانی را از لیست انتخاب می کند، اطلاعات مربوط به آن مکان به شی SearchBox بازگردانده می شود و می تواند توسط برنامه شما بازیابی شود.
سازنده SearchBox دو آرگومان می گیرد:
یک عنصر input HTML از نوع text . این فیلد ورودی است که سرویس SearchBox آن را نظارت کرده و نتایج خود را به آن پیوست می کند.
یک آرگومان options ، که می‌تواند حاوی ویژگی bounds باشد: bounds یک شی google.maps.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",()=>{constplaces=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.constbounds=newgoogle.maps.LatLngBounds();places.forEach((place)=>{if(!place.geometry||!place.geometry.location){console.log("Returned place contains no geometry");return;}consticon={url:place.iconasstring,size:newgoogle.maps.Size(71,71),origin:newgoogle.maps.Point(0,0),anchor:newgoogle.maps.Point(17,34),scaledSize:newgoogle.maps.Size(25,25),};// Create a marker for each place.markers.push(newgoogle.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);});
// Listen for the event fired when the user selects a prediction and retrieve// more details for that place.searchBox.addListener("places_changed",()=>{constplaces=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.constbounds=newgoogle.maps.LatLngBounds();places.forEach((place)=>{if(!place.geometry||!place.geometry.location){console.log("Returned place contains no geometry");return;}consticon={url:place.icon,size:newgoogle.maps.Size(71,71),origin:newgoogle.maps.Point(0,0),anchor:newgoogle.maps.Point(17,34),scaledSize:newgoogle.maps.Size(25,25),};// Create a marker for each place.markers.push(newgoogle.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() پیش بینی های مکان را برمی گرداند. توجه: «مکان» می‌تواند یک مؤسسه، موقعیت جغرافیایی یا نقطه‌ی مهم مورد علاقه باشد که توسط Places API تعریف شده است.
getQueryPredictions() لیست گسترده ای از پیش بینی ها را برمی گرداند که می تواند شامل مکان ها (همانطور که توسط Places API تعریف شده است) به همراه عبارات جستجوی پیشنهادی باشد. برای مثال، اگر کاربر «پیتزا در جدید» را وارد کند، فهرست انتخاب ممکن است شامل عبارت «پیتزا در نیویورک، نیویورک» و همچنین نام فروشگاه‌های مختلف پیتزا باشد.
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">functioninitService():void{constdisplaySuggestions=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)=>{constli=document.createElement("li");li.appendChild(document.createTextNode(prediction.description));(document.getElementById("results")asHTMLUListElement).appendChild(li);});};constservice=newgoogle.maps.places.AutocompleteService();service.getQueryPredictions({input:"pizza near Syd"},displaySuggestions);}declareglobal{interfaceWindow{initService:()=>void;}}window.initService=initService;
// 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">functioninitService(){constdisplaySuggestions=function(predictions,status){if(status!=google.maps.places.PlacesServiceStatus.OK||!predictions){alert(status);return;}predictions.forEach((prediction)=>{constli=document.createElement("li");li.appendChild(document.createTextNode(prediction.description));document.getElementById("results").appendChild(li);});};constservice=newgoogle.maps.places.AutocompleteService();service.getQueryPredictions({input:"pizza near Syd"},displaySuggestions);}window.initService=initService;
<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() ناشی می‌شود، استفاده کنید. در این حالت، درخواست تکمیل خودکار با درخواست جزئیات مکان ترکیب می شود و هزینه تماس به عنوان یک درخواست معمولی جزئیات مکان محاسبه می شود. برای درخواست تکمیل خودکار هزینه ای دریافت نمی شود.
مطمئن شوید که برای هر جلسه جدید یک نشانه جلسه منحصر به فرد ارسال می کنید. استفاده از یک نشانه برای بیش از یک جلسه تکمیل خودکار، آن جلسات تکمیل خودکار را باطل می‌کند و تمام درخواست‌های تکمیل خودکار در جلسات نامعتبر به صورت جداگانه با استفاده از تکمیل خودکار در هر درخواست SKU کسر می‌شود. درباره نشانه های جلسه بیشتر بخوانید .
مثال زیر ایجاد یک نشانه جلسه، سپس ارسال آن در AutocompleteService را نشان می دهد (عملکرد displaySuggestions() برای اختصار حذف شده است):
// Create a new session token.varsessionToken=newgoogle.maps.places.AutocompleteSessionToken();// Pass the token to the autocomplete service.varautocompleteService=newgoogle.maps.places.AutocompleteService();autocompleteService.getPlacePredictions({input:'pizza near Syd',sessionToken:sessionToken},displaySuggestions);
مطمئن شوید که برای هر جلسه جدید یک نشانه جلسه منحصر به فرد ارسال می کنید. استفاده از یک نشانه برای بیش از یک جلسه باعث می شود که هر درخواست به صورت جداگانه صورتحساب شود.
به‌طور پیش‌فرض، عناصر رابط کاربری ارائه‌شده توسط Autocomplete و SearchBox برای گنجاندن در نقشه Google سبک‌سازی می‌شوند. ممکن است بخواهید استایل را مطابق با سایت خود تنظیم کنید. کلاس های CSS زیر در دسترس هستند. همه کلاس‌های فهرست‌شده در زیر برای ویجت‌های Autocomplete و 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 باشد.
بهینه سازی تکمیل خودکار مکان
این بخش بهترین روش‌ها را توضیح می‌دهد تا به شما کمک کند از خدمات تکمیل خودکار مکان حداکثر استفاده را ببرید.
از همان ابتدا درک درستی از فیلدهای داده تکمیل خودکار مکان ضروری ایجاد کنید.
فیلدهای بایاس موقعیت و محدودیت مکان اختیاری هستند اما می توانند تأثیر قابل توجهی بر عملکرد تکمیل خودکار داشته باشند.
از مدیریت خطا استفاده کنید تا مطمئن شوید اگر API خطایی را برمی‌گرداند، برنامه شما به خوبی کاهش می‌یابد.
مطمئن شوید که برنامه شما وقتی انتخابی وجود ندارد کنترل می کند و راهی برای ادامه به کاربران ارائه می دهد.
بهترین شیوه های بهینه سازی هزینه
بهینه سازی هزینه پایه
برای بهینه‌سازی هزینه استفاده از سرویس تکمیل خودکار مکان، از ماسک‌های فیلد در ویجت‌های Place Details و Place Autocomplete استفاده کنید تا فقط فیلدهای داده مکان مورد نیازتان را برگردانید.
بهینه سازی هزینه پیشرفته
برای دسترسی به قیمت هر درخواست و درخواست نتایج Geocoding API در مورد مکان انتخابی به جای جزئیات مکان، اجرای برنامه‌ای تکمیل خودکار مکان را در نظر بگیرید. قیمت گذاری هر درخواست جفت شده با Geocoding API مقرون به صرفه تر از قیمت گذاری در هر جلسه (مبتنی بر جلسه) است اگر هر دو شرایط زیر رعایت شود:
اگر فقط به طول/طول جغرافیایی یا آدرس مکان انتخابی کاربر نیاز دارید، API Geocoding این اطلاعات را کمتر از یک تماس با جزئیات مکان ارائه می‌کند.
اگر کاربران یک پیش‌بینی تکمیل خودکار را در چهار درخواست پیش‌بینی تکمیل خودکار یا کمتر انتخاب کنند، ممکن است قیمت‌گذاری به ازای هر درخواست مقرون‌به‌صرفه‌تر از قیمت‌گذاری در هر جلسه باشد.
برای کمک به انتخاب پیاده‌سازی تکمیل خودکار مکان که متناسب با نیاز شماست، برگه‌ای را انتخاب کنید که با پاسخ شما به سؤال زیر مطابقت دارد.
آیا برنامه شما به اطلاعات دیگری غیر از آدرس و طول و عرض جغرافیایی پیش بینی انتخاب شده نیاز دارد؟
هزینه های ذکر شده در اینجا به USD هستند. لطفاً برای اطلاعات کامل قیمت به صفحه صورتحساب پلتفرم Google Maps مراجعه کنید.
بهترین شیوه های عملکرد
دستورالعمل‌های زیر روش‌هایی را برای بهینه‌سازی عملکرد تکمیل خودکار مکان توضیح می‌دهند:
محدودیت‌های کشور، سوگیری موقعیت و اولویت زبان (برای اجرای برنامه‌ای) را به پیاده‌سازی تکمیل خودکار مکان خود اضافه کنید. اولویت زبان با ویجت ها مورد نیاز نیست زیرا آنها اولویت های زبان را از مرورگر کاربر یا دستگاه تلفن همراه انتخاب می کنند.
اگر «تکمیل خودکار مکان» با نقشه همراه باشد، می‌توانید مکان را با درگاه نمای نقشه سوگیری کنید.
در شرایطی که کاربر یکی از پیش‌بینی‌های تکمیل خودکار را انتخاب نمی‌کند، عموماً چون هیچ یک از آن پیش‌بینی‌ها نشانی نتیجه دلخواه نیستند، می‌توانید از ورودی اصلی کاربر برای تلاش برای دریافت نتایج مرتبط‌تر دوباره استفاده کنید:
اگر انتظار دارید کاربر فقط اطلاعات آدرس را وارد کند، از ورودی اصلی کاربر در تماس با API جغرافیایی استفاده مجدد کنید.
اگر از کاربر انتظار دارید که پرس و جوهایی را برای مکان خاصی با نام یا آدرس وارد کند، از درخواست Find Place استفاده کنید. اگر نتایج فقط در یک منطقه خاص مورد انتظار است، از بایاس مکان استفاده کنید.
سناریوهای دیگر زمانی که بهتر است به API Geocoding برگردید عبارتند از:
کاربرانی که آدرس‌های فرعی را وارد می‌کنند، مانند آدرس‌های واحدها یا آپارتمان‌های خاص در یک ساختمان. به عنوان مثال، آدرس چک "Stroupežnického 3191/17, Praha" یک پیش بینی جزئی در تکمیل خودکار مکان به دست می دهد.
کاربرانی که آدرس هایی را با پیشوندهای قطعه جاده مانند "23-30 29 خیابان ، کوئینز" در شهر نیویورک یا "47-380 Kamehameha Hwy ، Kaneohe" در جزیره Kauai در هاوایی وارد می کنند.
تاریخ آخرین به‌روزرسانی 2025-01-14 بهوقت ساعت هماهنگ جهانی.
[null,null,["تاریخ آخرین به‌روزرسانی 2025-01-14 بهوقت ساعت هماهنگ جهانی."],[[["Google Maps Place Autocomplete predicts places, addresses, and plus codes as users type, similar to the Google Maps search bar."],["Autocomplete is available through UI widgets (Autocomplete, SearchBox) and programmatically via AutocompleteService."],["Developers can customize predictions using options like place types, search area, and country restrictions."],["Place Autocomplete usage is subject to billing; optimize costs by carefully selecting data fields and session management strategies."],["Programmatic requests benefit from using session tokens for billing efficiency and grouping related queries."]]],[]]
