مقدمه
جستجوی متن (جدید) اطلاعاتی درباره مجموعه‌ای از مکان‌ها بر اساس یک رشته (مثلاً «پیتزا در نیویورک» یا «کفش‌فروشی‌های نزدیک اتاوا» یا «خیابان اصلی ۱۲۳») برمی‌گرداند. این سرویس با فهرستی از مکان‌هایی که با رشته متن مطابقت دارند و هرگونه سوگیری مکانی که تنظیم شده است، پاسخ می‌دهد.
علاوه بر پارامترهای مورد نیاز ، جستجوی متن (جدید) از اصلاح پرس‌وجوها با استفاده از پارامترهای اختیاری برای نتایج بهتر پشتیبانی می‌کند.
مرورگر APIها به شما امکان می‌دهد درخواست‌های زنده ارسال کنید تا بتوانید با API و گزینه‌های API آشنا شوید:
درخواست‌های جستجوی متن (جدید)
یک درخواست جستجوی متن (جدید) یک درخواست 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حاوی اطلاعات دقیقی در مورد یک مکان واحد است. - فیلدماسک ارسالی در درخواست، لیست فیلدهای برگردانده شده در شیء
Placeرا مشخص می‌کند. - تضمینی وجود ندارد که لیست مکان‌های برگردانده شده برای درخواست‌های یکسان، یکسان باشد.
شیء کامل JSON به شکل زیر است:
{
"places": [
{
object (Place)
}
]
}پارامترهای مورد نیاز
فیلد ماسک
با ایجاد یک ماسک فیلد پاسخ، لیست فیلدهایی را که باید در پاسخ برگردانده شوند، مشخص کنید. ماسک فیلد پاسخ را با استفاده از پارامتر URL
$fieldsیاfieldsیا با استفاده از هدر HTTPX-Goog-FieldMaskبه متد ارسال کنید. هیچ لیست پیش‌فرضی از فیلدهای برگردانده شده در پاسخ وجود ندارد. اگر ماسک فیلد را حذف کنید، متد خطا برمی‌گرداند.ماسک کردن فیلد یک روش طراحی خوب برای اطمینان از عدم درخواست داده‌های غیرضروری است که به جلوگیری از زمان پردازش غیرضروری و هزینه‌های صورتحساب کمک می‌کند.
لیستی از انواع داده‌های مکان که با کاما از هم جدا شده‌اند را برای برگرداندن مشخص کنید. به عنوان مثال، برای بازیابی نام نمایشی و آدرس مکان.
X-Goog-FieldMask: places.displayName,places.formattedAddress
برای بازیابی همه فیلدها از
*استفاده کنید.X-Goog-FieldMask: *
یک یا چند مورد از فیلدهای زیر را مشخص کنید:
فیلدهای زیر، SKU مربوط به جستجوی متنی ملزومات با شناسه‌ی فقط (Text Search Essentials ID Only SKU) را فعال می‌کنند:
places.attributions
places.id
places.name*
nextPageToken
places.movedPlace
places.movedPlaceId* فیلد
places.nameشامل نام منبع مکان به شکلplaces/ PLACE_IDاست. برای دسترسی به نام متنی مکان، ازplaces.displayNameدر SKU نرم‌افزار Pro استفاده کنید.فیلدهای زیر SKU مربوط به Text Search Pro را فعال می‌کنند:
places.accessibilityOptions
places.addressComponents
places.addressDescriptor*
places.adrFormatAddress
places.businessStatus
places.containingPlaces
places.displayName
places.formattedAddress
places.googleMapsLinks
places.googleMapsUri
places.iconBackgroundColor
places.iconMaskBaseUri
places.location
places.photos
places.plusCode
places.postalAddress
places.primaryType
places.primaryTypeDisplayName
places.pureServiceAreaBusiness
places.shortFormattedAddress
places.searchUri
places.subDestinations
places.types
places.utcOffsetMinutes
places.viewport
* توصیفگرهای آدرس عموماً برای مشتریان در هند در دسترس هستند و در جاهای دیگر آزمایشی می‌باشند.فیلدهای زیر SKU مربوط به جستجوی متنی Enterprise را فعال می‌کنند:
places.currentOpeningHours
places.currentSecondaryOpeningHours
places.internationalPhoneNumber
places.nationalPhoneNumber
places.priceLevel
places.priceRange
places.rating
places.regularOpeningHours
places.regularSecondaryOpeningHours
places.userRatingCount
places.websiteUriفیلدهای زیر، جستجوی متن 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
* فقط جستجوی متنی و جستجوی نزدیک
پرس و جوی متنی
رشته متنی که باید جستجو شود. برای مثال، "رستوران"، "خیابان اصلی ۱۲۳" یا "بهترین مکان برای بازدید در سانفرانسیسکو". API بر اساس این رشته، موارد منطبق با کاندیدا را برمی‌گرداند و نتایج را بر اساس ارتباط درک شده آنها مرتب می‌کند.
جستجوی متن (جدید) برای پرس‌وجوهای مبهم، از جمله موارد زیر، در نظر گرفته نشده است:
نوع پرس و جو مثال مفاهیم یا محدودیت‌های بسیار زیاد، مانند نام چندین مکان، جاده یا شهر در یک پرس‌وجو «خیابان مارکت، سانفرانسیسکو، فرودگاه سن خوزه» عناصر آدرس پستی که در نقشه‌های گوگل نمایش داده نمی‌شوند «دفتر مرکزی جان اسمیت، خیابان اصلی ۱۲۳»
«صندوق پستی ۱۳ سانفرانسیسکو»نام کسب‌وکارها، زنجیره‌ها یا دسته‌بندی‌ها به همراه مکان‌هایی که این نهادها در آنها در دسترس نیستند «تسکو نزدیک دالاس، تگزاس» پرسش‌های مبهم با تفاسیر متعدد "تحویل شارژر" نام‌های تاریخی دیگر استفاده نمی‌شوند «میدلسکس، بریتانیا» عناصر یا مقاصد غیرمکان‌محور «چند قایق در بندر ونتورا وجود دارد؟» نام‌های غیررسمی یا خیالی "جنگا"
"هلتر اسکلتر"مختصات طول و عرض جغرافیایی «۳۷.۴۲۲۱۳۱، -۱۲۲.۰۸۴۸۰۱»
پارامترهای اختیاری
شاملنوع
نتایج را به مکان‌هایی که با نوع مشخص‌شده‌ی تعریف‌شده در جدول الف مطابقت دارند، بایاس می‌کند. فقط یک نوع می‌تواند مشخص شود. برای مثال:
-
"includedType":"bar" -
"includedType":"pharmacy"
جستجوی متن (جدید) بسته به کاربرد، فیلتر نوع را برای برخی از پرس‌وجوها اعمال می‌کند. برای مثال، فیلتر نوع ممکن است برای پرس‌وجوهای مربوط به آدرس‌های خاص ("خیابان اصلی ۱۲۳") اعمال نشود، اما فیلتر نوع تقریباً همیشه برای پرس‌وجوهای طبقه‌بندی‌شده ("فروشگاه‌های اطراف" یا "مراکز خرید") اعمال می‌شود.
برای اعمال فیلترینگ نوع روی همه کوئری‌ها،
strictTypeFilteringرویtrueتنظیم کنید.-
شامل PureServiceAreaBusinesses
اگر روی
trueتنظیم شود، پاسخ شامل کسب‌وکارهایی می‌شود که مستقیماً به مشتریان مراجعه می‌کنند یا به آنها کالا ارسال می‌کنند، اما مکان فیزیکی برای کسب‌وکار ندارند. اگر رویfalseتنظیم شود، API فقط کسب‌وکارهایی را برمی‌گرداند که مکان فیزیکی برای کسب‌وکار دارند.زبانکد
زبانی که نتایج با آن برگردانده می‌شوند.
- فهرست زبان‌های پشتیبانی‌شده را ببینید. گوگل اغلب زبان‌های پشتیبانی‌شده را به‌روزرسانی می‌کند، بنابراین این فهرست ممکن است جامع نباشد.
- اگر
languageCodeارائه نشود، API به طور پیش‌فرضenرا در نظر می‌گیرد. اگر کد زبان نامعتبری را مشخص کنید، API خطایINVALID_ARGUMENTرا برمی‌گرداند. - این API تمام تلاش خود را می‌کند تا آدرسی را ارائه دهد که هم برای کاربر و هم برای افراد محلی قابل خواندن باشد. برای دستیابی به این هدف، آدرس‌های خیابان را به زبان محلی برمی‌گرداند و در صورت لزوم با رعایت زبان ترجیحی، آنها را به اسکریپتی که توسط کاربر قابل خواندن باشد، تبدیل می‌کند. تمام آدرس‌های دیگر به زبان ترجیحی برگردانده می‌شوند. اجزای آدرس همگی به همان زبانی برگردانده می‌شوند که از اولین جزء انتخاب شده است.
- اگر نامی در زبان مورد نظر موجود نباشد، API از نزدیکترین مورد منطبق استفاده می‌کند.
- زبان ترجیحی تأثیر کمی بر مجموعه نتایجی که API برای برگرداندن انتخاب می‌کند و ترتیب برگرداندن آنها دارد. کدگذار جغرافیایی بسته به زبان، اختصارات را به طور متفاوتی تفسیر می‌کند، مانند اختصارات مربوط به انواع خیابان یا مترادف‌هایی که ممکن است در یک زبان معتبر باشند اما در زبان دیگر معتبر نباشند.
موقعیت مکانی
یک منطقه برای جستجو مشخص می‌کند. این مکان به عنوان یک بایاس عمل می‌کند، به این معنی که نتایج اطراف مکان مشخص شده، از جمله نتایج خارج از منطقه مشخص شده، می‌توانند بازگردانده شوند.
شما می‌توانید
locationRestrictionیاlocationBiasرا مشخص کنید، اما نه هر دو.locationRestrictionرا به عنوان مشخص‌کننده‌ی منطقه‌ای که نتایج باید درون آن باشند، وlocationBiasبه عنوان مشخص‌کننده‌ی منطقه‌ای که نتایج احتمالاً درون یا نزدیک آن خواهند بود، اما می‌توانند خارج از آن منطقه باشند، در نظر بگیرید.منطقه را به عنوان یک نمای مستطیلی یا به عنوان یک دایره مشخص کنید.
یک دایره با نقطه مرکز و شعاع بر حسب متر تعریف می‌شود. شعاع باید بین 0.0 تا 50000.0 باشد. شعاع پیش‌فرض 0.0 است. برای مثال:
"locationBias": { "circle": { "center": { "latitude": 37.7937, "longitude": -122.3965 }, "radius": 500.0 } }
مستطیل، یک نمای طول و عرض جغرافیایی است که به صورت دو نقطه پایین و بالا که به صورت مورب روبروی هم قرار دارند، نمایش داده می‌شود. نقطه پایین، گوشه جنوب غربی مستطیل و نقطه بالا، گوشه شمال شرقی مستطیل را نشان می‌دهد.
یک منظره یاب یک منطقه بسته در نظر گرفته می‌شود، به این معنی که مرز خود را شامل می‌شود. محدوده عرض جغرافیایی باید بین ۹۰- تا ۹۰ درجه و محدوده طول جغرافیایی باید بین ۱۸۰- تا ۱۸۰ درجه باشد:
- اگر
low=high، نمای دید از آن نقطه واحد تشکیل شده است. - اگر
low.longitude>high.longitudeباشد، محدوده طول جغرافیایی معکوس می‌شود (صفحه نمایش از خط طول جغرافیایی ۱۸۰ درجه عبور می‌کند). - اگر
low.longitude= -180 درجه وhigh.longitude= 180 درجه باشد، صفحه نمایش شامل تمام طول‌های جغرافیایی می‌شود. - اگر
low.longitude= 180 درجه وhigh.longitude= -180 درجه باشد، محدوده طول جغرافیایی خالی است. - اگر
low.latitude>high.latitudeباشد، محدوده عرض جغرافیایی خالی است.
هر دو پارامتر low و high باید پر شوند و کادر نمایش داده شده نمی‌تواند خالی باشد. یک viewport خالی منجر به خطا می‌شود.
برای مثال، این نمای کلی، شهر نیویورک را به طور کامل در بر می‌گیرد:
"locationBias": { "rectangle": { "low": { "latitude": 40.477398, "longitude": -74.259087 }, "high": { "latitude": 40.91618, "longitude": -73.70018 } } }
- اگر
محدودیت مکانی
محدوده‌ای را برای جستجو مشخص می‌کند. نتایج خارج از محدوده مشخص شده بازگردانده نمی‌شوند.
ناحیه را به عنوان یک Viewport مستطیلی مشخص کنید. برای مثالی از تعریف Viewport، به توضیحات
locationBiasمراجعه کنید.شما می‌توانید
locationRestrictionیاlocationBiasرا مشخص کنید، اما نه هر دو.locationRestrictionرا به عنوان مشخص‌کننده‌ی منطقه‌ای که نتایج باید درون آن باشند، وlocationBiasبه عنوان مشخص‌کننده‌ی منطقه‌ای که نتایج احتمالاً درون یا نزدیک آن خواهند بود، اما می‌توانند خارج از آن منطقه باشند، در نظر بگیرید.maxResultCount (منسوخ شده)
تعداد نتایج (بین ۱ تا ۲۰) را برای نمایش در هر صفحه مشخص می‌کند. برای مثال، تنظیم مقدار
maxResultCountبرابر با ۵، حداکثر ۵ نتیجه را در صفحه اول برمی‌گرداند. اگر نتایج بیشتری از کوئری قابل بازگشت باشد، پاسخ شامل یکnextPageTokenاست که می‌توانید برای دسترسی به صفحه بعد، آن را به درخواست بعدی ارسال کنید.گزینه‌های ev
پارامترهایی را برای شناسایی کانکتورهای شارژ خودروی برقی (EV) موجود و نرخ‌های شارژ مشخص می‌کند.
انواع کانکتور
فیلترها بر اساس نوع کانکتور شارژ خودروی برقی موجود در یک مکان. مکانی که از هیچ یک از انواع کانکتور پشتیبانی نکند، فیلتر خواهد شد. انواع کانکتور شارژ خودروی برقی پشتیبانی شده شامل شارژرهای ترکیبی (AC و DC)، شارژرهای تسلا، شارژرهای سازگار با GB/T (برای شارژ سریع خودروی برقی در چین) و شارژرهای پریز برق دیواری است. برای اطلاعات بیشتر، به مستندات مرجع مراجعه کنید.
- برای فیلتر کردن نتایج برای یک کانکتور پشتیبانی‌شده‌ی خاص ،
connectorTypesروی آن مقدار تنظیم کنید. برای مثال، برای یافتن کانکتورهای J1772 نوع 1،connectorTypesرویEV_CONNECTOR_TYPE_J1772تنظیم کنید. - برای فیلتر کردن نتایج برای کانکتورهای پشتیبانی نشده ،
connectorTypesرویEV_CONNECTOR_TYPE_OTHERتنظیم کنید. - برای فیلتر کردن نتایج برای هر نوع کانکتوری که یک پریز برق دیواری است،
connectorTypesرویEV_CONNECTOR_TYPE_UNSPECIFIED_WALL_OUTLETتنظیم کنید. - برای فیلتر کردن نتایج برای هر نوع کانکتور، یا
connectorTypesرویEV_CONNECTOR_TYPE_UNSPECIFIEDتنظیم کنید یا مقداری برایconnectorTypesتعیین نکنید.
- برای فیلتر کردن نتایج برای یک کانکتور پشتیبانی‌شده‌ی خاص ،
حداقل نرخ شارژ کیلووات
مکان‌ها را بر اساس حداقل نرخ شارژ خودروهای برقی بر حسب کیلووات (kW) فیلتر می‌کند. هر مکانی که نرخ شارژ آن کمتر از حداقل نرخ شارژ باشد، فیلتر می‌شود. به عنوان مثال، برای یافتن شارژرهای خودروهای برقی با نرخ شارژ حداقل 10 کیلووات، می‌توانید این پارامتر را روی "10" تنظیم کنید.
دقیقه رتبه‌بندی
نتایج را فقط به مواردی محدود می‌کند که میانگین امتیاز کاربران آنها بزرگتر یا مساوی این حد باشد. مقادیر باید بین 0.0 تا 5.0 (شامل) با گام‌های 0.5 باشند. برای مثال: 0، 0.5، 1.0، ...، 5.0 (شامل). مقادیر به نزدیکترین عدد 0.5 به بالا گرد می‌شوند. برای مثال، مقدار 0.6 تمام نتایج با امتیاز کمتر از 1.0 را حذف می‌کند.
اکنون باز است
اگر
true، فقط مکان‌هایی را برمی‌گرداند که در زمان ارسال پرس‌وجو باز هستند. اگرfalse، همه مکان‌های کسب‌وکار را صرف نظر از وضعیت باز بودنشان برمی‌گرداند. مکان‌هایی که ساعات کاری مشخصی در پایگاه داده Google Places ندارند، در صورت تنظیم این پارامتر رویfalse، بازگردانده می‌شوند.اندازه صفحه
تعداد نتایج (بین ۱ تا ۲۰) را برای نمایش در هر صفحه مشخص می‌کند. برای مثال، تنظیم مقدار
pageSizeبرابر با ۵، حداکثر ۵ نتیجه را در صفحه اول برمی‌گرداند. اگر نتایج بیشتری از کوئری قابل بازگشت باشند، پاسخ شامل یکnextPageTokenاست که می‌توانید برای دسترسی به صفحه بعدی به درخواست بعدی ارسال کنید.توکن صفحه
nextPageTokenاز بدنه پاسخ صفحه قبلی مشخص می‌کند.قیمت‌ها
جستجو را به مکان‌هایی که در سطوح قیمت خاصی علامت‌گذاری شده‌اند محدود کنید. پیش‌فرض این است که همه سطوح قیمت را انتخاب کنید.
سطوح قیمت را می‌توان برای مکان‌هایی از انواع زیر انتظار داشت:
اگر
priceLevelsمشخص شده باشد، مکان‌هایی که از نوع‌های پشتیبانی نشده هستند، در پاسخ لحاظ نخواهند شد.آرایه‌ای از یک یا چند مقدار تعریف شده توسط
PriceLevelرا مشخص کنید.برای مثال:
"priceLevels":["PRICE_LEVEL_INEXPENSIVE", "PRICE_LEVEL_MODERATE"]
رتبه بندی
نحوه رتبه‌بندی نتایج در پاسخ را بر اساس نوع پرس‌وجو مشخص می‌کند:
- برای یک عبارت جستجوی دسته‌بندی‌شده مانند «رستوران‌ها در شهر نیویورک»،
RELEVANCE(رتبه‌بندی نتایج بر اساس ارتباط جستجو) پیش‌فرض است. می‌توانیدrankPreferenceرویRELEVANCEیاDISTANCE(رتبه‌بندی نتایج بر اساس فاصله) تنظیم کنید. - برای یک عبارت جستجوی غیر دسته‌بندی‌شده مانند «مانتین ویو، کالیفرنیا»، توصیه می‌کنیم
rankPreferenceبدون تنظیم رها کنید.
- برای یک عبارت جستجوی دسته‌بندی‌شده مانند «رستوران‌ها در شهر نیویورک»،
کد منطقه
کد منطقه‌ای مورد استفاده برای قالب‌بندی پاسخ، که به عنوان یک مقدار کد 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" } }, { "formattedAddress": "29 King St, Sydney NSW 2000, Australia", "displayName": { "text": "Peace Harmony", "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 و سایر پارامترهای شرح داده شده در Optional parameters را اضافه کنید.
محدود کردن جستجو به یک منطقه مشخص
برای محدود کردن جستجو به یک منطقه، از locationRestriction یا locationBias استفاده کنید، اما نه هر دو. locationRestriction را به عنوان مشخص کننده منطقه‌ای که نتایج باید در آن باشند، و locationBias به عنوان مشخص کننده منطقه‌ای که نتایج باید نزدیک به آن باشند اما می‌توانند خارج از آن منطقه باشند، در نظر بگیرید.
محدود کردن منطقه با استفاده از locationRestriction
از پارامتر locationRestriction برای محدود کردن نتایج پرس‌وجو به یک منطقه مشخص استفاده کنید. در بدنه درخواست خود، مقادیر طول و عرض جغرافیایی low و high را که مرز منطقه را تعریف می‌کنند، مشخص کنید.
مثال زیر یک درخواست جستجوی متنی (جدید) برای "غذای گیاهی" در شهر نیویورک را نشان می‌دهد. این درخواست فقط 10 نتیجه اول را برای مکان‌هایی که باز هستند، برمی‌گرداند.
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'
شارژرهای EV با حداقل نرخ شارژ را جستجو کنید
از minimumChargingRateKw و connectorTypes برای جستجوی مکان‌هایی با شارژرهای موجود که با EV شما سازگار هستند، استفاده کنید.
مثال زیر درخواستی برای کانکتورهای شارژ خودروهای برقی تسلا و J1772 نوع 1 با حداقل نرخ شارژ 10 کیلووات در مانتین ویو، کالیفرنیا را نشان می‌دهد. فقط چهار نتیجه برگردانده شده است.
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" }, { "type": "EV_CONNECTOR_TYPE_CCS_COMBO_1", "maxChargeRateKw": 350, "count": 6, "availableCount": 3, "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" } ] } }, { "displayName": { "text": "EVgo Charging Station", "languageCode": "en" }, "evChargeOptions": { "connectorCount": 5, "connectorAggregation": [ { "type": "EV_CONNECTOR_TYPE_J1772", "maxChargeRateKw": 3.5999999046325684, "count": 1, "availableCount": 0, "outOfServiceCount": 1, "availabilityLastUpdateTime": "2024-01-10T19:10:00Z" }, { "type": "EV_CONNECTOR_TYPE_CHADEMO", "maxChargeRateKw": 50, "count": 2, "availableCount": 0, "outOfServiceCount": 0, "availabilityLastUpdateTime": "2024-01-10T19:10:00Z" }, { "type": "EV_CONNECTOR_TYPE_CCS_COMBO_1", "maxChargeRateKw": 50, "count": 2, "availableCount": 0, "outOfServiceCount": 0, "availabilityLastUpdateTime": "2024-01-10T19:10:00Z" } ] } }, { "displayName": { "text": "Electric Vehicle Charging Station", "languageCode": "en" }, "evChargeOptions": { "connectorCount": 10, "connectorAggregation": [ { "type": "EV_CONNECTOR_TYPE_OTHER", "maxChargeRateKw": 210, "count": 10 } ] } } ] }
جستجوی کسب و کارهای حوزه خدمات
از پارامتر 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" } }, { "formattedAddress": "1455 Bancroft Ave, San Francisco, CA 94124, USA", "displayName": { "text": "Magic Plumbing Heating & Cooling", "languageCode": "en" } }, /.../ { "displayName": { "text": "Starboy Plumbing Inc.", "languageCode": "en" } }, { "formattedAddress": "78 Dorman Ave, San Francisco, CA 94124, USA", "displayName": { "text": "Cabrillo Plumbing, Heating & Air", "languageCode": "en" } }, { "formattedAddress": "540 Barneveld Ave # D, San Francisco, CA 94124, USA", "displayName": { "text": "Mr. Rooter Plumbing of San Francisco", "languageCode": "en" } }, /.../ { "displayName": { "text": "Pipeline Plumbing", "languageCode": "en" } }, { "formattedAddress": "350 Bay St #100-178, San Francisco, CA 94133, USA", "displayName": { "text": "One Source Plumbing and Rooter", "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" }, { "id": "ChIJrXXKn5NZwokR78g0ipCnY60" }, { "id": "ChIJ6ySICVZYwokR9rIK8HjXhzE" }, { "id": "ChIJ6xvs94VZwokRnT1D2lX2OTw" } ], "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" }, { "id": "ChIJ6ffdpJNZwokRmcafdROM5q0" }, { "id": "ChIJ8Q2WSpJZwokRQz-bYYgEskM" }, { "id": "ChIJ8164qwFZwokRhplkmhvq1uE" } ], "nextPageToken": "AeCrKXvPd6uUy-oj96W2OaqEe2pUD8QTxOM8-sKfUcFsC9t2Wey5qivrKGoGSxcZnyc7RPmaFfAktslrKbUh31ZDTkL0upRmaxA7c_c" }
دریافت توصیفگرهای آدرس
توصیفگرهای آدرس، اطلاعات نسبی در مورد موقعیت مکانی یک مکان، از جمله نشانه‌های نزدیک و مناطق اطراف آن را ارائه می‌دهند.
مثال زیر یک درخواست جستجوی متن (جدید) برای مکان‌های نزدیک یک مرکز خرید در سن خوزه را نشان می‌دهد. در این مثال، شما addressDescriptors در فیلد mask قرار می‌دهید:
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 }, { "name": "places/ChIJ8WvuSB7Lj4ARFyHppkxDRQ4", "placeId": "ChIJ8WvuSB7Lj4ARFyHppkxDRQ4", "displayName": { "text": "Macy's", "languageCode": "en" }, "types": [ "clothing_store", "department_store", "establishment", "point_of_interest", "store" ], "straightLineDistanceMeters": 116.24196 }, { "name": "places/ChIJ9d3plB_Lj4ARzyaU5bn80WY", "placeId": "ChIJ9d3plB_Lj4ARzyaU5bn80WY", "displayName": { "text": "Bank of America Financial Center", "languageCode": "en" }, "types": [ "bank", "establishment", "finance", "point_of_interest" ], "straightLineDistanceMeters": 121.61515 }, { "name": "places/ChIJaXCjxvXLj4ARCPmQpvJ52Lw", "placeId": "ChIJaXCjxvXLj4ARCPmQpvJ52Lw", "displayName": { "text": "Bloomingdale's", "languageCode": "en" }, "types": [ "clothing_store", "department_store", "establishment", "furniture_store", "home_goods_store", "point_of_interest", "shoe_store", "store" ], "straightLineDistanceMeters": 81.32396 } ], "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" }, { "name": "places/ChIJtYoUX2DLj4ARKoKOb1G0CpM", "placeId": "ChIJtYoUX2DLj4ARKoKOb1G0CpM", "displayName": { "text": "Central San Jose", "languageCode": "en" }, "containment": "WITHIN" } ] } }, /.../ ] }
امتحانش کن!
مرورگر APIها به شما امکان می‌دهد درخواست‌های نمونه ایجاد کنید تا با API و گزینه‌های API آشنا شوید.
آیکون API یعنی api را در سمت راست صفحه انتخاب کنید.
در صورت تمایل، پارامترهای درخواست را ویرایش کنید.
دکمه اجرا را انتخاب کنید. در کادر محاوره‌ای، حسابی را که می‌خواهید برای ارسال درخواست استفاده کنید، انتخاب کنید.
در پنل APIs Explorer، آیکون تمام صفحه را در حالت تمام صفحه انتخاب کنید تا پنجره APIs Explorer باز شود.