مقدمه
درخواست جستجوی اطراف (جدید) یک یا چند نوع مکان را می‌گیرد و فهرستی از مکان‌های منطبق در منطقه مشخص‌شده برمی‌گرداند. پوشش فیلدی که یک یا چند نوع داده را مشخص می‌کند الزامی است. «جستجوی اطراف» (جدید) فقط از درخواست‌های POST پشتیبانی می‌کند.
APIs Explorer به شما امکان می‌دهد درخواست‌های زنده ارسال کنید تا بتوانید با میانای برنامه‌سازی کاربردی و گزینه‌های میانای برنامه‌سازی کاربردی آشنا شوید:
نمونه تعاملی را امتحان کنید تا نتایج «جستجوی اطراف» (جدید) را که روی نقشه نمایش داده می‌شود ببینید.
درخواست‌های «جستجوی اطراف» (جدید)
درخواست «جستجوی مکان‌های اطراف (جدید)» یک درخواست HTTP POST به نشانی وب در فرم است:
https://places.googleapis.com/v1/places:searchNearby
همه پارامترها را در بدنه درخواست JSON یا در سرایندها به‌عنوان بخشی از درخواست POST بگذرانید. برای مثال:
curl -X POST -d '{
"includedTypes": ["restaurant"],
"maxResultCount": 10,
"locationRestriction": {
"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" \
https://places.googleapis.com/v1/places:searchNearby
پاسخ‌های «جستجوی اطراف» (جدید)
«جستجوی اطراف» (جدید) یک شیء 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: *
یک یا چند فیلد زیر را مشخص کنید:
فیلدهای زیر Nearby Search Pro SKU را راه‌اندازی می‌کنند:
places.accessibilityOptions
places.addressComponents
places.addressDescriptor*
places.adrFormatAddress
places.attributions
places.businessStatus
places.consumerAlert
places.containingPlaces
places.displayName
places.formattedAddress
places.googleMapsLinks
places.googleMapsTypeLabel
places.googleMapsUri
places.iconBackgroundColor
places.iconMaskBaseUri
places.id
places.location
places.name**
places.movedPlace
places.movedPlaceId
places.openingDate
places.photos
places.plusCode
places.postalAddress
places.primaryType
places.primaryTypeDisplayName
places.pureServiceAreaBusiness
places.shortFormattedAddress
places.subDestinations
places.timeZone
places.types
places.utcOffsetMinutes
places.viewport
* توصیف‌کننده‌های نشانی به‌طور کلی برای مشتریان در هند دردسترس است و در جاهای دیگر آزمایشی است.
** فیلدplaces.nameحاوی نام منبع مکان به این شکل است:places/PLACE_ID. ازplaces.displayNameبرای دسترسی به نام نوشتاری مکان استفاده کنید.برای فهرست کامل فیلدها و «واحد نگهداری کالا» مرتبط با آن‌ها، فیلدهای داده مکان (جدید) را ببینید.
فیلدهای زیر Nearby Search Enterprise 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 «سازمانی جستجوی اطراف + Atmosphere» را راه‌اندازی می‌کنند:
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
* فقط «جستجوی نوشتار» و «جستجوی اطراف»برای فهرست کامل فیلدها و «واحد نگهداری کالا» مرتبط با آن‌ها، فیلدهای داده مکان (جدید) را ببینید.
-
locationRestriction
منطقه‌ای که باید جستجو شود به‌صورت دایره‌ای مشخص می‌شود که با نقطه مرکزی و شعاع به متر تعریف می‌شود. شعاع باید بین ۰٫۰ و ۵۰۰۰۰٫۰ باشد و می‌تواند این دو عدد را نیز دربر بگیرد. شعاع پیش‌فرض ۰٫۰ است. باید آن را در درخواستتان روی مقداری بزرگ‌تر از ۰٫۰ تنظیم کنید.
برای مثال:
"locationRestriction": { "circle": { "center": { "latitude": 37.7937, "longitude": -122.3965 }, "radius": 500.0 } }
پارامترهای اختیاری
-
includeFutureOpeningBusinesses
اگر
true، کسب‌وکارهایی را برمی‌گرداند که انتظار می‌رود در آینده باز شوند. پیش‌فرضfalseاست.
برای بازیابی وضعیت کسب‌وکار،places.businessStatusرا در پوشش فیلد درخواستتان بگنجانید. برای بازیابی تاریخ افتتاح پیش‌بینی‌شده کسب‌وکار،places.openingDateرا در پوشش فیلد درخواستتان بگنجانید. -
includedTypes/excludedTypes, includedPrimaryTypes/excludedPrimaryTypes
به شما امکان می‌دهد فهرستی از انواع را از انواع جدول A مشخص کنید که برای فیلتر کردن نتایج جستجو استفاده می‌شود. حداکثر ۵۰ نوع را می‌توان در هر دسته محدودیت نوع مشخص کرد.
مکان فقط می‌تواند یک نوع اصلی از انواع جدول A منسوب به آن داشته باشد. برای مثال، نوع اصلی ممکن است
"mexican_restaurant"یا"steak_house"باشد. ازincludedPrimaryTypesوexcludedPrimaryTypesبرای فیلتر کردن نتایج براساس نوع اصلی مکان استفاده کنید.مکان همچنین می‌تواند چندین مقدار نوع از انواع جدول الف مرتبط با آن داشته باشد. برای مثال، رستورانی ممکن است انواع زیر را داشته باشد:
"seafood_restaurant"،"restaurant"،"food"،"point_of_interest"،"establishment". ازincludedTypesوexcludedTypesبرای فیلتر کردن نتایج در فهرست انواع منسوب به یک مکان استفاده کنید.وقتی نوع اصلی عمومی را مشخص می‌کنید، مثلاً
"restaurant"یا"hotel"، پاسخ می‌تواند حاوی مکان‌هایی با نوع اصلی خاص‌تر از نوع مشخص‌شده باشد. برای مثال، مشخص می‌کنید که نوع اصلی"restaurant"گنجانده شود. درنتیجه، پاسخ می‌تواند حاوی مکان‌هایی با نوع اصلی"restaurant"باشد، اما پاسخ می‌تواند حاوی مکان‌هایی با نوع اصلی خاص‌تر، مثل"chinese_restaurant"یا"seafood_restaurant"، نیز باشد.اگر جستجویی با چندین محدودیت نوع مشخص شده باشد، فقط مکان‌هایی که همه محدودیت‌ها را برآورده می‌کنند برگردانده می‌شوند. برای مثال، اگر
{"includedTypes": ["restaurant"], "excludedPrimaryTypes": ["steak_house"]}را مشخص کنید، مکان‌های برگشتی خدمات مرتبط با"restaurant"را ارائه می‌دهند اما در درجه اول به‌عنوان"steak_house"فعالیت نمی‌کنند.includedTypes
فهرست جداشده با کاما از انواع مکان‌ها از جدول الف برای جستجو. اگر این پارامتر حذف شود، مکان‌های همه انواع برگردانده می‌شود.
excludedTypes
فهرست انواع مکان جداشده با کاما از جدول الف برای مستثنا کردن از جستجو.
اگر هم
includedTypes( مانند"school") و همexcludedTypes(مانند"primary_school") را در درخواست مشخص کنید، پاسخ شامل مکان‌هایی می‌شود که به‌عنوان"school"دسته‌بندی شده‌اند اما به‌عنوان"primary_school"دسته‌بندی نشده‌اند. پاسخ شامل مکان‌هایی است که با حداقل یکی ازincludedTypesمطابقت دارد و با هیچ‌کدام ازexcludedTypesمطابقت ندارد.اگر نوع‌های متعارضی وجود داشته باشد، مثلاً نوعی که هم در
includedTypesو هم درexcludedTypesظاهر می‌شود، خطایINVALID_REQUESTبرگردانده می‌شود.includedPrimaryTypes
فهرست انواع مکان اصلی جداشده با کاما از جدول الف برای گنجاندن در جستجو.
excludedPrimaryTypes
فهرست جداشده با کاما از انواع مکان‌های اصلی از جدول الف برای مستثنی کردن از جستجو.
اگر نوع‌های اصلی متعارضی وجود داشته باشد، مثلاً نوعی که هم در
includedPrimaryTypesو هم درexcludedPrimaryTypesظاهر شود، خطایINVALID_ARGUMENTبرگردانده می‌شود. -
languageCode
زبانی که نتایج به آن برگردانده می‌شود.
- فهرست زبان‌های پشتیبانی‌شده را ببینید. Google اغلب زبان‌های پشتیبانی‌شده را به‌روز می‌کند، بنابراین این فهرست ممکن است کامل نباشد.
- اگر
languageCodeارائه نشود، میانای برنامه‌سازی کاربردی به‌طور پیش‌فرض ازenاستفاده می‌کند. اگر کد زبان نامعتبری را مشخص کنید، API خطایINVALID_ARGUMENTبرمی‌گرداند. - این API تلاش می‌کند نشانی خیابانی ارائه دهد که هم برای کاربر و هم برای افراد محلی خوانا باشد. برای دستیابی به این هدف، نشانی‌های خیابان را به زبان محلی برمی‌گرداند و درصورت لزوم، آن‌ها را به خطی که کاربر بتواند بخواند آوانویسی می‌کند و زبان ترجیحی را رعایت می‌کند. همه نشانی‌های دیگر به زبان ترجیحی برگردانده می‌شوند. اجزای نشانی همه به یک زبان برگردانده می‌شوند که از اولین جزء انتخاب می‌شود.
- اگر نامی به زبان ترجیحی دردسترس نباشد، API از نزدیک‌ترین مطابقت استفاده می‌کند.
- زبان ترجیحی تأثیر کمی بر مجموعه نتایجی دارد که API برای برگرداندن انتخاب می‌کند و ترتیبی که در آن برگردانده می‌شوند. کدبند جغرافیایی بسته به زبان، مخفف‌ها را به‌صورت متفاوت تفسیر می‌کند، مثلاً مخفف‌های انواع خیابان، یا مترادف‌هایی که ممکن است در یک زبان معتبر باشند اما در زبان دیگر معتبر نباشند.
-
maxResultCount
حداکثر تعداد نتایج مکان را برای برگشت مشخص می‌کند. باید بین ۱ و ۲۰ (پیش‌فرض) فراگیر باشد.
-
rankPreference
نوع رتبه‌بندی برای استفاده. اگر این پارامتر حذف شود، نتایج براساس محبوبیت رتبه‌بندی می‌شوند. می‌تواند یکی از موارد زیر باشد:
POPULARITY(پیش‌فرض) نتایج را براساس محبوبیت آن‌ها مرتب می‌کند.DISTANCEنتایج را براساس فاصله آن‌ها از مکان مشخص‌شده به‌ترتیب صعودی مرتب می‌کند.
-
regionCode
کد منطقه‌ای که برای قالب‌بندی پاسخ استفاده می‌شود، به‌عنوان مقدار کد CLDR دو نویسه‌ای مشخص شده است. مقدار پیش‌فرضی وجود ندارد.
اگر نام کشور فیلد
formattedAddressدر پاسخ باregionCodeمطابقت داشته باشد، کد کشور ازformattedAddressحذف می‌شود. این پارامتر هیچ تأثیری برadrFormatAddressندارد، که همیشه نام کشور را دربرمی‌گیرد، یا برshortFormattedAddress، که هرگز آن را دربرنمی‌گیرد.اکثر کدهای CLDR با کدهای ISO 3166-1 یکسان هستند، با چند استثنای قابل‌توجه. برای مثال، دامنه سطح بالای کد کشور پادشاهی متحد «uk» (co.uk.) است، درحالی‌که کد ISO 3166-1 آن «gb» است (ازنظر فنی برای نهاد «پادشاهی متحد بریتانیای کبیر و ایرلند شمالی»). این پارامتر می‌تواند براساس قانون ذی‌ربط بر نتایج تأثیر بگذارد.
نمونه‌های «جستجوی اطراف» (جدید)
پیدا کردن مکان‌های یک نوع
مثال زیر درخواست «جستجوی اطراف» (جدید) را برای نمایش
نام‌های همه رستوران‌ها در شعاع ۵۰۰ متری نشان می‌دهد که با circle تعریف شده است:
curl -X POST -d '{
"includedTypes": ["restaurant"],
"maxResultCount": 10,
"locationRestriction": {
"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" \
https://places.googleapis.com/v1/places:searchNearby
توجه داشته باشید که سرصفحه X-Goog-FieldMask مشخص می‌کند که پاسخ
شامل فیلدهای داده زیر است: places.displayName.
پاسخ
به این شکل است:
{ "places": [ { "displayName": { "text": "La Mar Cocina Peruana", "languageCode": "en" } }, { "displayName": { "text": "Kokkari Estiatorio", "languageCode": "en" } }, { "displayName": { "text": "Harborview Restaurant & Bar", "languageCode": "en" } }, ... }
انواع داده بیشتری به پوشش فیلد اضافه کنید تا اطلاعات بیشتری برگردانده شود.
برای مثال، places.formattedAddress,places.types,places.websiteUri را اضافه کنید تا نشانی، نوع، و نشانی وب رستوران در پاسخ گنجانده شود:
curl -X POST -d '{
"includedTypes": ["restaurant"],
"maxResultCount": 10,
"locationRestriction": {
"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,places.types,places.websiteUri" \
https://places.googleapis.com/v1/places:searchNearby
پاسخ اکنون در فرم است:
{ "places": [ { "types": [ "seafood_restaurant", "restaurant", "food", "point_of_interest", "establishment" ], "formattedAddress": "PIER 1 1/2 The Embarcadero N, San Francisco, CA 94105, USA", "websiteUri": "http://lamarsf.com/", "displayName": { "text": "La Mar Cocina Peruana", "languageCode": "en" } }, { "types": [ "greek_restaurant", "meal_takeaway", "restaurant", "food", "point_of_interest", "establishment" ], "formattedAddress": "200 Jackson St, San Francisco, CA 94111, USA", "websiteUri": "https://kokkari.com/", "displayName": { "text": "Kokkari Estiatorio", "languageCode": "en" } }, ... }
پیدا کردن مکان‌هایی از انواع مختلف
مثال زیر درخواست «جستجوی اطراف» (جدید) را برای
نام‌های نمایشی همه فروشگاه‌های رفاهی و مشروب‌فروشی‌ها در شعاع ۱۰۰۰ متری
circle مشخص‌شده نشان می‌دهد:
curl -X POST -d '{
"includedTypes": ["liquor_store", "convenience_store"],
"maxResultCount": 10,
"locationRestriction": {
"circle": {
"center": {
"latitude": 37.7937,
"longitude": -122.3965
},
"radius": 1000.0
}
}
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
-H "X-Goog-FieldMask: places.displayName,places.primaryType,places.types" \
https://places.googleapis.com/v1/places:searchNearby
places.primaryType و places.types را به پوشش فیلد اضافه می‌کند
تا پاسخ شامل اطلاعات نوع درباره هر مکان باشد و انتخاب مکان
مناسب از نتایج را آسان‌تر کند.
کنار گذاشتن نوع مکان از جستجو
مثال زیر درخواست «جستجوی اطراف» (جدید) را برای همه مکان‌های
نوع "school" نشان می‌دهد، همه مکان‌های نوع "primary_school" را مستثنا می‌کند، و نتایج را براساس
فاصله رتبه‌بندی می‌کند:
curl -X POST -d '{
"includedTypes": ["school"],
"excludedTypes": ["primary_school"],
"maxResultCount": 10,
"locationRestriction": {
"circle": {
"center": {
"latitude": 37.7937,
"longitude": -122.3965
},
"radius": 1000.0
}
},
"rankPreference": "DISTANCE"
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
-H "X-Goog-FieldMask: places.displayName" \
https://places.googleapis.com/v1/places:searchNearby
جستجوی همه مکان‌های نزدیک یک منطقه، رتبه‌بندی براساس فاصله
مثال زیر درخواست «جستجوی اطراف» (جدید) برای مکان‌های
نزدیک نقطه‌ای در مرکز شهر سان‌فرانسیسکو را نشان می‌دهد. در این مثال، پارامتر rankPreference را برای رتبه‌بندی نتایج براساس فاصله اضافه می‌کنید:
curl -X POST -d '{
"maxResultCount": 10,
"rankPreference": "DISTANCE",
"locationRestriction": {
"circle": {
"center": {
"latitude": 37.7937,
"longitude": -122.3965
},
"radius": 1000.0
}
}
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
-H "X-Goog-FieldMask: places.displayName" \
https://places.googleapis.com/v1/places:searchNearby
دریافت توصیفگرهای نشانی
توصیفگرهای نشانی اطلاعات رابطه‌ای درباره مکان ارائه می‌دهند، ازجمله نشانگرهای مکانی اطراف و مناطق دربرگیرنده.
مثال زیر درخواست «جستجوی اطراف» (جدید) برای مکان‌های نزدیک
مرکز خریدی در سن‌خوزه را نشان می‌دهد. در این مثال، addressDescriptors
را در پوشش فیلد اضافه می‌کنید:
curl -X POST -d '{
"maxResultCount": 5,
"locationRestriction": {
"circle": {
"center": {
"latitude": 37.321328,
"longitude": -121.946275
},"radius": 1000
}
},
"includedTypes": ["restaurant", "cafe"],
"excludedTypes": [],
"rankPreference":"POPULARITY"
}' \
-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:searchNearby
پاسخ شامل مکان مشخص‌شده در درخواست، فهرستی از نشان‌های نزدیک و فاصله آن‌ها از مکان، و فهرستی از مناطق و رابطه محصور بودن آن‌ها با مکان است:
{ "places": [ { "displayName": { "text": "Westfield Valley Fair", "languageCode": "en" }, "addressDescriptor": { "landmarks": [ { "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": 114.76984, "travelDistanceMeters": 114.261856 }, { "name": "places/ChIJgexMlR_Lj4ARiKCKuhNnjn0", "placeId": "ChIJgexMlR_Lj4ARiKCKuhNnjn0", "displayName": { "text": "Valley Fair Mall Eyexam of CA", "languageCode": "en" }, "types": [ "establishment", "health", "point_of_interest" ], "straightLineDistanceMeters": 131.62566, "travelDistanceMeters": 237.33253 }, { "name": "places/ChIJWWIlNx7Lj4ARpe1E0ob-_GI", "placeId": "ChIJWWIlNx7Lj4ARpe1E0ob-_GI", "displayName": { "text": "Din Tai Fung", "languageCode": "en" }, "types": [ "establishment", "food", "point_of_interest", "restaurant" ], "straightLineDistanceMeters": 110.0775, "travelDistanceMeters": 171.41951 }, { "name": "places/ChIJwyfPQx7Lj4AR7bYI2A2Yc54", "placeId": "ChIJwyfPQx7Lj4AR7bYI2A2Yc54", "displayName": { "text": "Abercrombie & Fitch", "languageCode": "en" }, "types": [ "clothing_store", "establishment", "point_of_interest", "shoe_store", "store" ], "spatialRelationship": "DOWN_THE_ROAD", "straightLineDistanceMeters": 53.620117, "travelDistanceMeters": 2.4578214 }, { "name": "places/ChIJpycNQx7Lj4ARjhXw3PrM_kU", "placeId": "ChIJpycNQx7Lj4ARjhXw3PrM_kU", "displayName": { "text": "Hollister Co.", "languageCode": "en" }, "types": [ "clothing_store", "establishment", "point_of_interest", "shoe_store", "store" ], "spatialRelationship": "DOWN_THE_ROAD", "straightLineDistanceMeters": 56.53726, "travelDistanceMeters": 15.418246 } ], "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": "OUTSKIRTS" } ] } }, /.../ }
پیدا کردن کسب‌وکارهایی که در آینده باز می‌شوند
مثال زیر درخواست «جستجوی اطراف» (جدید) را برای کسب‌وکارهایی که در آینده در نیو میدوز، آیداهو باز می‌شوند نشان می‌دهد:
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 '{
"includeFutureOpeningBusinesses": true,
"maxResultCount": 20,
"locationRestriction": {
"circle": {
"center": {"latitude": 44.9755100, "longitude": -116.2842180},
"radius": 20
}
},
"rankPreference": "DISTANCE"
}' \
"https://places.googleapis.com/v1/places:searchNearby"
پاسخ شامل کسب‌وکارهایی است که در آینده باز خواهند شد، به‌همراه وضعیت کسب‌وکار و تاریخ افتتاح پیش‌بینی‌شده:
{ "places": [ { "id": "ChIJp1-VoKWJplQRMz8g-7Wa3Do", "businessStatus": "FUTURE_OPENING", "displayName": { "text": "Roberts Greenhouse and Tree Farm", "languageCode": "en" }, "openingDate": { "year": 2026, "month": 4, "day": 15 } } ] }
دریافت اطلاعات ایستگاه حمل‌ونقل عمومی
می‌توانید از Nearby Search (New) برای دریافت اطلاعات درباره ایستگاه‌های حمل‌ونقل عمومی در شعاع مشخصی از یک مکان معین استفاده کنید. بدنه پاسخ شامل اطلاعاتی درباره ایستگاه است، ازجمله نام ایستگاه، دفاتر حمل‌ونقل عمومی وابسته، و خطوط حمل‌ونقل عمومی که به ایستگاه خدمات ارائه می‌دهند. علاوه‌براین، پاسخ شامل نماد وسیله نقلیه و رنگ‌هایی است که می‌توانید از آن‌ها برای نمایش اطلاعات ایستگاه حمل‌ونقل عمومی استفاده کنید.
مثال زیر درخواست ایستگاه‌های ترابری در فاصله ۵۰ متری از مرکز منهتن را نشان می‌دهد:
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 '{
"includedTypes": ["transit_station"],
"locationRestriction": {
"circle": {
"center": {"latitude": 40.754851, "longitude": -73.984164},
"radius": 50.0
}
}
}' \
"https://places.googleapis.com/v1/places:searchNearby"
بدنه پاسخ شامل اطلاعاتی درباره هر ایستگاه در آن شعاع، خطوطی که آن ایستگاه به آن‌ها خدمات می‌دهد، هشدارهای صادرشده توسط سازمان‌های حمل‌ونقل عمومی در آن ایستگاه، و اطلاعات حرکت است:
{ "places": [ { "id": "ChIJH2EstKpZwokRCwZtYyMd5Fg", "displayName": { "text": "6 Av/W 41 St", "languageCode": "en" }, "transitStation": { "displayName": { "text": "6 Av/W 41 St", "languageCode": "en" }, "agencies": [ { "displayName": { "text": "ShortLine Hudson", "languageCode": "en" }, "url": "https://www.coachusa.com/", "lines": [ { "id": "ChIJSQlbzvPwwokRolrIA-Kuh6o", "vehicleType": "BUS", "displayName": { "text": "200 - Northern District – Nanuet", "languageCode": "en" }, "shortDisplayName": { "text": "ShortLine Hudson", "languageCode": "en" }, "textColor": "#000000", "backgroundColor": "#ED60A3", "vehicleIcon": { "url": "https://maps.gstatic.com/mapfiles/transit/iw2/svg/bus2.svg" } } ] }, { "displayName": { "text": "MTA New York City Transit", "languageCode": "en" }, "url": "http://www.mta.info/", "lines": [ { "id": "ChIJjUrj7PBewokR3O3S2JVpBrI", "vehicleType": "SUBWAY", "displayName": { "text": "E Train (8 Av Local)", "languageCode": "en" }, "shortDisplayName": { "text": "E Line", "languageCode": "en" }, "textColor": "#FFFFFF", "backgroundColor": "#0039A6", "url": "https://www.mta.info/schedules/subway/e-train", "icon": { "url": "https://maps.gstatic.com/mapfiles/transit/iw2/svg/us-ny-mta/E.svg", "nameIncluded": true }, "vehicleIcon": { "url": "https://maps.gstatic.com/mapfiles/transit/iw2/svg/subway2.svg" } }, ... ] }, "stops": [ { "id": "ChIJvRnquapZwokRdUOyVwNGbe8", "displayName": { "text": "6 Av/W 41 St", "languageCode": "en" }, "location": { "latitude": 40.754509, "longitude": -73.984216500000016 }, "wheelchairAccessibleEntrance": true } ], "departureBoards": [ { "displayType": "DIRECTION_CENTRIC", "rows": [ { "departures": [ { "timedDeparture": { "scheduledTime": "2026-05-15T22:29:51Z", "timingType": "SCHEDULED" }, "originallyScheduledStopId": "ChIJvRnquapZwokRdUOyVwNGbe8", "lineId": "ChIJA1aFyaZfwokRkO5869M6UXk" } ] }, { "departures": [ { "timedDeparture": { "scheduledTime": "2026-05-15T22:33:55Z", "timingType": "SCHEDULED" }, "originallyScheduledStopId": "ChIJvRnquapZwokRdUOyVwNGbe8", "lineId": "ChIJj3iCEwJfwokRZE2Qtnm4pPI" } ] }, ... ] } ] } }, ... { { "id": "ChIJPyq6TZBZwokRdGoiJ5Iq_hE", "vehicleType": "BUS", "displayName": { "text": "W 44 St - South Ferry", "languageCode": "en" }, "shortDisplayName": { "text": "M55", "languageCode": "en" }, "textColor": "#FFFFFF", "backgroundColor": "#1D59B3", "vehicleIcon": { "url": "https://maps.gstatic.com/mapfiles/transit/iw2/svg/bus2.svg" }, "alerts": [ { "effect": "OTHER", "texts": [ { "headline": { "text": "Information", "languageCode": "en" }, "summary": { "text": "Northbound M20 and M55 stop on State St at Bridge St is closed; use the temporary stop on State St before the intersection instead", "languageCode": "en" }, "fullDescription": { "text": "See a map of the new stop location. What's happening? Construction", "languageCode": "en" } } ], "detailsUrls": [ { "url": "https://www.mta.info/" } ], "cause": "OTHER_CAUSE", "startTime": "2025-04-02T04:00:00Z", "endTime": "2026-06-15T00:00:00Z", "attribution": { "link": { "text": "www.mta.info", "url": "https://www.mta.info/" } }, "createTime": "2026-05-15T22:32:00Z", "severityLevel": "INFO" } ] }, ... } ... }
دریافت ورودی‌ها و نقاط ناوبری
می‌توانید برای مقصد، ورودی‌ها و نقاط پیمایش درخواست کنید. ورودی‌ها نقاط ورود و خروج مکان را تعریف می‌کنند (برای مثال، دروازه‌های مختلف در فرودگاه یا مرکز خرید). نقاط ناوبری مکان‌های کنار جاده را که ناوبری باید در آن‌ها پایان یابد تعریف می‌کنند، که برای هدایت کاربران به سمت درست جاده یا نقطه پیاده‌سازی خاص مفید است.
نقطه‌های پیمایش 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 '{
"includedTypes": ["airport"],
"maxResultCount": 1,
"locationRestriction": {
"circle": {
"center": {"latitude": 37.6193, "longitude": -122.3816},
"radius": 1000.0
}
}
}' \
"https://places.googleapis.com/v1/places:searchNearby"
پاسخ شامل ورودی‌ها و نقاط پیمایش برای مکان است:
{ "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 api را در سمت چپ صفحه انتخاب کنید.
درصورت تمایل، پارامترهای درخواست را ویرایش کنید.
دکمه اجرا را انتخاب کنید. در کادر گفتگو، حسابی را که می‌خواهید برای درخواست استفاده شود انتخاب کنید.
در پانل «کاوشگر میاناهای برنامه‌سازی کاربردی»، نماد تمام‌صفحه تمام‌صفحه را برای ازهم بازکردن پنجره «کاوشگر میاناهای برنامه‌سازی کاربردی» انتخاب کنید.