مقدمه
جستجوی نوشتار (جدید) اطلاعاتی درباره مجموعه‌ای از مکان‌ها براساس رشته‌ای (برای مثال، «پیتزا در نیویورک» یا «کفش‌فروشی‌های نزدیک اتاوا» یا «خیابان اصلی ۱۲۳») برمی‌گرداند. سرویس با فهرستی از مکان‌های منطبق با رشته نوشتاری و هرگونه سوگیری مکانی که تنظیم شده است پاسخ می‌دهد.
علاوه‌بر پارامترهای الزامی، «جستجوی نوشتار (جدید)» از پالایش پُرسمان‌ها بااستفاده از پارامترهای اختیاری برای نتایج بهتر پشتیبانی می‌کند.
APIs Explorer به شما امکان می‌دهد درخواست‌های مستقیم ارسال کنید تا بتوانید با «میانای برنامه‌سازی کاربردی» و گزینه‌های آن آشنا شوید:
درخواست‌های «جستجوی نوشتار (جدید)»
درخواست «جستجوی نوشتار (جدید)» یک درخواست HTTP POST به‌شکل زیر است:
https://places.googleapis.com/v1/places:searchText
همه پارامترها را در بدنه درخواست JSON یا در سرصفحه‌ها به‌عنوان بخشی از درخواست POST ارسال کنید. برای مثال:
curl -X POST -d '{
"textQuery" : "Spicy Vegetarian Food in Sydney, Australia"
}' \
-H 'Content-Type: application/json' -H 'X-Goog-Api-Key: API_KEY' \
-H 'X-Goog-FieldMask: places.displayName,places.formattedAddress,places.priceLevel' \
'https://places.googleapis.com/v1/places:searchText'پاسخ‌های «جستجوی نوشتار (جدید)»
«جستجوی نوشتاری (جدید)» شیء JSON را به‌عنوان پاسخ برمی‌گرداند. در پاسخ:
- آرایه
placesحاوی همه مکان‌های منطبق است. - هر مکان در آرایه با یک شیء
Placeنشان داده می‌شود. شیءPlaceحاوی اطلاعات دقیقی درباره یک مکان است. - FieldMask ارسال‌شده در درخواست، فهرست فیلدهای برگردانده‌شده در شیء
Placeرا مشخص می‌کند. - تضمینی وجود ندارد که فهرست مکان‌های برگردانده‌شده برای درخواست‌های یکسان، سازگار باشد.
شیء JSON کامل در فرم است:
{
"places": [
{
object (Place)
}
]
}پارامترهای الزامی
-
FieldMask
با ایجاد کردن ماسک فیلد پاسخ، فهرست فیلدهایی را که باید در پاسخ برگردانده شود مشخص کنید. ماسک فیلد پاسخ را بااستفاده از پارامتر نشانی وب
$fieldsیاfields، یا بااستفاده از سرصفحه HTTPX-Goog-FieldMaskبه روش ارسال کنید. هیچ فهرست پیش‌فرضی از فیلدهای برگردانده‌شده در پاسخ وجود ندارد. اگر ماسک فیلد را حذف کنید، روش خطا برمی‌گرداند.ماسک کردن فیلد روش طراحی خوبی است که تضمین می‌کند داده‌های غیرضروری درخواست نکنید، که این امر به جلوگیری از زمان پردازش غیرضروری و هزینه‌های صورت‌حساب کمک می‌کند.
فهرست جداشده با کاما از انواع داده‌های مکان را برای برگرداندن مشخص کنید. برای مثال، برای بازیابی نام نمایشی و نشانی مکان.
X-Goog-FieldMask: places.displayName,places.formattedAddress
برای بازیابی همه فیلدها، از
*استفاده کنید.X-Goog-FieldMask: *
یک یا چند فیلد زیر را مشخص کنید:
فیلدهای زیر شناسه SKU فقط شناسه Text Search Essentials را راه‌اندازی می‌کنند:
places.attributions
places.id
places.consumerAlert
places.name*
nextPageToken
places.movedPlace
places.movedPlaceId* فیلد
places.nameحاوی نام منبع مکان در این فرم است:places/PLACE_ID. ازplaces.displayNameدر Pro SKU برای دسترسی به نام نوشتاری مکان استفاده کنید.برای مشاهده فهرست کامل فیلدها و SKUهای مرتبط با آن‌ها، به فیلدهای داده مکان (جدید) مراجعه کنید.
فیلدهای زیر شناسه کالا برای جستجوی نوشتار Pro را فعال می‌کنند:
places.accessibilityOptions
places.addressComponents
places.addressDescriptor*
places.adrFormatAddress
places.businessStatus
places.containingPlaces
places.displayName
places.formattedAddress
places.googleMapsLinks
places.googleMapsTypeLabel
places.googleMapsUri
places.iconBackgroundColor
places.iconMaskBaseUri
places.location
places.openingDate
places.photos
places.plusCode
places.postalAddress
places.primaryType
places.primaryTypeDisplayName
places.pureServiceAreaBusiness
places.shortFormattedAddress
places.searchUri
places.subDestinations
places.timeZone
places.types
places.utcOffsetMinutes
places.viewport
* توصیف‌کننده‌های نشانی به‌طور کلی برای مشتریان در هند دردسترس است و در جاهای دیگر آزمایشی است.برای مشاهده فهرست کامل فیلدها و SKUهای مرتبط با آن‌ها، به فیلدهای داده مکان (جدید) مراجعه کنید.
فیلدهای زیر شناسه محصول سازمانی جستجوی نوشتار را راه‌اندازی می‌کنند:
places.currentOpeningHours
places.currentSecondaryOpeningHours
places.internationalPhoneNumber
places.nationalPhoneNumber
places.priceLevel
places.priceRange
places.rating
places.regularOpeningHours
places.regularSecondaryOpeningHours
places.transitStation
places.userRatingCount
places.websiteUriبرای مشاهده فهرست کامل فیلدها و SKUهای مرتبط با آن‌ها، به فیلدهای داده مکان (جدید) مراجعه کنید.
فیلدهای زیر Text Search Enterprise + Atmosphere SKU را راه‌اندازی می‌کنند:
places.allowsDogs
places.curbsidePickup
places.delivery
places.dineIn
places.editorialSummary
places.evChargeAmenitySummary
places.evChargeOptions
places.fuelOptions
places.generativeSummary
places.goodForChildren
places.goodForGroups
places.goodForWatchingSports
places.liveMusic
places.menuForChildren
places.neighborhoodSummary
places.parkingOptions
places.paymentOptions
places.outdoorSeating
places.reservable
places.restroom
places.reviews
places.reviewSummary
routingSummaries*
places.servesBeer
places.servesBreakfast
places.servesBrunch
places.servesCocktails
places.servesCoffee
places.servesDessert
places.servesDinner
places.servesLunch
places.servesVegetarianFood
places.servesWine
places.takeout
* فقط «جستجوی نوشتار» و «جستجوی اطراف»برای مشاهده فهرست کامل فیلدها و SKUهای مرتبط با آن‌ها، به فیلدهای داده مکان (جدید) مراجعه کنید.
-
textQuery
رشته نوشتاری که باید در آن جستجو شود. برای مثال، «رستوران»، «خیابان ولیعصر، پلاک ۱۲۳»، یا «بهترین مکان برای بازدید در تهران». API مطابقت‌های نامزد را براساس این رشته برمی‌گرداند و نتایج را براساس ارتباط درک‌شده آن‌ها مرتب می‌کند.
«جستجوی نوشتاری (جدید)» برای پرسمان‌های مبهم، ازجمله موارد زیر، درنظر گرفته نشده است:
نوع پُرسمان مثال مفاهیم یا محدودیت‌های بسیار زیاد، مانند نام چندین مکان، جاده، یا شهر در یک پُرسمان «Market Street San Francisco San Jose Airport» عناصر نشانی پستی که در Google Maps نشان داده نمی‌شود «C/O John Smith 123 Main Street»
«P.O. Box 13 San Francisco»نام کسب‌وکارها، زنجیره‌ها، یا دسته‌هایی که با مکان‌هایی ترکیب شده‌اند که این نهادها در آن‌ها دردسترس نیستند «Tesco near Dallas, Texas» (تسکو نزدیک دالاس، تگزاس) پرسمان‌های مبهم با چند تفسیر «تحویل شارژر» نام‌های قدیمی که دیگر استفاده نمی‌شوند "Middlesex United Kingdom" عناصر یا هدف غیرزمین‌مکانی «چند قایق در بندر ونتورا وجود دارد؟» نام‌های غیررسمی یا نام‌های سفارشی «برج هیجان»
«سرسره مارپیچ»مختصات طول و عرض جغرافیایی "37.422131,-122.084801"
پارامترهای اختیاری
-
includeFutureOpeningBusinesses
اگر
true، کسب‌وکارهایی را برمی‌گرداند که انتظار می‌رود در آینده باز شوند. پیش‌فرض‌ها بهfalse.
برای بازیابی وضعیت کسب‌وکار،places.businessStatusرا در ماسک فیلد درخواستتان بگنجانید. برای بازیابی تاریخ افتتاح پیش‌بینی‌شده کسب‌وکار،places.openingDateرا در ماسک فیلد درخواستتان اضافه کنید. -
includedType
نتایج را به مکان‌هایی که با نوع مشخص‌شده تعریف‌شده در جدول الف مطابقت دارند متمایل می‌کند. فقط یک نوع می‌توانید مشخص کنید. برای مثال:
"includedType":"bar""includedType":"pharmacy"
«جستجوی نوشتار (جدید)» فیلتر کردن نوع را برای برخی پرسمان‌ها، بسته به کاربرد، اعمال می‌کند. برای مثال، فیلتر کردن نوع ممکن است برای پُرسمان‌های مربوط به نشانی‌های خاص («خیابان اصلی ۱۲۳») اعمال نشود، اما فیلتر کردن نوع تقریباً همیشه برای پُرسمان‌های دسته‌ای («فروشگاه‌های اطراف» یا «مراکز خرید») اعمال می‌شود.
برای اعمال فیلتر کردن نوع به همه پُرسمان‌ها،
strictTypeFilteringرا رویtrueتنظیم کنید. -
includePureServiceAreaBusinesses
اگر روی
trueتنظیم شود، پاسخ شامل کسب‌وکارهایی می‌شود که مستقیماً به مشتریان مراجعه می‌کنند یا برای آن‌ها کالا ارسال می‌کنند، ولی مکان فیزیکی کسب‌وکار ندارند. اگر رویfalseتنظیم شود، میانای برنامه‌سازی کاربردی فقط کسب‌وکارهایی را برمی‌گرداند که مکان فیزیکی کسب‌وکار دارند. languageCode
زبانی که نتایج به آن برگردانده می‌شود.
- فهرست زبان‌های پشتیبانی‌شده را ببینید. Google اغلب زبان‌های پشتیبانی‌شده را به‌روز می‌کند، بنابراین این فهرست ممکن است جامع نباشد.
-
اگر
languageCodeارائه نشده باشد، میانای برنامه‌سازی کاربردی به‌طور پیش‌فرض ازenاستفاده می‌کند. اگر کد زبان نامعتبری را مشخص کنید، API خطایINVALID_ARGUMENTرا برمی‌گرداند. - این API تمام تلاش خود را می‌کند تا نشانی خیابانی ارائه دهد که هم برای کاربر و هم برای افراد محلی قابل‌خواندن باشد. برای دستیابی به این هدف، نشانی‌های خیابان را به زبان محلی برمی‌گرداند و درصورت لزوم، با رعایت زبان ترجیحی، آن‌ها را به نویسه‌ای که برای کاربر خوانا باشد نویسه‌گردانی می‌کند. همه نشانی‌های دیگر به زبان ترجیحی برگردانده می‌شوند. همه مؤلفه‌های نشانی به همان زبانی برگردانده می‌شوند که از مؤلفه اول انتخاب شده است.
- اگر نامی به زبان ترجیحی دردسترس نباشد، API از نزدیک‌ترین مطابقت استفاده می‌کند.
- زبان ترجیحی تأثیر کمی بر مجموعه نتایجی دارد که میانای برنامه‌سازی کاربردی برای برگرداندن انتخاب می‌کند و ترتیبی که در آن برگردانده می‌شوند. زمین‌کدیاب اختصارات را بسته به زبان به‌طور متفاوتی تفسیر می‌کند، مانند اختصارات برای انواع خیابان‌ها، یا مترادف‌هایی که ممکن است در یک زبان معتبر باشند اما در زبان دیگر معتبر نباشند.
locationBias
منطقه‌ای را برای جستجو مشخص می‌کند. این مکان به‌عنوان سوگیری عمل می‌کند، یعنی نتایج اطراف مکان مشخص‌شده می‌تواند برگردانده شود، ازجمله نتایج خارج از منطقه مشخص‌شده.
می‌توانید
locationRestrictionیاlocationBiasرا مشخص کنید، اما نه هر دو را.locationRestrictionرا به‌عنوان مشخص‌کننده منطقه‌ای درنظر بگیرید که نتایج باید در آن باشد وlocationBiasرا به‌عنوان مشخص‌کننده منطقه‌ای درنظر بگیرید که نتایج احتمالاً در آن یا نزدیک آن خواهد بود اما می‌تواند خارج از آن منطقه هم باشد.منطقه را به‌عنوان نمای مستطیلی یا دایره مشخص کنید.
دایره با نقطه مرکزی و شعاع به متر تعریف می‌شود. شعاع باید بین ۰٫۰ و ۵۰۰۰۰٫۰ باشد. شعاع پیش‌فرض ۰٫۰ است. برای مثال:
"locationBias": { "circle": { "center": { "latitude": 37.7937, "longitude": -122.3965 }, "radius": 500.0 } }
مستطیل یک نمای طول و عرض جغرافیایی است که به‌صورت دو نقطه پایین و بالای مقابل هم به‌صورت مورب نشان داده می‌شود. نقطه پایین نشان‌دهنده گوشه جنوب غربی مستطیل است و نقطه بالا نشان‌دهنده گوشه شمال شرقی مستطیل است.
ناحیه نمایش به‌عنوان یک منطقه بسته درنظر گرفته می‌شود، یعنی مرزهای آن را شامل می‌شود. محدوده عرض جغرافیایی باید بین ۹۰- و ۹۰ درجه باشد و محدوده طول جغرافیایی باید بین ۱۸۰- و ۱۸۰ درجه باشد:
- اگر
low=high، ناحیه نمایش از آن نقطه تکی تشکیل می‌شود. - اگر
low.longitude>high.longitude، محدوده طول جغرافیایی معکوس می‌شود (نمای جغرافیایی از خط طول جغرافیایی ۱۸۰ درجه عبور می‌کند). - اگر
low.longitude= ۱۸۰- درجه وhigh.longitude= ۱۸۰ درجه باشد، نمای دید شامل همه طول‌های جغرافیایی می‌شود. - اگر
low.longitude= ۱۸۰ درجه وhigh.longitude= ۱۸۰- درجه باشد، محدوده طول جغرافیایی خالی است. - اگر
low.latitude>high.latitude، محدوده عرض جغرافیایی خالی است.
هر دو مقدار کم و زیاد باید پر شوند و چارگوش نشان‌داده‌شده نمی‌تواند خالی باشد. نمای خالی منجر به خطا می‌شود.
برای مثال، این ناحیه نمایش کاملاً شهر نیویورک را دربرمی‌گیرد:
"locationBias": { "rectangle": { "low": { "latitude": 40.477398, "longitude": -74.259087 }, "high": { "latitude": 40.91618, "longitude": -73.70018 } } }
- اگر
locationRestriction
منطقه‌ای را برای جستجوی فقط پرسمان‌های دسته‌بندی‌شده مشخص می‌کند که می‌تواند چندین مکان را برگرداند (برای مثال، «رستوران‌ها در نیویورک» یا «مراکز خرید»). نتایج خارج از منطقه مشخص‌شده برگردانده نمی‌شود.
منطقه را به‌صورت نمای مستطیلی مشخص کنید. برای دیدن نمونه‌ای از تعریف «ناحیه نمایش»، شرح
locationBiasرا ببینید.می‌توانید
locationRestrictionیاlocationBiasرا مشخص کنید، اما نه هر دو را.locationRestrictionرا به‌عنوان مشخص‌کننده منطقه‌ای درنظر بگیرید که نتایج باید در آن باشد وlocationBiasرا به‌عنوان مشخص‌کننده منطقه‌ای درنظر بگیرید که نتایج احتمالاً در آن یا نزدیک آن خواهد بود اما می‌تواند خارج از آن منطقه هم باشد.evOptions
پارامترهای شناسایی رابط‌های شارژ خودرو برقی (EV) و نرخ‌های شارژ را مشخص می‌کند.
connectorTypes
براساس نوع رابط شارژ خودرو برقی موجود در مکان فیلتر می‌کند. مکان‌هایی که از هیچ‌کدام از انواع رابط پشتیبانی نمی‌کنند فیلتر می‌شوند. انواع رابط‌های شارژ خودرو برقی پشتیبانی‌شده شامل شارژرهای ترکیبی (AC و DC)، شارژرهای Tesla، شارژرهای سازگار با GB/T (برای شارژ سریع خودرو برقی در چین)، و شارژرهای پریز دیواری می‌شود. برای اطلاعات بیشتر، به اسناد مرجع مراجعه کنید.
- برای فیلتر کردن نتایج برای رابط پشتیبانی‌شده خاص،
connectorTypesرا روی آن مقدار تنظیم کنید. برای مثال، برای پیدا کردن رابط‌های J1772 نوع ۱،connectorTypesرا رویEV_CONNECTOR_TYPE_J1772تنظیم کنید. - برای فیلتر کردن نتایج برای رابط‌های پشتیبانی‌نشده،
connectorTypesرا رویEV_CONNECTOR_TYPE_OTHERتنظیم کنید. - برای فیلتر کردن نتایج برای هر نوع رابطی که پریز دیواری است،
connectorTypesرا رویEV_CONNECTOR_TYPE_UNSPECIFIED_WALL_OUTLETتنظیم کنید. - برای فیلتر کردن نتایج برای هر نوع اتصال‌دهنده،
connectorTypesرا رویEV_CONNECTOR_TYPE_UNSPECIFIEDتنظیم کنید یا مقداری برایconnectorTypesتنظیم نکنید.
- برای فیلتر کردن نتایج برای رابط پشتیبانی‌شده خاص،
minimumChargingRateKw
مکان‌ها را براساس حداقل نرخ شارژ خودرو برقی به کیلووات (kW) فیلتر می‌کند. هر مکانی که نرخ شارژ آن کمتر از حداقل نرخ شارژ باشد فیلتر می‌شود. برای مثال، برای پیدا کردن شارژرهای خودرو برقی با نرخ شارژ حداقل ۱۰ کیلووات، می‌توانید این پارامتر را روی «۱۰» تنظیم کنید.
minRating
نتایج را فقط به مواردی محدود می‌کند که میانگین رده‌بندی کاربر آن‌ها بزرگ‌تر یا مساوی این حد باشد. مقادیر باید بین ۰٫۰ و ۵٫۰ (شامل این دو عدد) با افزایش ۰٫۵ باشد. برای مثال: 0، 0.5، 1.0، ... ، 5.0 شامل می‌شود. مقادیر به نزدیک‌ترین ۰٫۵ گرد می‌شوند. برای مثال، مقدار ۰٫۶ همه نتایج با رده‌بندی کمتر از ۱٫۰ را حذف می‌کند.
openNow
اگر
true، فقط مکان‌هایی را برگردانید که برای کسب‌وکار باز هستند در زمانی که پُرسمان ارسال می‌شود. اگرfalse، همه کسب‌وکارها را صرف‌نظر از وضعیت باز بودن برگردانید. اگر این پارامتر را رویfalseتنظیم کنید، مکان‌هایی که ساعات کاری آن‌ها در پایگاه داده Google Places مشخص نشده است برگردانده می‌شوند.pageSize
تعداد نتایج را برای نمایش در هر صفحه مشخص می‌کند (بین ۱ تا ۲۰). برای مثال، تنظیم مقدار
pageSizeروی ۵، حداکثر ۵ نتیجه را در صفحه اول برمی‌گرداند. اگر پرسمان بتواند نتایج بیشتری برگرداند، پاسخ شاملnextPageTokenاست که می‌توانید آن را در درخواست بعدی برای دسترسی به صفحه بعدی ارسال کنید.این فیلد جایگزین فیلد منسوخ‌شده
maxResultCountمی‌شود. اگر همpageSizeو همmaxResultCountرا مشخص کنید، API ازpageSizeاستفاده می‌کند وmaxResultCountرا نادیده می‌گیرد.pageToken
nextPageTokenرا از بدنه پاسخ صفحه قبلی مشخص می‌کند.-
priceLevels
جستجو را به مکان‌هایی محدود کنید که با سطوح قیمت خاصی علامت‌گذاری شده‌اند. به‌طور پیش‌فرض، همه سطوح قیمت انتخاب شده است.
سطوح قیمت را می‌توان برای مکان‌هایی از انواع زیر انتظار داشت:
اگر
priceLevelsمشخص شده باشد، مکان‌های انواع پشتیبانی‌نشده در پاسخ گنجانده نخواهد شد.آرایه‌ای از یک یا چند مقدار تعریف‌شده توسط
PriceLevelرا مشخص می‌کند.برای مثال:
"priceLevels":["PRICE_LEVEL_INEXPENSIVE", "PRICE_LEVEL_MODERATE"]
rankPreference
مشخص می‌کند که نتایج در پاسخ براساس نوع پُرسمان چگونه رتبه‌بندی می‌شوند:
- برای پُرسمان دسته‌ای مثل «رستوران‌های تهران»،
RELEVANCE(رتبه‌بندی نتایج براساس ارتباط جستجو) پیش‌فرض است. می‌توانیدrankPreferenceرا رویRELEVANCEیاDISTANCE(رتبه‌بندی نتایج براساس فاصله) تنظیم کنید. - برای پُرسمان غیردسته‌بندی‌شده‌ای مثل «Mountain View, CA»، توصیه می‌کنیم
rankPreferenceرا تنظیم‌نشده رها کنید.
- برای پُرسمان دسته‌ای مثل «رستوران‌های تهران»،
regionCode
کد منطقه استفاده‌شده برای قالب‌بندی پاسخ، که به‌عنوان مقدار کد CLDR دو نویسه‌ای مشخص شده است. این پارامتر همچنین می‌تواند تأثیر سوگیرانه‌ای بر نتایج جستجو داشته باشد. مقدار پیش‌فرضی وجود ندارد.
اگر نام کشور فیلد
formattedAddressدر پاسخ باregionCodeمطابقت داشته باشد، کد کشور ازformattedAddressحذف می‌شود. این پارامتر تأثیری برadrFormatAddress(که همیشه نام کشور را درصورت دردسترس بودن دربرمی‌گیرد) یاshortFormattedAddress(که هرگز آن را دربرنمی‌گیرد) ندارد.اکثر کدهای CLDR با کدهای ISO 3166-1 یکسان هستند، با چند استثنای قابل‌توجه. برای مثال، ccTLD پادشاهی متحد «uk» (co.uk.) است درحالی‌که کد ISO 3166-1 آن «gb» است (ازنظر فنی برای نهاد «پادشاهی متحد بریتانیای کبیر و ایرلند شمالی»). این پارامتر می‌تواند بر نتایج براساس قانون ذی‌ربط تأثیر بگذارد.
strictTypeFiltering
با پارامتر
includedTypeاستفاده می‌شود. وقتی رویtrueتنظیم شود، فقط مکان‌هایی که با انواع مشخص‌شده توسطincludedTypeمطابقت داشته باشند برگردانده می‌شوند. وقتی مقدار false (نادرست) باشد، که مقدار پیش‌فرض است، پاسخ می‌تواند حاوی مکان‌هایی باشد که با انواع مشخص‌شده مطابقت ندارند.
نمونه‌های «جستجوی نوشتار (جدید)»
پیدا کردن مکان با رشته پُرسمان
مثال زیر درخواست «جستجوی نوشتار (جدید)» را برای «غذای گیاهی تند در سیدنی، استرالیا» نشان می‌دهد:
curl -X POST -d '{
"textQuery" : "Spicy Vegetarian Food in Sydney, Australia"
}' \
-H 'Content-Type: application/json' -H 'X-Goog-Api-Key: API_KEY' \
-H 'X-Goog-FieldMask: places.displayName,places.formattedAddress' \
'https://places.googleapis.com/v1/places:searchText'
توجه داشته باشید که سرصفحه X-Goog-FieldMask مشخص می‌کند که
پاسخ
حاوی فیلدهای داده زیر است: places.displayName,places.formattedAddress.
سپس پاسخ به‌صورت زیر خواهد بود:
{ "places": [ { "formattedAddress": "367 Pitt St, Sydney NSW 2000, Australia", "displayName": { "text": "Mother Chu's Vegetarian Kitchen", "languageCode": "en" } }, { "formattedAddress": "175 First Ave, Five Dock NSW 2046, Australia", "displayName": { "text": "Veggo Sizzle - Vegan & Vegetarian Restaurant, Five Dock, Sydney", "languageCode": "en" } }, ... ] }
برای برگرداندن اطلاعات بیشتر، انواع داده بیشتری به ماسک فیلد اضافه کنید.
برای مثال، places.types,places.websiteUri را اضافه کنید تا نوع رستوران و نشانی وب در پاسخ گنجانده شود:
curl -X POST -d '{
"textQuery" : "Spicy Vegetarian Food in Sydney, Australia"
}' \
-H 'Content-Type: application/json' -H 'X-Goog-Api-Key: API_KEY' \
-H 'X-Goog-FieldMask: places.displayName,places.formattedAddress,places.types,places.websiteUri' \
'https://places.googleapis.com/v1/places:searchText'پاسخ اکنون در فرم است:
{ "places": [ { "types": [ "vegetarian_restaurant", "vegan_restaurant", "chinese_restaurant", "restaurant", "food", "point_of_interest", "establishment" ], "formattedAddress": "367 Pitt St, Sydney NSW 2000, Australia", "websiteUri": "http://www.motherchusvegetarian.com.au/", "displayName": { "text": "Mother Chu's Vegetarian Kitchen", "languageCode": "en" } }, { "types": [ "vegan_restaurant", "thai_restaurant", "vegetarian_restaurant", "indian_restaurant", "italian_restaurant", "american_restaurant", "restaurant", "food", "point_of_interest", "establishment" ], "formattedAddress": "175 First Ave, Five Dock NSW 2046, Australia", "websiteUri": "http://www.veggosizzle.com.au/", "displayName": { "text": "Veggo Sizzle - Vegan & Vegetarian Restaurant, Five Dock, Sydney", "languageCode": "en" } }, ... ] }
فیلتر کردن مکان‌ها براساس سطح قیمت
از گزینه priceLevel برای فیلتر کردن نتایج به رستوران‌هایی که
ارزان یا نسبتاً گران تعریف شده‌اند استفاده کنید:
curl -X POST -d '{
"textQuery" : "Spicy Vegetarian Food in Sydney, Australia",
"priceLevels":["PRICE_LEVEL_INEXPENSIVE", "PRICE_LEVEL_MODERATE"]
}' \
-H 'Content-Type: application/json' -H 'X-Goog-Api-Key: API_KEY' \
-H 'X-Goog-FieldMask: places.displayName,places.formattedAddress,places.priceLevel' \
'https://places.googleapis.com/v1/places:searchText'این مثال همچنین از سرصفحه X-Goog-FieldMask برای افزودن فیلد داده places.priceLevel به پاسخ استفاده می‌کند، بنابراین به این شکل است:
{ "places": [ { "formattedAddress": "367 Pitt St, Sydney NSW 2000, Australia", "priceLevel": "PRICE_LEVEL_MODERATE", "displayName": { "text": "Mother Chu's Vegetarian Kitchen", "languageCode": "en" } }, { "formattedAddress": "115 King St, Newtown NSW 2042, Australia", "priceLevel": "PRICE_LEVEL_MODERATE", "displayName": { "text": "Green Mushroom", "languageCode": "en" } }, ... ] }
گزینه‌های بیشتری برای پالایش جستجو اضافه کنید، مثل includedType،
minRating، rankPreference، openNow،
و پارامترهای دیگری که در
پارامترهای اختیاری شرح داده شده است.
محدود کردن جستجو به منطقه‌ای مشخص
برای محدود کردن جستجو به یک منطقه، از locationRestriction یا locationBias استفاده کنید،
اما نه از هر دو. locationRestriction
را به‌عنوان مشخص‌کننده منطقه‌ای درنظر بگیرید که نتایج باید در آن باشد، و locationBias
را به‌عنوان مشخص‌کننده منطقه‌ای درنظر بگیرید که نتایج باید نزدیک آن باشد اما می‌تواند خارج از
آن منطقه باشد.
محدود کردن منطقه بااستفاده از locationRestriction
از پارامتر locationRestriction برای محدود کردن نتایج پُرسمان به منطقه‌ای خاص استفاده کنید. در بدنه درخواست، مقادیر عرض و طول جغرافیایی low و high را که مرز منطقه را تعریف می‌کنند مشخص کنید.
مثال زیر درخواست «جستجوی نوشتار (جدید)» را برای «غذای گیاهی» در شهر نیویورک نشان می‌دهد. این درخواست فقط ۱۰ نتیجه اول را برای مکان‌هایی که باز هستند برمی‌گرداند.
curl -X POST -d '{
"textQuery" : "vegetarian food",
"pageSize" : "10",
"locationRestriction": {
"rectangle": {
"low": {
"latitude": 40.477398,
"longitude": -74.259087
},
"high": {
"latitude": 40.91618,
"longitude": -73.70018
}
}
}
}' \
-H 'Content-Type: application/json' \
-H 'X-Goog-Api-Key: API_KEY' \
-H 'X-Goog-FieldMask: places.id,places.formattedAddress' \
'https://places.googleapis.com/v1/places:searchText'
سوگیری به یک منطقه بااستفاده از locationBias
مثال زیر درخواست «جستجوی نوشتار (جدید)» را برای «غذای گیاهی» نشان می‌دهد که به مکانی در فاصله ۵۰۰ متری از نقطه‌ای در مرکز شهر سانفرانسیسکو متمایل شده است. این درخواست فقط ۱۰ نتیجه اول را برای مکان‌هایی که باز هستند برمی‌گرداند.
curl -X POST -d '{
"textQuery" : "vegetarian food",
"openNow": true,
"pageSize": 10,
"locationBias": {
"circle": {
"center": {"latitude": 37.7937, "longitude": -122.3965},
"radius": 500.0
}
},
}' \
-H 'Content-Type: application/json' -H 'X-Goog-Api-Key: API_KEY' \
-H 'X-Goog-FieldMask: places.displayName,places.formattedAddress' \
'https://places.googleapis.com/v1/places:searchText'
جستجوی شارژرهای خودرو برقی با حداقل نرخ شارژ
از minimumChargingRateKw و connectorTypes برای جستجوی مکان‌هایی استفاده کنید که شارژرهای دردسترس و سازگار با خودروِ برقی شما دارند.
مثال زیر درخواستی را برای رابط‌های شارژ خودرو برقی از نوع Tesla و J1772 نوع ۱ با حداقل نرخ شارژ ۱۰ کیلووات در Mountain View، کالیفرنیا نشان می‌دهد. فقط چهار نتیجه برگردانده می‌شود.
curl -X POST -d '{
"textQuery": "EV Charging Station Mountain View",
"pageSize": 4,
"evOptions": {
"minimumChargingRateKw": 10,
"connectorTypes": ["EV_CONNECTOR_TYPE_J1772","EV_CONNECTOR_TYPE_TESLA"]
}
}' \
-H 'Content-Type: application/json' -H 'X-Goog-Api-Key: API_KEY' \
-H "X-Goog-FieldMask: places.displayName,places.evChargeOptions" \
'https://places.googleapis.com/v1/places:searchText'
درخواست پاسخ زیر را برمی‌گرداند:
{ "places": [ { "displayName": { "text": "EVgo Charging Station", "languageCode": "en" }, "evChargeOptions": { "connectorCount": 16, "connectorAggregation": [ { "type": "EV_CONNECTOR_TYPE_CHADEMO", "maxChargeRateKw": 100, "count": 8, "availableCount": 5, "outOfServiceCount": 0, "availabilityLastUpdateTime": "2024-01-10T19:10:00Z" }, { "type": "EV_CONNECTOR_TYPE_CCS_COMBO_1", "maxChargeRateKw": 100, "count": 2, "availableCount": 2, "outOfServiceCount": 0, "availabilityLastUpdateTime": "2024-01-10T19:10:00Z" }, ... ] } }, { "displayName": { "text": "EVgo Charging Station", "languageCode": "en" }, "evChargeOptions": { "connectorCount": 6, "connectorAggregation": [ { "type": "EV_CONNECTOR_TYPE_CCS_COMBO_1", "maxChargeRateKw": 100, "count": 4, "availableCount": 3, "outOfServiceCount": 0, "availabilityLastUpdateTime": "2024-01-10T19:10:00Z" }, { "type": "EV_CONNECTOR_TYPE_CCS_COMBO_1", "maxChargeRateKw": 350, "count": 2, "availableCount": 0, "outOfServiceCount": 2, "availabilityLastUpdateTime": "2024-01-10T19:10:00Z" } ] } }, ... ] }
جستجوی کسب‌وکارهای با منطقه خدماتی
از پارامتر includePureServiceAreaBusinesses برای جستجوی کسب‌وکارهای بدون نشانی خدمات فیزیکی (برای مثال، سرویس نظافت سیار یا کامیون غذا) استفاده کنید.
مثال زیر درخواستی برای لوله‌کش در سانفرانسیسکو را نشان می‌دهد:
curl -X POST -d '{
"textQuery" : "plumber San Francisco",
"includePureServiceAreaBusinesses": true
}' \
-H 'Content-Type: application/json' -H 'X-Goog-Api-Key: API_KEY' \
-H 'X-Goog-FieldMask: places.displayName,places.formattedAddress' \
'https://places.googleapis.com/v1/places:searchText'
در پاسخ، کسب‌وکارهای بدون نشانی خدمات فیزیکی فیلد formattedAddress را ندارند:
{ "places": [ { "formattedAddress": "3450 Sacramento St #204, San Francisco, CA 94118, USA", "displayName": { "text": "Advanced Plumbing & Drain", "languageCode": "en" } }, { "displayName": { "text": "Starboy Plumbing Inc.", "languageCode": "en" } }, ... ] }
تعداد نتایج را برای برگرداندن در هر صفحه مشخص کنید
از پارامتر pageSize برای مشخص کردن تعداد نتایج برای
برگرداندن در هر صفحه استفاده کنید. پارامتر nextPageToken در متن پاسخ، نشانهای ارائه می‌دهد که می‌توان از آن در تماس‌های بعدی برای دسترسی به صفحه بعدی نتایج استفاده کرد.
مثال زیر درخواستی را برای «پیتزا در نیویورک» نشان می‌دهد که به ۵ نتیجه در هر صفحه محدود شده است:
curl -X POST -d '{
"textQuery": "pizza in New York",
"pageSize": 5
}' \
-H 'Content-Type: application/json' -H 'X-Goog-Api-Key: API_KEY' \
-H "X-Goog-FieldMask: places.id,nextPageToken" \
'https://places.googleapis.com/v1/places:searchText'
{ "places": [ { "id": "ChIJifIePKtZwokRVZ-UdRGkZzs" }, { "id": "ChIJPxPd_P1YwokRfzLhSiACEoU" }, ... ], "nextPageToken": "AeCrKXsZWzNVbPzO-MRWPu52jWO_Xx8aKwOQ69_Je3DxRpfdjClq8Ekwh3UcF2h2Jn75kL6PtWLGV4ecQri-GEUKN_OFpJkdVc-JL4Q" }
برای دسترسی به صفحه بعدی نتایج، از pageToken برای ارسال
nextPageToken در بدنه درخواست استفاده کنید:
curl -X POST -d '{
"textQuery": "pizza in New York",
"pageSize": 5,
"pageToken": "AeCrKXsZWzNVbPzO-MRWPu52jWO_Xx8aKwOQ69_Je3DxRpfdjClq8Ekwh3UcF2h2Jn75kL6PtWLGV4ecQri-GEUKN_OFpJkdVc-JL4Q"
}' \
-H 'Content-Type: application/json' -H 'X-Goog-Api-Key: API_KEY' \
-H "X-Goog-FieldMask: places.id,nextPageToken" \
'https://places.googleapis.com/v1/places:searchText'
{ "places": [ { "id": "ChIJL-LN1N1ZwokR8K2jACu6Ydw" }, { "id": "ChIJjaD94kFZwokR-20CXqlpy_4" }, ... ], "nextPageToken": "AeCrKXvPd6uUy-oj96W2OaqEe2pUD8QTxOM8-sKfUcFsC9t2Wey5qivrKGoGSxcZnyc7RPmaFfAktslrKbUh31ZDTkL0upRmaxA7c_c" }
دریافت توصیف‌کننده‌های نشانی
توصیف‌کننده‌های نشانی اطلاعاتی نسبی درباره مکان ارائه می‌دهند، ازجمله نشانگرهای مکانی اطراف و مناطق دربرگیرنده.
مثال زیر درخواست «جستجوی نوشتار (جدید)» را برای مکان‌های نزدیک یک
مرکز خرید در سن خوزه نشان می‌دهد. در این مثال، addressDescriptors را در ماسک فیلد
قرار می‌دهید:
curl -X POST -d '{
"textQuery": "clothes",
"maxResultCount": 5,
"locationBias": {
"circle": {
"center": {
"latitude": 37.321328,
"longitude": -121.946275
}
}
},
"rankPreference":"RANK_PREFERENCE_UNSPECIFIED"
}' \
-H 'Content-Type: application/json' \
-H "X-Goog-Api-Key: API_KEY" \
-H "X-Goog-FieldMask: places.displayName,places.addressDescriptor" \
https://places.googleapis.com/v1/places:searchText
پاسخ شامل مکان مشخص‌شده در درخواست، فهرستی از نقاط دیدنی اطراف و فاصله آن‌ها از مکان، و فهرستی از مناطق و رابطه دربرگیری آن‌ها با مکان است:
{ "places": [ { "displayName": { "text": "Urban Outfitters", "languageCode": "en" }, "addressDescriptor": { "landmarks": [ { "name": "places/ChIJVVVVUB7Lj4ARXyb4HFVDV8s", "placeId": "ChIJVVVVUB7Lj4ARXyb4HFVDV8s", "displayName": { "text": "Westfield Valley Fair", "languageCode": "en" }, "types": [ "clothing_store", "department_store", "establishment", "food", "movie_theater", "point_of_interest", "restaurant", "shoe_store", "shopping_mall", "store" ], "spatialRelationship": "WITHIN", "straightLineDistanceMeters": 133.72855 }, { "name": "places/ChIJ62_oCR7Lj4AR_MGWkSPotD4", "placeId": "ChIJ62_oCR7Lj4AR_MGWkSPotD4", "displayName": { "text": "Nordstrom", "languageCode": "en" }, "types": [ "clothing_store", "department_store", "establishment", "point_of_interest", "shoe_store", "store" ], "straightLineDistanceMeters": 250.99161 }, ... ], "areas": [ { "name": "places/ChIJb3F-EB7Lj4ARnHApQ_Hu1gI", "placeId": "ChIJb3F-EB7Lj4ARnHApQ_Hu1gI", "displayName": { "text": "Westfield Valley Fair", "languageCode": "en" }, "containment": "WITHIN" }, { "name": "places/ChIJXYuykB_Lj4AR1Ot8nU5q26Q", "placeId": "ChIJXYuykB_Lj4AR1Ot8nU5q26Q", "displayName": { "text": "Valley Fair", "languageCode": "en" }, "containment": "WITHIN" }, ... ] } }, ... ] }
پیدا کردن کسب‌وکارهایی که در آینده باز می‌شوند
مثال زیر درخواست «جستجوی نوشتار (جدید)» را برای کسب‌وکارهایی نشان می‌دهد که در آینده در نیو مدوز، آیداهو افتتاح می‌شوند:
curl -X POST \
-H "Content-Type: application/json" \
-H "X-Goog-Api-Key: API_KEY" \
-H "X-Goog-FieldMask: places.id,places.displayName,places.businessStatus,places.openingDate" \
-d '{
"textQuery": "Roberts Greenhouse and Tree Farm",
"includeFutureOpeningBusinesses": true,
"maxResultCount": 20,
"locationBias": {
"circle": {
"center": {"latitude": 44.9755100, "longitude": -116.2842180},
"radius": 20
}
}
}' \
"https://places.googleapis.com/v1/places:searchText"
پاسخ شامل کسب‌وکارهایی است که در آینده باز خواهند شد، به‌همراه وضعیت کسب‌وکار و تاریخ افتتاح پیش‌بینی‌شده آن‌ها:
{ "places": [ { "id": "ChIJp1-VoKWJplQRMz8g-7Wa3Do", "businessStatus": "FUTURE_OPENING", "displayName": { "text": "Roberts Greenhouse and Tree Farm", "languageCode": "en" }, "openingDate": { "year": 2026, "month": 4, "day": 15 } } ] }
دریافت اطلاعات ایستگاه حمل‌ونقل عمومی
می‌توانید از «جستجوی نوشتار (جدید)» برای پیدا کردن ایستگاه‌های حمل‌ونقل عمومی استفاده کنید. بدنه پاسخ شامل اطلاعاتی درباره ایستگاه است، ازجمله نام ایستگاه، سازمان‌های حمل‌ونقل عمومی وابسته، و خطوط حمل‌ونقل عمومی که به ایستگاه خدمات ارائه می‌دهند. علاوه‌براین، پاسخ شامل نماد خودرو و رنگ‌هایی است که می‌توانید برای نمایش اطلاعات ایستگاه حمل‌ونقل عمومی استفاده کنید.
مثال زیر درخواستی را برای «Grand Central Station» نشان می‌دهد:
curl -X POST \
-H "Content-Type: application/json" \
-H "X-Goog-Api-Key: API_KEY" \
-H "X-Goog-FieldMask: places.id,places.displayName,places.transitStation" \
-d '{
"textQuery": "Grand Central Station"
}' \
"https://places.googleapis.com/v1/places:searchText"
بدنه پاسخ شامل اطلاعاتی درباره هر ایستگاه در آن شعاع، خطوطی که ایستگاه به آن‌ها خدمات می‌دهد، هشدارهای صادرشده توسط دفاتر حمل‌ونقل عمومی در آن ایستگاه، و اطلاعات حرکت است:
{ "places": [ { "id": "ChIJhRwB-yFawokRi0AhGH87UTc", "displayName": { "text": "Grand Central", "languageCode": "en" }, "transitStation": { "displayName": { "text": "Grand Central", "languageCode": "en" }, "agencies": [ { "displayName": { "text": "Metro-North Railroad", "languageCode": "en" }, "url": "http://www.mta.info/mnr", "lines": [ { "id": "ChIJOXpD29y2wokRryDO0CocwK0", "vehicleType": "HEAVY_RAIL", "displayName": { "text": "Harlem", "languageCode": "en" }, "textColor": "#FFFFFF", "backgroundColor": "#0061AA", "vehicleIcon": { "url": "https://maps.gstatic.com/mapfiles/transit/iw2/svg/rail2.svg" }, "alerts": [ { "effect": "OTHER", "texts": [ { "headline": { "text": "Information", "languageCode": "en" }, "summary": { "text": "Temporary platforms are in place at Botanical Garden, Williams Bridge, and Woodlawn for northbound travel. Build in extra travel time to reach the platform.", "languageCode": "en" }, "fullDescription": { "text": "What's Happening? We are renovating some Harlem Line stations in the Bronx. Learn more about the project here.", "languageCode": "en" } } ], "detailsUrls": [ { "url": "https://new.mta.info/" } ], "cause": "OTHER_CAUSE", "startTime": "2026-04-16T04:00:00Z", "endTime": "2026-12-01T04:45:00Z", "attribution": { "link": { "text": "new.mta.info", "url": "https://new.mta.info/" } }, "createTime": "2026-05-15T22:39:30Z", "severityLevel": "INFO" } ] }, ... ] }, ... ] "stops": [ { "id": "ChIJOfdrigFZwokRJPllLwfPrJY", "location": { "latitude": 40.752823, "longitude": -73.977195999999992 }, "wheelchairAccessibleEntrance": true } ], "departureBoards": [ { "displayType": "TIME_CENTRIC", "rows": [ { "departures": [ { "timedDeparture": { "scheduledTime": "2026-05-15T22:42:00Z", "timingType": "SCHEDULED", "predictedTime": "2026-05-15T22:42:00Z", "updateTime": "2026-05-15T22:38:50Z" }, "originallyScheduledStopId": "ChIJOfdrigFZwokRJPllLwfPrJY", "lineId": "ChIJAfBuQhwg6IkRYnFpClHxFrM" } ] }, ... ] } ] } }, { "id": "ChIJ_4EAi-pZwokRWe5T1JmmWmc", "displayName": { "text": "Grand Central Station", "languageCode": "en" } } ] }
دریافت ورودی‌ها و نقاط ناوبری
می‌توانید ورودی‌ها و نقاط پیمایش را برای مقصد درخواست کنید. ورودی‌ها نقاط ورود و خروج مکان را مشخص می‌کنند (برای مثال، دروازه‌های مختلف در فرودگاه یا مرکز خرید). نقاط ناوبری مکان‌های کنار جاده را که ناوبری باید در آنجا پایان یابد تعریف می‌کنند، که برای هدایت کاربران به سمت درست جاده یا نقطه پیاده کردن خاصی مفید است.
نقاط ناوبری navigationPointToken را برمی‌گرداند. می‌توانید این توکن را به «کیت توسعه نرم‌افزار پیمایش» (موجود برای Android یا iOS) یا میانای برنامه‌سازی کاربردی Routes ارسال کنید تا رانندگان را به آن مکان خاص هدایت کنید. برای اطلاعات بیشتر، نشانهای نقطه ناوبری را ببینید.
مثال زیر درخواست «جستجوی نوشتار (جدید)» را برای «فرودگاه بین‌المللی سانفرانسیسکو» نشان می‌دهد که شامل entrances و navigationPoints در ماسک فیلد است:
curl -X POST \
-H "Content-Type: application/json" \
-H "X-Goog-Api-Key: API_KEY" \
-H "X-Goog-FieldMask: places.id,places.displayName,places.entrances,places.navigationPoints" \
-d '{
"textQuery": "San Francisco International Airport",
"pageSize": 1
}' \
"https://places.googleapis.com/v1/places:searchText"
پاسخ شامل ورودی‌ها و نقاط ناوبری برای مکان است:
{ "places": [ { "id": "ChIJVVVVVYx3j4ARP-3NGldc8qQ", "displayName": { "text": "San Francisco International Airport", "languageCode": "en" }, "entrances": [ { "location": { "latitude": 37.6172154, "longitude": -122.3839724 } }, { "location": { "latitude": 37.6174073, "longitude": -122.384196 } }, ... ], "navigationPoints": [ { "navigationPointToken": "ChIJoioBjMLOQkAR0A3yH_eYXsA...", "displayName": { "text": "International Terminal Departures Level", "languageCode": "en" }, "location": { "latitude": 37.6153121, "longitude": -122.3900833 }, "travelModes": ["WALK"] }, { "navigationPointToken": "ChIJy5JKws_OQkAROx0jNN2YXsA...", "displayName": { "text": "Domestic Garage - SFO Short Term Parking", "languageCode": "en" }, "location": { "latitude": 37.6157153, "longitude": -122.3885012 }, "travelModes": ["DRIVE", "WALK"], "usages": ["PARKING"] }, ... ] } ] }
امتحان کنید!
با API Explorer می‌توانید درخواست‌های نمونه ایجاد کنید تا با API و گزینه‌های API آشنا شوید.
نماد API api را در سمت چپ صفحه انتخاب کنید.
درصورت تمایل، پارامترهای درخواست را ویرایش کنید.
دکمه اجرا را انتخاب کنید. در کادر گفتگو، حسابی را که می‌خواهید برای درخواست استفاده شود انتخاب کنید.
در پانل «کاوشگر API»، نماد تمام‌صفحه تمام‌صفحه را انتخاب کنید تا پنجره «کاوشگر API» ازهم باز شود.