یک درخواست Nearby Search (جدید) یک یا چند نوع مکان را می گیرد و فهرستی از مکان های منطبق را در منطقه مشخص شده برمی گرداند. یک ماسک فیلد که یک یا چند نوع داده را مشخص می کند مورد نیاز است. جستجوی نزدیک (جدید) فقط از درخواستهای POST پشتیبانی میکند.
API Explorer به شما امکان می دهد درخواست های زنده بنویسید تا بتوانید با API و گزینه های API آشنا شوید:
آن را امتحان کنید!نسخه ی نمایشی تعاملی را امتحان کنید تا نتایج جستجوی نزدیک (جدید) را که روی نقشه نمایش داده شده است ببینید.
درخواستهای جستجوی نزدیک (جدید).
یک درخواست Nearby Search (جدید) یک درخواست HTTP POST به یک URL به شکل زیر است:
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
پاسخهای جستجوی نزدیک (جدید).
Nearby Search (جدید) یک شی JSON را به عنوان پاسخ برمی گرداند. در پاسخ:
- آرایه
places
شامل همه مکان های منطبق است. - هر مکان در آرایه با یک شی
Place
نشان داده می شود. شیPlace
حاوی اطلاعات دقیق در مورد یک مکان است. - FieldMask ارسال شده در درخواست، فهرست فیلدهای بازگشتی در شیء
Place
را مشخص می کند.
شیء کامل JSON به شکل زیر است:
{ "places": [ { object (Place) } ] }
پارامترهای مورد نیاز
فیلد ماسک
با ایجاد یک ماسک فیلد پاسخ، لیست فیلدهایی را که باید در پاسخ بازگردانده شوند، مشخص کنید. ماسک فیلد پاسخ را با استفاده از پارامتر URL
$fields
یاfields
$ یا با استفاده از هدر HTTPX-Goog-FieldMask
به روش ارسال کنید. هیچ لیست پیش فرضی از فیلدهای برگشتی در پاسخ وجود ندارد. اگر فیلد ماسک را حذف کنید، متد یک خطا برمیگرداند.پوشاندن میدان یک روش طراحی خوب برای اطمینان از عدم درخواست دادههای غیرضروری است که به جلوگیری از زمان پردازش غیرضروری و هزینههای صورتحساب کمک میکند.
یک لیست جدا شده با کاما از انواع داده مکان برای بازگشت مشخص کنید. به عنوان مثال، برای بازیابی نام نمایشی و آدرس مکان.
X-Goog-FieldMask: places.displayName,places.formattedAddress
برای بازیابی تمام فیلدها از
*
استفاده کنید.X-Goog-FieldMask: *
یک یا چند مورد از فیلدهای زیر را مشخص کنید:
فیلدهای زیر SKU جستجوی نزدیک (پایه) را فعال میکنند:
places.accessibilityOptions
،places.addressComponents
،places.adrFormatAddress
،places.attributions
،places.businessStatus
،places.displayName
،places.formattedAddress
،places.googleMapsUri
،places.iconBackgroundColor
،places.iconMaskBaseUri
places.id
places.location
places.name
iconMaskBaseU، مکانها.places.name
* ,places.photos
,places.plusCode
,places.primaryType
,places.primaryTypeDisplayName
,places.shortFormattedAddress
,places.subDestinations
,places.types
,places.utcOffsetMinutes
,places.viewport
* فیلدplaces.name
حاوی نام منبع مکان به شکل است:places/ PLACE_ID
. برای دسترسی به نام متنی مکان، ازplaces.displayName
استفاده کنید.فیلدهای زیر SKU جستجوی نزدیک (پیشرفته) را فعال میکنند:
places.currentOpeningHours
places.priceLevel
places.nationalPhoneNumber
places.rating
places.currentSecondaryOpeningHours
places.internationalPhoneNumber
places.regularOpeningHours
places.regularSecondaryOpeningHours
places.userRatingCount
places.websiteUri
فیلدهای زیر SKU جستجوی نزدیک (ترجیح) را فعال میکنند:
places.allowsDogs
،places.curbsidePickup
places.delivery
،places.dineIn
places.menuForChildren
مکانها. غذا در،places.editorialSummary
خلاصه،places.evChargeOptions
.evChargeOptions،places.fuelOptions
.fuelOptions،places.goodForChildren
.goodForChildren،places.goodForGroups
.places.liveMusic
،places.goodForWatchingSports
places.parkingOptions
goodForWatchingSports.places.parkingOptions
,places.paymentOptions
,places.outdoorSeating
,places.reservable
,places.restroom
,places.reviews
,places.routingSummaries
, *places.servesBeer
places.servesDessert
places.servesBreakfast
,places.servesBrunch
,places.servesCocktails
,places.servesCoffee
. ,places.servesDinner
places.servesWine
places.servesLunch
,places.servesVegetarianFood
,places.takeout
* فقط جستجوی متن و جستجوی نزدیک
محدودیت مکان
منطقه مورد جستجو به عنوان یک دایره مشخص شده است که با نقطه مرکزی و شعاع بر حسب متر تعریف می شود. شعاع باید بین 0.0 تا 50000.0 باشد. شعاع پیش فرض 0.0 است. شما باید آن را در درخواست خود روی مقداری بیشتر از 0.0 تنظیم کنید.
به عنوان مثال:
"locationRestriction": { "circle": { "center": { "latitude": 37.7937, "longitude": -122.3965 }, "radius": 500.0 } }
پارامترهای اختیاری
includeTypes/excludedTypes، includePrimaryTypes/excludedPrimaryTypes
به شما امکان می دهد لیستی از انواع از انواع جدول A که برای فیلتر کردن نتایج جستجو استفاده می شود را مشخص کنید. حداکثر 50 نوع را می توان در هر دسته بندی محدودیت نوع مشخص کرد.
یک مکان فقط می تواند یک نوع اصلی از انواع جدول A مرتبط با آن داشته باشد. برای مثال، نوع اولیه ممکن است
"mexican_restaurant"
یا"steak_house"
باشد. ازincludedPrimaryTypes
وexcludedPrimaryTypes
برای فیلتر کردن نتایج در نوع اصلی مکان استفاده کنید.یک مکان همچنین میتواند چندین مقدار نوع از انواع جدول A مرتبط با آن داشته باشد. به عنوان مثال، یک رستوران ممکن است انواع زیر را داشته باشد:
"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"
عمل نمیکنند.شامل انواع
یک لیست جدا شده با کاما از مکان هایی که از جدول A برای جستجو استفاده می شود. اگر این پارامتر حذف شود، مکان های همه نوع برگردانده می شوند.
excludedTypes
فهرستی از انواع مکان جدا شده با کاما از جدول A برای حذف از جستجو.
اگر هر دو
includedTypes
(مانند"school"
) وexcludedTypes
(مانند"primary_school"
) را در درخواست مشخص کنید، پاسخ شامل مکان هایی است که به عنوان"school"
طبقه بندی می شوند اما نه به عنوان"primary_school"
. پاسخ شامل مکانهایی است که حداقل با یکی ازincludedTypes
و هیچ یک ازexcludedTypes
مطابقت ندارند.اگر انواع متضاد وجود داشته باشد، مانند نوعی که در هر دو
includedTypes
وexcludedTypes
ظاهر می شود، یک خطایINVALID_REQUEST
برگردانده می شود.شامل PrimaryTypes
فهرستی از انواع مکان های اصلی جدا شده با کاما از جدول A برای گنجاندن در جستجو.
excludedPrimaryTypes
فهرستی از انواع مکان های اصلی جدا شده با کاما از جدول A برای حذف از جستجو.
اگر انواع اصلی متناقض وجود داشته باشد، مانند نوعی که هم در
includedPrimaryTypes
و همexcludedPrimaryTypes
ظاهر می شود، یک خطایINVALID_ARGUMENT
برگردانده می شود.کد زبان
زبانی که در آن نتایج را برگرداند.
- لیست زبان های پشتیبانی شده را ببینید. Google اغلب زبان های پشتیبانی شده را به روز می کند، بنابراین این فهرست ممکن است جامع نباشد.
- اگر
languageCode
ارائه نشده باشد، API پیشفرضen
را انتخاب میکند. اگر کد زبان نامعتبر را مشخص کنید، API یک خطایINVALID_ARGUMENT
برمیگرداند. - API تمام تلاش خود را می کند تا آدرس خیابانی را ارائه دهد که هم برای کاربر و هم برای افراد محلی قابل خواندن باشد. برای دستیابی به این هدف، آدرسهای خیابان را به زبان محلی برمیگرداند و به اسکریپتی که در صورت لزوم توسط کاربر قابل خواندن است، با رعایت زبان ترجیحی، ترجمه میشود. همه آدرس های دیگر به زبان ترجیحی برگردانده می شوند. اجزای آدرس همه به یک زبان بازگردانده می شوند که از جزء اول انتخاب شده است.
- اگر نامی در زبان ترجیحی موجود نباشد، API از نزدیکترین تطابق استفاده می کند.
- زبان ترجیحی تأثیر کمی بر مجموعه نتایجی که API برای برگرداندن آنها انتخاب میکند و ترتیب بازگرداندن آنها دارد. geocoder بسته به زبان، اختصارات را متفاوت تفسیر می کند، مانند اختصارات انواع خیابان، یا مترادف هایی که ممکن است در یک زبان معتبر باشند اما در زبان دیگر معتبر نیستند.
maxResultCount
حداکثر تعداد نتایج مکان برای بازگشت را مشخص می کند. باید بین 1 تا 20 (پیشفرض) باشد.
رتبه اولویت
نوع رتبه بندی مورد استفاده اگر این پارامتر حذف شود، نتایج بر اساس محبوبیت رتبه بندی می شوند. ممکن است یکی از موارد زیر باشد:
-
POPULARITY
(پیش فرض) نتایج را بر اساس محبوبیت آنها مرتب می کند. -
DISTANCE
مرتبسازی به ترتیب صعودی بر اساس فاصله آنها از مکان مشخص شده نتیجه میدهد.
-
منطقه کد
کد منطقه ای که برای قالب بندی پاسخ استفاده می شود، به عنوان مقدار کد CLDR دو کاراکتری مشخص شده است. هیچ مقدار پیش فرض وجود ندارد.
اگر نام کشور قسمت
formattedAddress
در پاسخ باregionCode
مطابقت داشته باشد، کد کشور ازformattedAddress
حذف میشود. این پارامتر رویadrFormatAddress
، که همیشه شامل نام کشور است، یاshortFormattedAddress
که هرگز شامل آن نمیشود، تأثیری ندارد.اکثر کدهای CLDR با کدهای ISO 3166-1 یکسان هستند، با برخی استثناهای قابل توجه. برای مثال، ccTLD بریتانیا "uk" (.co.uk) است در حالی که کد ISO 3166-1 آن "gb" است (از لحاظ فنی برای نهاد "پادشاهی متحده بریتانیای کبیر و ایرلند شمالی"). این پارامتر می تواند بر نتایج بر اساس قانون قابل اجرا تأثیر بگذارد.
نمونههای جستجوی نزدیک (جدید).
مکان های یک نوع را پیدا کنید
مثال زیر یک درخواست Nearby Search (جدید) برای نامهای نمایشی همه رستورانها در شعاع 500 متری را نشان میدهد که با 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" } }, ... }
مکان هایی با انواع مختلف پیدا کنید
مثال زیر یک درخواست Nearby Search (جدید) را برای نامهای نمایشی همه فروشگاههای رفاه و مشروبفروشیها در شعاع 1000 متری 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
آن را امتحان کنید!
API Explorer به شما امکان می دهد درخواست های نمونه بنویسید تا بتوانید با API و گزینه های API آشنا شوید.
- نماد API را انتخاب کنید، ، در سمت راست صفحه.
- به صورت اختیاری نمایش پارامترهای استاندارد را گسترش دهید و پارامتر
fields
را روی فیلد ماسک تنظیم کنید. - به صورت اختیاری بدنه درخواست را ویرایش کنید.
- دکمه Execute را انتخاب کنید. در پنجره پاپ آپ، حسابی را که می خواهید برای درخواست استفاده کنید، انتخاب کنید.
در پانل API Explorer، نماد گسترش را انتخاب کنید، ، برای گسترش پنجره API Explorer.