سرویس تکمیل خودکار (جدید) یک سرویس وب است که پیشبینیهای مکان و پیشبینیهای پرس و جو را در پاسخ به درخواست HTTP برمیگرداند. در درخواست، یک رشته جستجوی متن و مرزهای جغرافیایی که منطقه جستجو را کنترل می کند، مشخص کنید.
سرویس تکمیل خودکار (جدید) میتواند با کلمات کامل و زیر رشتههای ورودی، نام مکانها، آدرسها و کدهای بعلاوه مطابقت داشته باشد. بنابراین، برنامهها میتوانند پرسوجوهایی را بهعنوان نوع کاربر ارسال کنند تا پیشبینیهای مربوط به مکان و پرس و جو را ارائه دهند.
پاسخ از API تکمیل خودکار (جدید) میتواند شامل دو نوع پیشبینی باشد:
- پیشبینیهای مکان : مکانها، مانند مشاغل، آدرسها و نقاط مورد علاقه، بر اساس رشته متن ورودی مشخص شده و ناحیه جستجو. پیشبینیهای مکان بهطور پیشفرض برگردانده میشوند.
- پیشبینیهای پرس و جو : رشتههای پرس و جو که با رشته متن ورودی و ناحیه جستجو مطابقت دارند. پیش بینی های پرس و جو به طور پیش فرض برگردانده نمی شوند. از پارامتر درخواست
includeQueryPredictions
برای افزودن پیشبینیهای پرس و جو به پاسخ استفاده کنید.
به عنوان مثال، شما API را با استفاده از یک رشته ورودی که شامل ورودی جزئی کاربر، "Sicilian piz" است، با ناحیه جستجو محدود به San Francisco، CA می نامید. سپس پاسخ شامل فهرستی از پیشبینیهای مکان است که با رشته جستجو و منطقه جستجو مطابقت دارد، مانند رستورانی به نام «آشپزخانه پیتزا سیسیلی»، همراه با جزئیات مربوط به مکان.
پیشبینیهای مکان بازگشتی به گونهای طراحی شدهاند که به کاربر ارائه شود تا در انتخاب مکان مورد نظر به او کمک کند. برای دریافت اطلاعات بیشتر درباره هر یک از پیشبینیهای مکان بازگشتی، میتوانید درخواست جزئیات مکان (جدید) کنید.
پاسخ همچنین میتواند حاوی فهرستی از پیشبینیهای پرس و جو باشد که با رشته جستجو و ناحیه جستجو مطابقت دارند، مانند «پیتزا و پاستا سیسیلی». هر پیش بینی پرس و جو در پاسخ شامل فیلد text
حاوی یک رشته جستجوی متن توصیه شده است. از آن رشته به عنوان ورودی برای جستجوی متن (جدید) برای انجام جستجوی دقیق تر استفاده کنید.
API Explorer به شما امکان می دهد درخواست های زنده بنویسید تا بتوانید با 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
در مورد پاسخ
تکمیل خودکار (جدید) یک شی 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 }] }, ... } ...] }
پارامترهای مورد نیاز
ورودی
رشته متنی که در آن جستجو می شود. کلمات و رشته های فرعی کامل، نام مکان ها، آدرس ها و کدهای بعلاوه را مشخص کنید. سرویس تکمیل خودکار (جدید) منطبقات نامزد را بر اساس این رشته برمی گرداند و نتایج را بر اساس ارتباط درک شده آنها سفارش می دهد.
پارامترهای اختیاری
شامل PrimaryTypes
یک مکان فقط می تواند یک نوع اصلی از انواع فهرست شده در جدول A یا جدول B داشته باشد. برای مثال، نوع اولیه ممکن است
"mexican_restaurant"
یا"steak_house"
باشد.به طور پیشفرض، API همه مکانها را بر اساس پارامتر
input
، صرفنظر از مقدار نوع اولیه مرتبط با مکان، برمیگرداند. با عبور دادن پارامترincludedPrimaryTypes
، نتایج را محدود کنید تا از نوع اولیه یا انواع اولیه خاص باشند.از این پارامتر برای تعیین حداکثر پنج مقدار نوع از جدول A یا جدول B استفاده کنید. یک مکان باید با یکی از مقادیر نوع اولیه مشخص شده مطابقت داشته باشد تا در پاسخ گنجانده شود.
این پارامتر همچنین ممکن است در عوض شامل یکی از
(regions)
یا(cities)
باشد.(regions)
فیلترهای مجموعه را برای مناطق یا بخشها، مانند محلهها و کدهای پستی، تایپ میکنند. فیلترهای مجموعه نوع(cities)
برای مکانهایی که Google آنها را به عنوان شهر شناسایی میکند.درخواست با خطای
INVALID_REQUEST
رد می شود اگر:- بیش از پنج نوع مشخص شده است.
- هر نوع علاوه بر
(cities)
یا(regions)
مشخص شده است. - انواع ناشناخته مشخص شده است.
شاملQueryPredictions
اگر
true
، پاسخ شامل پیشبینی مکان و پرس و جو میشود. مقدار پیشفرضfalse
است، به این معنی که پاسخ فقط شامل پیشبینی مکان میشود.شاملRegionCodes
فقط شامل نتایج از لیست مناطق مشخص شده است، که به صورت آرایه ای تا 15 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
شما می توانید
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
و بالا به صورت مورب در مقابل هم نمایش داده می شود. یک viewport یک منطقه بسته در نظر گرفته می شود، به این معنی که شامل مرز آن می شود. محدوده عرض جغرافیایی باید بین 90- تا 90 درجه باشد و محدوده طول جغرافیایی باید بین 180- تا 180 درجه باشد:- اگر
low
=high
، نمای از همان نقطه واحد تشکیل شده است. - اگر
low.longitude
>high.longitude
, محدوده طول معکوس می شود (نمایش از خط طول جغرافیایی 180 درجه عبور می کند). - اگر
low.longitude
= -180 درجه وhigh.longitude
= 180 درجه باشد، درگاه دید شامل تمام طولهای جغرافیایی میشود. - اگر
low.longitude
= 180 درجه وhigh.longitude
= -180 درجه باشد، محدوده طول جغرافیایی خالی است.
هم
low
و همhigh
باید پر شوند و کادر نمایش داده شده نمی تواند خالی باشد. یک نمای خالی منجر به خطا می شود.به عنوان مثال، این نما به طور کامل شهر نیویورک را در بر می گیرد:
"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" است (از لحاظ فنی برای نهاد "پادشاهی متحده بریتانیای کبیر و ایرلند شمالی").
اگر کد منطقه نامعتبر را مشخص کنید، API یک خطای
INVALID_ARGUMENT
را برمیگرداند. این پارامتر می تواند بر نتایج بر اساس قانون قابل اجرا تأثیر بگذارد.sessionToken
نشانههای جلسه رشتههایی هستند که توسط کاربر ایجاد میشوند که تماسهای تکمیل خودکار (جدید) را بهعنوان «جلسه» دنبال میکنند. تکمیل خودکار (جدید) از نشانههای جلسه برای گروهبندی مراحل جستجو و انتخاب جستجوی تکمیل خودکار کاربر در یک جلسه مجزا برای اهداف صورتحساب استفاده میکند. برای اطلاعات بیشتر، نشانههای جلسه را ببینید.
نمونه های تکمیل خودکار (جدید).
از locationRestriction و locationBias استفاده کنید
API به طور پیش فرض از بایاس IP برای کنترل منطقه جستجو استفاده می کند. با بایاس IP، API از آدرس IP دستگاه برای سوگیری نتایج استفاده می کند. میتوانید بهصورت اختیاری از locationRestriction
یا locationBias
استفاده کنید، اما نه از هر دو، برای تعیین منطقهای برای جستجو.
locationRestriction
ناحیه مورد جستجو را مشخص می کند. نتایج خارج از منطقه مشخص شده برگردانده نمی شوند. در مثال زیر، از locationRestriction
برای محدود کردن درخواست به دایره ای به شعاع 5000 متری در مرکز سانفرانسیسکو استفاده می کنید:
curl -X POST -d '{ "input": "Amoeba", "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/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", "store", "point_of_interest", "electronics_store" ] } } ] }
با 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
نتایج اکنون حاوی موارد بسیار بیشتری هستند، از جمله نتایج خارج از شعاع 5000 متر:
{ "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" ] } }, ... ] }
از includePrimaryTypes استفاده کنید
از پارامتر 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
وارد میکنید، API شامل فیلد 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 } } ] }
آن را امتحان کنید!
API Explorer به شما امکان می دهد درخواست های نمونه بنویسید تا بتوانید با API و گزینه های API آشنا شوید.
- نماد API را انتخاب کنید،
، در سمت راست صفحه.
- به صورت اختیاری نمایش پارامترهای استاندارد را گسترش دهید و پارامتر
fields
روی فیلد ماسک تنظیم کنید. - به صورت اختیاری بدنه درخواست را ویرایش کنید.
- دکمه Execute را انتخاب کنید. در پنجره پاپ آپ، حسابی را که می خواهید برای درخواست استفاده کنید، انتخاب کنید.
در پانل API Explorer، نماد گسترش را انتخاب کنید،
، برای گسترش پنجره API Explorer.