مقدمه
تکمیل خودکار (جدید) یک سرویس وب است که پیشبینیهای مکان و پیشبینیهای پرسوجو را در پاسخ به یک درخواست HTTP برمیگرداند. در درخواست، یک رشته جستجوی متنی و مرزهای جغرافیایی که منطقه جستجو را کنترل میکنند، مشخص کنید.
تکمیل خودکار (جدید) میتواند کلمات کامل و زیررشتههای ورودی را تطبیق دهد و نام مکانها، آدرسها و کدهای پلاس را حل کند. بنابراین، برنامهها میتوانند همزمان با تایپ کاربر، پرسوجوها را ارسال کنند تا پیشبینیهای مکان و پرسوجو را در لحظه ارائه دهند.
پاسخ از تکمیل خودکار (جدید) میتواند شامل دو نوع پیشبینی باشد:
- پیشبینی مکانها : مکانها، مانند کسبوکارها، آدرسها و نقاط مورد علاقه، بر اساس رشته متن ورودی مشخص شده و ناحیه جستجو. پیشبینیهای مکان به طور پیشفرض بازگردانده میشوند.
- پیشبینیهای پرسوجو : رشتههای پرسوجو که با رشته متن ورودی و ناحیه جستجو مطابقت دارند. پیشبینیهای پرسوجو بهطور پیشفرض بازگردانده نمیشوند. از پارامتر درخواست
includeQueryPredictionsبرای افزودن پیشبینیهای پرسوجو به پاسخ استفاده کنید.
برای مثال، شما با استفاده از رشتهای که شامل بخشی از ورودی کاربر، "Sicilian piz" است و ناحیه جستجو به سانفرانسیسکو، کالیفرنیا محدود شده است، Autocomplete (جدید) را فراخوانی میکنید. سپس پاسخ شامل فهرستی از پیشبینیهای مکان است که با رشته جستجو و ناحیه جستجو مطابقت دارند، مانند رستورانی با نام "Sicilian Pizza Kitchen" به همراه جزئیاتی در مورد مکان.
پیشبینیهای مکانهای بازگشتی به گونهای طراحی شدهاند که به کاربر ارائه شوند تا در انتخاب مکان مورد نظر به او کمک کنند. میتوانید برای دریافت اطلاعات بیشتر در مورد هر یک از پیشبینیهای مکان بازگشتی، درخواست « جزئیات مکان (جدید)» ارسال کنید.
پاسخ همچنین میتواند شامل فهرستی از پیشبینیهای پرسوجو باشد که با رشته جستجو و ناحیه جستجو مطابقت دارند، مانند "پیتزا و پاستای سیسیلی". هر پیشبینی پرسوجو در پاسخ شامل فیلد text حاوی یک رشته جستجوی متن پیشنهادی است. از آن رشته به عنوان ورودی برای جستجوی متن (جدید) برای انجام جستجوی دقیقتر استفاده کنید.
مرورگر APIها به شما امکان میدهد درخواستهای زنده ارسال کنید تا بتوانید با API و گزینههای API آشنا شوید:
تکمیل خودکار درخواستها (جدید)
یک درخواست تکمیل خودکار (جدید) یک درخواست HTTP POST به یک URL به شکل زیر است:
https://places.googleapis.com/v1/places:autocomplete
تمام پارامترها را در بدنه درخواست JSON یا در هدرها به عنوان بخشی از درخواست POST ارسال کنید. برای مثال:
curl -X POST -d '{
"input": "pizza",
"locationBias": {
"circle": {
"center": {
"latitude": 37.7937,
"longitude": -122.3965
},
"radius": 500.0
}
}
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
https://places.googleapis.com/v1/places:autocomplete
پارامترهای پشتیبانی شده
پارامتر | توضیحات |
|---|---|
| رشته متنی برای جستجو (کلمات کامل، زیررشتهها، نام مکانها، آدرسها، بهعلاوه کدها). |
| فهرستی که با کاما از هم جدا شده و مشخص میکند کدام فیلدها در پاسخ برگردانده شوند. |
نتایج را به مکانهایی محدود میکند که با یکی از حداکثر پنج نوع اصلی مشخصشده مطابقت دارند. | |
اگر درست باشد، شامل کسبوکارهایی میشود که مکان فیزیکی ندارند (کسبوکارهای منطقه خدماتی). پیشفرض روی نادرست است. | |
اگر درست باشد، هم پیشبینیهای مکان و هم پیشبینیهای پرسوجو را در پاسخ لحاظ میکند. پیشفرضها نادرست است. | |
آرایهای از حداکثر ۱۵ کد کشور دو کاراکتری برای محدود کردن نتایج به آنها. | |
آفست کاراکتر یونیکد مبتنی بر صفر موقعیت مکاننما در رشته ورودی، که بر پیشبینیها تأثیر میگذارد. پیشفرض روی طول ورودی. | |
زبان ترجیحی (کد IETF BCP-47) برای نتایج. پیشفرضها روی Accept-Language header یا 'en' است. | |
یک ناحیه (دایره یا مستطیل) را مشخص میکند تا نتایج جستجو به سمت آن متمایل شوند و نتایج خارج از آن ناحیه نمایش داده شوند. نمیتوان از آن با locationRestriction استفاده کرد. | |
یک ناحیه (دایره یا مستطیل) را برای محدود کردن نتایج جستجو در داخل آن مشخص میکند. نتایج خارج از این ناحیه حذف میشوند. نمیتوان از آن با locationBias استفاده کرد. | |
نقطه مبدا (عرض، طول) که برای محاسبه فاصله مستقیم (distanceMeters) تا مقاصد پیشبینیشده استفاده میشود. | |
کد منطقه مورد استفاده برای قالببندی پاسخ و پیشنهادهای بایاس (مثلاً «uk»، «fr»). | |
رشته تولید شده توسط کاربر برای گروهبندی فراخوانیهای تکمیل خودکار در یک جلسه برای اهداف صدور صورتحساب. |
درباره پاسخ
تکمیل خودکار (جدید) یک شیء JSON را به عنوان پاسخ برمیگرداند. در پاسخ:
- آرایه
suggestionsشامل تمام مکانها و پرسوجوهای پیشبینیشده به ترتیب بر اساس ارتباط درکشده آنها است. هر مکان توسط یک فیلدplacePredictionو هر پرسوجو توسط یک فیلدqueryPredictionنمایش داده میشود. - فیلد
placePredictionشامل اطلاعات دقیقی در مورد پیشبینی یک مکان واحد، از جمله شناسه مکان و توضیحات متنی است. - فیلد
queryPredictionشامل اطلاعات دقیقی در مورد یک پیشبینی پرسوجوی واحد است.
شیء کامل JSON به شکل زیر است:
{
"suggestions": [
{
"placePrediction": {
"place": "places/ChIJ5YQQf1GHhYARPKG7WLIaOko",
"placeId": "ChIJ5YQQf1GHhYARPKG7WLIaOko",
"text": {
"text": "Amoeba Music, Haight Street, San Francisco, CA, USA",
"matches": [
{
"endOffset": 6
}]
},
...
},
{
"queryPrediction": {
"text": {
"text": "Amoeba Music",
"matches": [
{
"endOffset": 6
}]
},
...
}
...]
}پارامترهای مورد نیاز
ورودی
رشته متنی که جستجو روی آن انجام میشود. کلمات کامل و زیررشتهها، نام مکانها، آدرسها و کدهای اضافی را مشخص کنید. سرویس تکمیل خودکار (جدید) تطابقهای کاندید را بر اساس این رشته برمیگرداند و نتایج را بر اساس ارتباط درک شده آنها مرتب میکند.
پارامترهای اختیاری
فیلد ماسک
با ایجاد یک ماسک فیلد پاسخ، لیست فیلدهایی را که باید در پاسخ برگردانده شوند، مشخص کنید. ماسک فیلد پاسخ را با استفاده از هدر HTTP
X-Goog-FieldMaskبه متد ارسال کنید.لیستی از فیلدهای پیشنهادی که با کاما از هم جدا شدهاند را برای برگرداندن مشخص کنید. برای مثال، برای بازیابی
suggestions.placePrediction.text.textوsuggestions.queryPrediction.text.textاز پیشنهاد.X-Goog-FieldMask: suggestions.placePrediction.text.text,suggestions.queryPrediction.text.text
برای بازیابی همه فیلدها از
*استفاده کنید.X-Goog-FieldMask: *
شامل انواع اولیه
یک مکان فقط میتواند یک نوع اصلی از انواع فهرستشده در جدول A یا جدول B داشته باشد. برای مثال، نوع اصلی ممکن است
"mexican_restaurant"یا"steak_house"باشد.به طور پیشفرض، API تمام مکانها را بر اساس پارامتر
input، صرف نظر از مقدار نوع اصلی مرتبط با مکان، برمیگرداند. با ارسال پارامترincludedPrimaryTypes، نتایج را به یک نوع اصلی خاص یا انواع اصلی محدود کنید.از این پارامتر برای مشخص کردن حداکثر پنج مقدار نوع از جدول A یا جدول B استفاده کنید. یک مکان باید با یکی از مقادیر نوع اولیه مشخص شده مطابقت داشته باشد تا در پاسخ گنجانده شود.
این پارامتر همچنین میتواند شامل یکی از
(regions)یا(cities)باشد. فیلترهای مجموعه نوع(regions)برای مناطق یا بخشها، مانند محلهها و کدهای پستی، استفاده میشوند. فیلترهای مجموعه نوع(cities)برای مکانهایی است که گوگل به عنوان شهر شناسایی میکند.درخواست با خطای
INVALID_REQUESTرد میشود اگر:- بیش از پنج نوع مشخص شده است.
- هر نوعی علاوه بر
(cities)یا(regions)مشخص شده است. - هر نوع ناشناختهای مشخص شده است.
شامل PureServiceAreaBusinesses
اگر روی
trueتنظیم شود، پاسخ شامل کسبوکارهایی میشود که مستقیماً به مشتریان مراجعه میکنند یا به آنها کالا ارسال میکنند، اما مکان فیزیکی برای کسبوکار ندارند. اگر رویfalseتنظیم شود، API فقط کسبوکارهایی را برمیگرداند که مکان فیزیکی برای کسبوکار دارند.شامل پیشبینیهای پرسوجو
اگر
true، پاسخ شامل پیشبینیهای مکان و پرسوجو میشود. مقدار پیشفرض آنfalseاست، به این معنی که پاسخ فقط شامل پیشبینیهای مکان است.شاملکدهای منطقه
فقط نتایجی از لیست مناطق مشخص شده را در نظر بگیرید، که به صورت آرایهای با حداکثر ۱۵ مقدار دو کاراکتری ccTLD ("دامنه سطح بالا") مشخص شدهاند. در صورت حذف، هیچ محدودیتی برای پاسخ اعمال نمیشود. به عنوان مثال، برای محدود کردن مناطق به آلمان و فرانسه:
"includedRegionCodes": ["de", "fr"]
اگر هر دو
locationRestrictionوincludedRegionCodesرا مشخص کنید، نتایج در ناحیه تقاطع این دو تنظیم قرار میگیرند.ورودی-آفست
آفست کاراکتر یونیکد مبتنی بر صفر که موقعیت مکاننما را در
inputنشان میدهد. موقعیت مکاننما میتواند بر پیشبینیهای برگشتی تأثیر بگذارد. اگر خالی باشد، به طور پیشفرض به طولinputتنظیم میشود.زبانکد
زبان ترجیحی برای برگرداندن نتایج. اگر زبان مورد استفاده در
inputبا مقدار مشخص شده توسطlanguageCodeمتفاوت باشد، یا اگر مکان برگردانده شده ترجمهای از زبان محلی بهlanguageCodeنداشته باشد، نتایج ممکن است به زبانهای ترکیبی باشند.- برای مشخص کردن زبان ترجیحی باید از کدهای زبان IETF BCP-47 استفاده کنید.
- اگر
languageCodeارائه نشود، API از مقداری که در سربرگAccept-Languageمشخص شده است استفاده میکند. اگر هیچکدام مشخص نشود، مقدار پیشفرضenاست. اگر کد زبان نامعتبری را مشخص کنید، API خطایINVALID_ARGUMENTرا برمیگرداند. - زبان ترجیحی تأثیر کمی بر مجموعه نتایجی که API برای برگرداندن انتخاب میکند و ترتیب برگرداندن آنها دارد. این موضوع همچنین بر توانایی API در اصلاح خطاهای املایی تأثیر میگذارد.
- این API تلاش میکند آدرس خیابانی را ارائه دهد که هم برای کاربر و هم برای جمعیت محلی قابل خواندن باشد، و در عین حال ورودی کاربر را نیز منعکس کند. پیشبینیهای مکان بسته به ورودی کاربر در هر درخواست، قالببندی متفاوتی دارند.
- ابتدا عبارات منطبق در پارامتر
input، با استفاده از نامهایی که با ترجیح زبانی مشخص شده توسط پارامترlanguageCodeدر صورت وجود، همسو هستند، انتخاب میشوند، در غیر این صورت از نامهایی استفاده میشود که به بهترین وجه با ورودی کاربر مطابقت دارند. - آدرسهای خیابان به زبان محلی و در صورت امکان به خطی که توسط کاربر قابل خواندن باشد، قالببندی میشوند، تنها پس از اینکه عبارات منطبق برای مطابقت با عبارات موجود در پارامتر
inputانتخاب شدند. - تمام آدرسهای دیگر پس از انتخاب عبارات منطبق برای مطابقت با عبارات موجود در پارامتر
input، به زبان دلخواه برگردانده میشوند. اگر نامی به زبان دلخواه موجود نباشد، API از نزدیکترین مورد منطبق استفاده میکند.
- ابتدا عبارات منطبق در پارامتر
سوگیری مکانی یا محدودیت مکانی
شما میتوانید
locationBiasیاlocationRestrictionبرای تعریف ناحیه جستجو مشخص کنید، اما نه هر دو را.locationRestrictionرا به عنوان مشخص کننده ناحیهای که نتایج باید درون آن باشند، وlocationBiasبه عنوان مشخص کننده ناحیهای که نتایج باید نزدیک به آن باشند اما میتوانند خارج از آن ناحیه باشند، در نظر بگیرید.موقعیت مکانی
یک منطقه برای جستجو مشخص میکند. این مکان به عنوان یک بایاس عمل میکند، به این معنی که نتایج اطراف مکان مشخص شده، از جمله نتایج خارج از منطقه مشخص شده، میتوانند بازگردانده شوند.
محدودیت مکانی
محدودهای را برای جستجو مشخص میکند. نتایج خارج از محدوده مشخص شده بازگردانده نمیشوند.
ناحیه
locationBiasیاlocationRestrictionرا به عنوان یک Viewport مستطیلی یا به عنوان یک دایره مشخص کنید.یک دایره با نقطه مرکزی و شعاع بر حسب متر تعریف میشود. شعاع باید بین 0.0 تا 50000.0 باشد، که شامل همه میشود. مقدار پیشفرض 0.0 است. برای
locationRestriction، باید شعاع را روی مقداری بزرگتر از 0.0 تنظیم کنید. در غیر این صورت، درخواست هیچ نتیجهای برنمیگرداند.برای مثال:
"locationBias": { "circle": { "center": { "latitude": 37.7937, "longitude": -122.3965 }, "radius": 500.0 } }
مستطیل، یک دریچه دید طول و عرض جغرافیایی است که به صورت دو نقطه
lowو بالا که به صورت مورب روبروی هم قرار دارند، نمایش داده میشود. یک دریچه دید، یک منطقه بسته در نظر گرفته میشود، به این معنی که شامل مرز خود نیز میشود. محدودههای عرض جغرافیایی باید بین ۹۰- تا ۹۰ درجه و محدودههای طول جغرافیایی باید بین ۱۸۰- تا ۱۸۰ درجه باشند:- اگر
low=high، نمای دید از آن نقطه واحد تشکیل شده است. - اگر
low.longitude>high.longitude، محدوده طول جغرافیایی معکوس میشود (صفحه نمایش از خط طول جغرافیایی ۱۸۰ درجه عبور میکند). - اگر
low.longitude= -180 درجه وhigh.longitude= 180 درجه باشد، صفحه نمایش شامل تمام طولهای جغرافیایی میشود. - اگر
low.longitude= 180 درجه وhigh.longitude= -180 درجه باشد، محدوده طول جغرافیایی خالی است.
هر دو پارامتر
lowوhighباید پر شوند و کادر نمایش داده شده نمیتواند خالی باشد. یک viewport خالی منجر به خطا میشود.برای مثال، این نمای کلی، شهر نیویورک را به طور کامل در بر میگیرد:
"locationBias": { "rectangle": { "low": { "latitude": 40.477398, "longitude": -74.259087 }, "high": { "latitude": 40.91618, "longitude": -73.70018 } } }
- اگر
منشأ
نقطه مبدا که از آن فاصله مستقیم تا مقصد محاسبه میشود (به صورت
distanceMetersبرگردانده میشود). اگر این مقدار حذف شود، فاصله مستقیم برگردانده نمیشود. باید به صورت مختصات طول و عرض جغرافیایی مشخص شود:"origin": { "latitude": 40.477398, "longitude": -74.259087 }
کد منطقه
کد منطقهای مورد استفاده برای قالببندی پاسخ، که به عنوان یک مقدار دو کاراکتری ccTLD ("دامنه سطح بالا") مشخص شده است. اکثر کدهای ccTLD با کدهای ISO 3166-1 یکسان هستند، با برخی استثنائات قابل توجه. به عنوان مثال، ccTLD بریتانیا "uk" (.co.uk) است در حالی که کد ISO 3166-1 آن "gb" است (از نظر فنی برای موجودیت "پادشاهی متحده بریتانیای کبیر و ایرلند شمالی").
پیشنهادها همچنین بر اساس کدهای منطقهای ارائه میشوند. گوگل توصیه میکند که
regionCodeبر اساس ترجیح منطقهای کاربر تنظیم کنید.اگر کد منطقه نامعتبری را مشخص کنید، API خطای
INVALID_ARGUMENTرا برمیگرداند. این پارامتر میتواند بر اساس قانون مربوطه بر نتایج تأثیر بگذارد.توکن جلسه
توکنهای جلسه، رشتههای تولید شده توسط کاربر هستند که فراخوانیهای تکمیل خودکار (جدید) را به عنوان "جلسات" ردیابی میکنند. تکمیل خودکار (جدید) از توکنهای جلسه برای گروهبندی مراحل پرسوجو و انتخاب یک جستجوی تکمیل خودکار کاربر در یک جلسه مجزا برای اهداف صورتحساب استفاده میکند. برای اطلاعات بیشتر، به توکنهای جلسه مراجعه کنید.
انتخاب پارامترها برای بایاس کردن نتایج
پارامترهای تکمیل خودکار (جدید) میتوانند به طور متفاوتی بر نتایج جستجو تأثیر بگذارند. جدول زیر توصیههایی برای استفاده از پارامترها بر اساس نتیجه مورد نظر ارائه میدهد.| پارامتر | توصیه استفاده |
|---|---|
regionCode | بر اساس اولویت منطقهای کاربر تنظیم شود. |
includedRegionCodes | تنظیم کنید تا نتایج به فهرست مناطق مشخصشده محدود شود. |
locationBias | زمانی استفاده میشود که نتایج در داخل یا اطراف یک منطقه ترجیح داده میشوند. در صورت لزوم، منطقه را به عنوان نمای نقشهای که کاربر به آن نگاه میکند تعریف کنید. |
locationRestriction | فقط زمانی استفاده شود که نتایج خارج از یک منطقه نباید برگردانده شوند. |
origin | زمانی استفاده میشود که فاصلهی مستقیم تا هر پیشبینی مد نظر باشد. |
مثالهای تکمیل خودکار (جدید)
محدود کردن جستجو به یک منطقه با استفاده از locationRestriction
locationRestriction ناحیه مورد جستجو را مشخص میکند. نتایج خارج از ناحیه مشخص شده بازگردانده نمیشوند. در مثال زیر، شما locationRestriction برای محدود کردن درخواست به دایرهای به شعاع ۵۰۰۰ متر با مرکز سانفرانسیسکو استفاده میکنید:
curl -X POST -d '{
"input": "Art museum",
"locationRestriction": {
"circle": {
"center": {
"latitude": 37.7749,
"longitude": -122.4194
},
"radius": 5000.0
}
}
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
https://places.googleapis.com/v1/places:autocomplete
تمام نتایج حاصل از محدودههای مشخص شده در آرایه suggestions قرار میگیرند:
{ "suggestions": [ { "placePrediction": { "place": "places/ChIJkQQVTZqAhYARHxPt2iJkm1Q", "placeId": "ChIJkQQVTZqAhYARHxPt2iJkm1Q", "text": { "text": "Asian Art Museum, Larkin Street, San Francisco, CA, USA", "matches": [ { "startOffset": 6, "endOffset": 16 } ] }, "structuredFormat": { "mainText": { "text": "Asian Art Museum", "matches": [ { "startOffset": 6, "endOffset": 16 } ] }, "secondaryText": { "text": "Larkin Street, San Francisco, CA, USA" } }, "types": [ "establishment", "museum", "point_of_interest" ] } }, { "placePrediction": { "place": "places/ChIJI7NivpmAhYARSuRPlbbn_2w", "placeId": "ChIJI7NivpmAhYARSuRPlbbn_2w", "text": { "text": "de Young Museum, Hagiwara Tea Garden Drive, San Francisco, CA, USA", "matches": [ { "endOffset": 15 } ] }, "structuredFormat": { "mainText": { "text": "de Young Museum", "matches": [ { "endOffset": 15 } ] }, "secondaryText": { "text": "Hagiwara Tea Garden Drive, San Francisco, CA, USA" } }, "types": [ "establishment", "point_of_interest", "tourist_attraction", "museum" ] } }, /.../ ] }
همچنین میتوانید locationRestriction برای محدود کردن جستجوها به یک Viewport مستطیلی استفاده کنید. مثال زیر درخواست را به مرکز شهر سانفرانسیسکو محدود میکند:
curl -X POST -d '{
"input": "Art museum",
"locationRestriction": {
"rectangle": {
"low": {
"latitude": 37.7751,
"longitude": -122.4219
},
"high": {
"latitude": 37.7955,
"longitude": -122.3937
}
}
}
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
https://places.googleapis.com/v1/places:autocomplete
نتایج در آرایه suggestions قرار دارند:
{ "suggestions": [ { "placePrediction": { "place": "places/ChIJkQQVTZqAhYARHxPt2iJkm1Q", "placeId": "ChIJkQQVTZqAhYARHxPt2iJkm1Q", "text": { "text": "Asian Art Museum, Larkin Street, San Francisco, CA, USA", "matches": [ { "startOffset": 6, "endOffset": 16 } ] }, "structuredFormat": { "mainText": { "text": "Asian Art Museum", "matches": [ { "startOffset": 6, "endOffset": 16 } ] }, "secondaryText": { "text": "Larkin Street, San Francisco, CA, USA" } }, "types": [ "point_of_interest", "museum", "establishment" ] } }, { "placePrediction": { "place": "places/ChIJyQNK-4SAhYARO2DZaJleWRc", "placeId": "ChIJyQNK-4SAhYARO2DZaJleWRc", "text": { "text": "International Art Museum of America, Market Street, San Francisco, CA, USA", "matches": [ { "startOffset": 14, "endOffset": 24 } ] }, "structuredFormat": { "mainText": { "text": "International Art Museum of America", "matches": [ { "startOffset": 14, "endOffset": 24 } ] }, "secondaryText": { "text": "Market Street, San Francisco, CA, USA" } }, "types": [ "museum", "point_of_interest", "tourist_attraction", "art_gallery", "establishment" ] } } ] }
جستجوی بایاس به یک منطقه با استفاده از locationBias
با locationBias ، مکان به عنوان یک بایاس عمل میکند، به این معنی که نتایج اطراف مکان مشخص شده، از جمله نتایج خارج از منطقه مشخص شده، میتوانند بازگردانده شوند. در مثال زیر، شما درخواست را به مرکز شهر سانفرانسیسکو بایاس میکنید:
curl -X POST -d '{
"input": "Amoeba",
"locationBias": {
"circle": {
"center": {
"latitude": 37.7749,
"longitude": -122.4194
},
"radius": 5000.0
}
}
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
https://places.googleapis.com/v1/places:autocomplete
نتایج اکنون شامل موارد بسیار بیشتری است، از جمله نتایج خارج از شعاع ۵۰۰۰ متر:
{ "suggestions": [ { "placePrediction": { "place": "places/ChIJ5YQQf1GHhYARPKG7WLIaOko", "placeId": "ChIJ5YQQf1GHhYARPKG7WLIaOko", "text": { "text": "Amoeba Music, Haight Street, San Francisco, CA, USA", "matches": [ { "endOffset": 6 } ] }, "structuredFormat": { "mainText": { "text": "Amoeba Music", "matches": [ { "endOffset": 6 } ] }, "secondaryText": { "text": "Haight Street, San Francisco, CA, USA" } }, "types": [ "electronics_store", "point_of_interest", "store", "establishment", "home_goods_store" ] } }, { "placePrediction": { "place": "places/ChIJr7uwwy58hYARBY-e7-QVwqw", "placeId": "ChIJr7uwwy58hYARBY-e7-QVwqw", "text": { "text": "Amoeba Music, Telegraph Avenue, Berkeley, CA, USA", "matches": [ { "endOffset": 6 } ] }, "structuredFormat": { "mainText": { "text": "Amoeba Music", "matches": [ { "endOffset": 6 } ] }, "secondaryText": { "text": "Telegraph Avenue, Berkeley, CA, USA" } }, "types": [ "electronics_store", "point_of_interest", "establishment", "home_goods_store", "store" ] } }, ... ] }
همچنین میتوانید locationBias برای جهتدهی جستجوها به یک Viewport مستطیلی استفاده کنید. مثال زیر درخواست را به مرکز شهر سانفرانسیسکو محدود میکند:
curl -X POST -d '{
"input": "Amoeba",
"locationBias": {
"rectangle": {
"low": {
"latitude": 37.7751,
"longitude": -122.4219
},
"high": {
"latitude": 37.7955,
"longitude": -122.3937
}
}
}
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
https://places.googleapis.com/v1/places:autocomplete
اگرچه نتایج جستجو در نمای مستطیلی در پاسخ ظاهر میشوند، اما برخی از نتایج به دلیل بایاس، خارج از مرزهای تعریفشده هستند. نتایج همچنین در آرایه suggestions قرار میگیرند:
{ "suggestions": [ { "placePrediction": { "place": "places/ChIJ5YQQf1GHhYARPKG7WLIaOko", "placeId": "ChIJ5YQQf1GHhYARPKG7WLIaOko", "text": { "text": "Amoeba Music, Haight Street, San Francisco, CA, USA", "matches": [ { "endOffset": 6 } ] }, "structuredFormat": { "mainText": { "text": "Amoeba Music", "matches": [ { "endOffset": 6 } ] }, "secondaryText": { "text": "Haight Street, San Francisco, CA, USA" } }, "types": [ "point_of_interest", "store", "establishment" ] } }, { "placePrediction": { "place": "places/ChIJr7uwwy58hYARBY-e7-QVwqw", "placeId": "ChIJr7uwwy58hYARBY-e7-QVwqw", "text": { "text": "Amoeba Music, Telegraph Avenue, Berkeley, CA, USA", "matches": [ { "endOffset": 6 } ] }, "structuredFormat": { "mainText": { "text": "Amoeba Music", "matches": [ { "endOffset": 6 } ] }, "secondaryText": { "text": "Telegraph Avenue, Berkeley, CA, USA" } }, "types": [ "point_of_interest", "store", "establishment" ] } }, { "placePrediction": { "place": "places/ChIJRdmfADq_woARYaVhnfQSUTI", "placeId": "ChIJRdmfADq_woARYaVhnfQSUTI", "text": { "text": "Amoeba Music, Hollywood Boulevard, Los Angeles, CA, USA", "matches": [ { "endOffset": 6 } ] }, "structuredFormat": { "mainText": { "text": "Amoeba Music", "matches": [ { "endOffset": 6 } ] }, "secondaryText": { "text": "Hollywood Boulevard, Los Angeles, CA, USA" } }, "types": [ "point_of_interest", "store", "establishment" ] } }, /.../ ] }
از includedPrimaryTypes استفاده کنید
از پارامتر includedPrimaryTypes برای مشخص کردن حداکثر پنج مقدار نوع از جدول A ، جدول B ، یا فقط (regions) یا فقط (cities) استفاده کنید. یک مکان باید با یکی از مقادیر نوع اصلی مشخص شده مطابقت داشته باشد تا در پاسخ گنجانده شود.
در مثال زیر، شما یک رشته input از نوع "Soccer" تعیین میکنید و از پارامتر includedPrimaryTypes برای محدود کردن نتایج به فروشگاههایی از نوع "sporting_goods_store" استفاده میکنید:
curl -X POST -d '{
"input": "Soccer",
"includedPrimaryTypes": ["sporting_goods_store"],
"locationBias": {
"circle": {
"center": {
"latitude": 37.7749,
"longitude": -122.4194
},
"radius": 500.0
}
}
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
https://places.googleapis.com/v1/places:autocomplete
اگر پارامتر includedPrimaryTypes حذف کنید، نتایج میتوانند شامل موسساتی از نوعی باشند که شما نمیخواهید، مانند "athletic_field" .
درخواست پیشبینیهای پرسوجو
پیشبینیهای پرسوجو بهطور پیشفرض بازگردانده نمیشوند. از پارامتر درخواست includeQueryPredictions برای افزودن پیشبینیهای پرسوجو به پاسخ استفاده کنید. برای مثال:
curl -X POST -d '{
"input": "Amoeba",
"includeQueryPredictions": true,
"locationBias": {
"circle": {
"center": {
"latitude": 37.7749,
"longitude": -122.4194
},
"radius": 5000.0
}
}
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
https://places.googleapis.com/v1/places:autocomplete
آرایه suggestions اکنون شامل پیشبینیهای مکان و پیشبینیهای پرسوجو است، همانطور که در بالا در بخش «درباره پاسخ» نشان داده شده است. هر پیشبینی پرسوجو شامل فیلد text حاوی یک رشته جستجوی متن پیشنهادی است. میتوانید برای دریافت اطلاعات بیشتر در مورد هر یک از پیشبینیهای پرسوجوی برگشتی، یک درخواست جستجوی متن (جدید) ارسال کنید.
از مبدا استفاده کنید
در این مثال، origin به عنوان مختصات طول و عرض جغرافیایی در درخواست وارد کنید. وقتی origin وارد میکنید، تکمیل خودکار (جدید) فیلد distanceMeters را در پاسخ وارد میکند که شامل فاصله مستقیم از origin تا مقصد است. این مثال مبدا را روی مرکز سانفرانسیسکو تنظیم میکند:
curl -X POST -d '{
"input": "Amoeba",
"origin": {
"latitude": 37.7749,
"longitude": -122.4194
},
"locationRestriction": {
"circle": {
"center": {
"latitude": 37.7749,
"longitude": -122.4194
},
"radius": 5000.0
}
}
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
https://places.googleapis.com/v1/places:autocomplete
پاسخ اکنون شامل distanceMeters است:
{ "suggestions": [ { "placePrediction": { "place": "places/ChIJ5YQQf1GHhYARPKG7WLIaOko", "placeId": "ChIJ5YQQf1GHhYARPKG7WLIaOko", "text": { "text": "Amoeba Music, Haight Street, San Francisco, CA, USA", "matches": [ { "endOffset": 6 } ] }, "structuredFormat": { "mainText": { "text": "Amoeba Music", "matches": [ { "endOffset": 6 } ] }, "secondaryText": { "text": "Haight Street, San Francisco, CA, USA" } }, "types": [ "home_goods_store", "establishment", "point_of_interest", "store", "electronics_store" ], "distanceMeters": 3012 } } ] }
فاصله از پاسخ غایب است
در موارد خاص، حتی زمانی که origin در درخواست گنجانده شده باشد، distanceMeters در بدنه پاسخ وجود ندارد. این ممکن است در سناریوهای زیر اتفاق بیفتد:
-
distanceMetersبرای پیشبینیrouteلحاظ نشده است. -
distanceMetersوقتی مقدارش0باشد، لحاظ نمیشود، که این مورد برای پیشبینیهایی است که کمتر از ۱ متر از مکانoriginارائه شده فاصله دارند.
کتابخانههای کلاینت که سعی در خواندن فیلد distanceMeters از یک شیء تجزیهشده دارند، فیلدی با مقدار 0 را برمیگردانند. برای جلوگیری از گمراهی کاربران، فاصله صفر را به کاربران نمایش ندهید .
بهینهسازی تکمیل خودکار (جدید)
این بخش بهترین شیوهها را برای کمک به شما در استفاده بهینه از سرویس تکمیل خودکار (جدید) شرح میدهد.
در اینجا چند دستورالعمل کلی آورده شده است:
- سریعترین راه برای توسعه یک رابط کاربری کارآمد، استفاده از ویجت تکمیل خودکار Maps JavaScript API (جدید) ، ویجت Places SDK برای تکمیل خودکار Android (جدید) یا ویجت Places SDK برای تکمیل خودکار iOS (جدید) است.
- فیلدهای داده ضروری تکمیل خودکار (جدید) را از ابتدا درک کنید.
- فیلدهای Location biasing و location restriction اختیاری هستند اما میتوانند تأثیر قابل توجهی بر عملکرد تکمیل خودکار داشته باشند.
- از مدیریت خطا استفاده کنید تا مطمئن شوید که برنامه شما در صورت بروز خطا توسط API، به طور مناسب از رده خارج میشود.
- مطمئن شوید که برنامه شما وقتی هیچ انتخابی وجود ندارد، کار میکند و به کاربران راهی برای ادامه ارائه میدهد.
بهترین شیوههای بهینهسازی هزینه
بهینهسازی هزینه پایه
برای بهینهسازی هزینه استفاده از سرویس تکمیل خودکار (جدید)، از ماسکهای فیلد در ویجتهای جزئیات مکان (جدید) و تکمیل خودکار (جدید) استفاده کنید تا فقط فیلدهای داده تکمیل خودکار (جدید) مورد نیاز خود را برگردانید.
بهینهسازی پیشرفته هزینه
پیادهسازی برنامهریزیشدهی Autocomplete (جدید) را برای دسترسی به SKU در نظر بگیرید: Autocomplete درخواست قیمتگذاری و درخواست نتایج Geocoding API در مورد مکان انتخابشده به جای Place Details (جدید). قیمتگذاری بر اساس درخواست همراه با Geocoding API در صورت برآورده شدن هر دو شرط زیر، مقرونبهصرفهتر از قیمتگذاری بر اساس هر جلسه (مبتنی بر جلسه) است:
- اگر فقط به طول/عرض جغرافیایی یا آدرس مکان انتخاب شده کاربر نیاز دارید، API مربوط به Geocoding این اطلاعات را با هزینهای کمتر از فراخوانی Place Details (New) ارائه میدهد.
- اگر کاربران به طور متوسط از بین چهار درخواست پیشبینی تکمیل خودکار (جدید) یا کمتر، یک پیشبینی تکمیل خودکار را انتخاب کنند، قیمتگذاری بر اساس هر درخواست ممکن است مقرون به صرفهتر از قیمتگذاری بر اساس هر جلسه باشد.
آیا درخواست شما به اطلاعات دیگری غیر از آدرس و طول و عرض جغرافیایی پیشبینی انتخاب شده نیاز دارد؟
بله، نیاز به توضیحات بیشتر دارد
استفاده از تکمیل خودکار مبتنی بر جلسه (جدید) به همراه جزئیات مکان (جدید).
از آنجایی که برنامه شما به جزئیات مکان (جدید)، مانند نام مکان، وضعیت کسب و کار یا ساعات کاری نیاز دارد، پیادهسازی Autocomplete (جدید) شما باید از یک توکن جلسه (به صورت برنامهنویسی یا ساخته شده در ویجتهای جاوا اسکریپت ، اندروید یا iOS ) به ازای هر جلسه به علاوه SKU های مکانهای قابل اجرا، بسته به فیلدهای داده مکانی که درخواست میکنید، استفاده کند. 1
پیادهسازی ویجت
مدیریت جلسه به طور خودکار در ویجتهای جاوا اسکریپت ، اندروید یا iOS تعبیه شده است. این شامل درخواستهای تکمیل خودکار (جدید) و درخواست جزئیات مکان (جدید) در پیشبینی انتخاب شده میشود. حتماً پارامتر fields را مشخص کنید تا مطمئن شوید که فقط فیلدهای داده تکمیل خودکار (جدید) مورد نیاز خود را درخواست میکنید.
پیادهسازی برنامهریزیشده
از یک توکن جلسه ( session token) برای درخواستهای تکمیل خودکار (Autocomplete) خود استفاده کنید. هنگام درخواست جزئیات مکان (Place Details) (جدید) در مورد پیشبینی انتخاب شده، پارامترهای زیر را وارد کنید:
- شناسه مکان از پاسخ تکمیل خودکار (جدید)
- توکن جلسه مورد استفاده در درخواست تکمیل خودکار (جدید)
- پارامتر
fieldsکه فیلدهای داده تکمیل خودکار (جدید) مورد نیاز شما را مشخص میکند
خیر، فقط به آدرس و موقعیت مکانی نیاز دارد
بسته به عملکرد استفاده از Autocomplete (جدید)، API مربوط به Geocoding میتواند گزینه مقرونبهصرفهتری نسبت به Place Details (جدید) برای برنامه شما باشد. کارایی Autocomplete (جدید) هر برنامه بسته به اینکه کاربران چه اطلاعاتی را وارد میکنند، برنامه در کجا استفاده میشود و اینکه آیا بهترین شیوههای بهینهسازی عملکرد پیادهسازی شدهاند یا خیر، متفاوت است.
برای پاسخ به سوال زیر، قبل از انتخاب پیشبینی تکمیل خودکار (جدید) در برنامه خود، تجزیه و تحلیل کنید که کاربر به طور متوسط چند کاراکتر تایپ میکند.
آیا کاربران شما به طور متوسط در چهار درخواست یا کمتر، پیشبینی تکمیل خودکار (جدید) را انتخاب میکنند؟
بله
تکمیل خودکار (جدید) را به صورت برنامهنویسی شده و بدون توکنهای جلسه پیادهسازی کنید و API مربوط به Geocoding را روی پیشبینی مکان انتخاب شده فراخوانی کنید.
API ژئوکدینگ آدرسها و مختصات طول و عرض جغرافیایی را ارائه میدهد. انجام چهار درخواست تکمیل خودکار به همراه یک فراخوانی API ژئوکدینگ در مورد پیشبینی مکان انتخاب شده، کمتر از هزینه تکمیل خودکار (جدید) به ازای هر جلسه است. 1
در نظر داشته باشید که از بهترین شیوههای عملکرد استفاده کنید تا به کاربران خود کمک کنید پیشبینی مورد نظر خود را با تعداد کاراکترهای کمتری دریافت کنند.
خیر
استفاده از تکمیل خودکار مبتنی بر جلسه (جدید) به همراه جزئیات مکان (جدید).
از آنجایی که میانگین تعداد درخواستهایی که انتظار دارید قبل از انتخاب پیشبینی تکمیل خودکار (جدید) توسط کاربر انجام شود، از هزینه قیمتگذاری به ازای هر جلسه بیشتر است، پیادهسازی تکمیل خودکار (جدید) شما باید از یک توکن جلسه برای هر دو درخواست تکمیل خودکار (جدید) و درخواست مرتبط با جزئیات مکان (جدید) به ازای هر جلسه استفاده کند. 1
پیادهسازی ویجت
مدیریت جلسه به طور خودکار در ویجتهای جاوا اسکریپت ، اندروید یا iOS تعبیه شده است. این شامل درخواستهای تکمیل خودکار (جدید) و درخواست جزئیات مکان (جدید) در پیشبینی انتخاب شده میشود. حتماً پارامتر fields را مشخص کنید تا مطمئن شوید که فقط فیلدهای مورد نیاز خود را درخواست میکنید.
پیادهسازی برنامهریزیشده
از یک توکن جلسه ( session token) برای درخواستهای تکمیل خودکار (Autocomplete) خود استفاده کنید. هنگام درخواست جزئیات مکان (Place Details) (جدید) در مورد پیشبینی انتخاب شده، پارامترهای زیر را وارد کنید:
- شناسه مکان از پاسخ تکمیل خودکار (جدید)
- توکن جلسه مورد استفاده در درخواست تکمیل خودکار (جدید)
- پارامتر
fieldsکه فیلدهایی مانند آدرس و هندسه را مشخص میکند
درخواستهای تکمیل خودکار (جدید) را به تعویق بیندازید
شما میتوانید از استراتژیهایی مانند به تأخیر انداختن درخواست تکمیل خودکار (جدید) تا زمانی که کاربر سه یا چهار کاراکتر اول را تایپ کرده باشد، استفاده کنید تا برنامه شما درخواستهای کمتری ارسال کند. به عنوان مثال، ایجاد درخواستهای تکمیل خودکار (جدید) برای هر کاراکتر پس از تایپ کاراکتر سوم توسط کاربر به این معنی است که اگر کاربر هفت کاراکتر تایپ کند و سپس پیشبینیای را انتخاب کند که شما برای آن یک درخواست API Geocoding ارسال میکنید، هزینه کل برای 4 تکمیل خودکار (جدید) به ازای هر درخواست + Geocoding خواهد بود. 1
اگر تأخیر در درخواستها میتواند میانگین درخواست برنامهنویسی شما را به زیر چهار برساند، میتوانید از راهنماییهای مربوط به تکمیل خودکار (جدید) با پیادهسازی API Geocoding پیروی کنید. توجه داشته باشید که تأخیر در درخواستها میتواند توسط کاربری که انتظار دارد با هر ضربه کلید جدید، پیشبینیها را ببیند، به عنوان تأخیر تلقی شود.
استفاده از بهترین شیوههای عملکرد را در نظر بگیرید تا به کاربران خود کمک کنید پیشبینی مورد نظر خود را با تعداد کاراکترهای کمتری دریافت کنند.
برای اطلاع از هزینهها، به لیست قیمتهای پلتفرم نقشههای گوگل مراجعه کنید.
بهترین شیوههای عملکرد
دستورالعملهای زیر روشهای بهینهسازی عملکرد تکمیل خودکار (جدید) را شرح میدهند:
- محدودیتهای کشور، سوگیری موقعیت مکانی و (برای پیادهسازیهای برنامهنویسی) ترجیح زبان را به پیادهسازی تکمیل خودکار (جدید) خود اضافه کنید. ترجیح زبان با ویجتها لازم نیست زیرا آنها ترجیحات زبان را از مرورگر یا دستگاه تلفن همراه کاربر انتخاب میکنند.
- اگر تکمیل خودکار (جدید) با نقشه همراه باشد، میتوانید مکان را بر اساس نمای نقشه تغییر دهید.
- در شرایطی که کاربر یکی از پیشبینیهای تکمیل خودکار (جدید) را انتخاب نمیکند، عموماً به این دلیل که هیچکدام از این پیشبینیها آدرس-نتیجه مورد نظر نیستند، میتوانید از ورودی اصلی کاربر برای تلاش جهت دریافت نتایج مرتبطتر استفاده مجدد کنید:
- اگر انتظار دارید کاربر فقط اطلاعات آدرس را وارد کند، از ورودی اصلی کاربر در فراخوانی Geocoding API استفاده مجدد کنید.
- اگر انتظار دارید کاربر برای یک مکان خاص با نام یا آدرس جستجو کند، از درخواست «جزئیات مکان (جدید)» استفاده کنید. اگر نتایج فقط در یک منطقه خاص مورد انتظار است، از «سوگیری مکان» استفاده کنید.
- کاربرانی که آدرسهای فرعی، مانند آدرسهای واحدها یا آپارتمانهای خاص در یک ساختمان را وارد میکنند. برای مثال، آدرس چکی "Stroupežnického 3191/17, Praha" در حالت تکمیل خودکار (جدید) پیشبینی جزئی ارائه میدهد.
- کاربرانی که آدرسهایی با پیشوندهای قطعه جادهای مانند «خیابان بیست و نهم، شماره ۲۳-۳۰، کوئینز» در شهر نیویورک یا «بزرگراه کامهامها، شماره ۴۷-۳۸۰، کانئوهه» در جزیره کائوآئی در هاوایی وارد میکنند.
سوگیری مکانی
با ارسال پارامتر location و پارامتر radius ، نتایج را به یک منطقه مشخص شده متمایل میکند. این به Autocomplete (جدید) دستور میدهد که ترجیح دهد نتایج را در منطقه تعریف شده نشان دهد. نتایج خارج از منطقه تعریف شده همچنان ممکن است نمایش داده شوند. میتوانید از پارامتر components برای فیلتر کردن نتایج استفاده کنید تا فقط مکانهای داخل یک کشور مشخص شده را نشان دهد.
محدود کردن موقعیت مکانی
با ارسال پارامتر locationRestriction ، نتایج را به یک ناحیه مشخص محدود کنید.
همچنین میتوانید با اضافه کردن پارامتر locationRestriction ، نتایج را به ناحیهای که توسط location و پارامتر radius تعریف شده است، محدود کنید. این به Autocomplete (جدید) دستور میدهد که فقط نتایج درون آن ناحیه را برگرداند.
امتحانش کن!
مرورگر APIها به شما امکان میدهد درخواستهای نمونه ایجاد کنید تا با API و گزینههای API آشنا شوید.
آیکون API یعنی api را در سمت راست صفحه انتخاب کنید.
در صورت تمایل، پارامترهای درخواست را ویرایش کنید.
دکمه اجرا را انتخاب کنید. در کادر محاورهای، حسابی را که میخواهید برای ارسال درخواست استفاده کنید، انتخاب کنید.
در پنل APIs Explorer، آیکون تمام صفحه را در حالت تمام صفحه انتخاب کنید تا پنجره APIs Explorer باز شود.