این صفحه به‌وسیله ‏Cloud Translation API‏ ترجمه شده است.

جستجوی نزدیک (جدید)

پلتفرم را انتخاب کنید: سرویس وب جاوا اسکریپت اندروید iOS

یک درخواست Nearby Search (جدید) منطقه ای را برای جستجو مشخص شده به عنوان یک دایره، که با مختصات طول و عرض جغرافیایی نقطه مرکزی دایره و شعاع بر حسب متر تعریف شده است، به عنوان ورودی می گیرد. درخواست فهرستی از مکان‌های منطبق را برمی‌گرداند که هر کدام با یک شی Place در ناحیه جستجوی مشخص شده نمایش داده می‌شوند.

به طور پیش‌فرض، پاسخ حاوی مکان‌هایی از همه نوع در ناحیه جستجو است. می‌توانید به‌صورت اختیاری پاسخ را با تعیین فهرستی از انواع مکان‌ها فیلتر کنید تا صریحاً در پاسخ قرار داده یا از آن حذف کنید. برای مثال، می‌توانید مشخص کنید که فقط مکان‌هایی در پاسخ گنجانده شود که از نوع «رستوران»، «نان‌پزی» و «کافه» هستند یا همه مکان‌های نوع «مدرسه» را حذف کنید.

درخواست‌های جستجوی نزدیک (جدید).

با فراخوانی PlacesClient.searchNearby و ارسال یک شی SearchNearbyRequest که پارامترهای درخواست را تعریف می کند، یک درخواست Nearby Search (جدید) ایجاد کنید.

شی SearchNearbyRequest تمام پارامترهای مورد نیاز و اختیاری را برای درخواست مشخص می کند. پارامترهای مورد نیاز عبارتند از:

لیست فیلدهایی که باید در شیء Place برگردند که به عنوان فیلد ماسک نیز شناخته می شود. اگر حداقل یک فیلد را در لیست فیلد مشخص نکنید، یا اگر لیست فیلد را حذف کنید، تماس یک خطا برمی‌گرداند.
محدودیت مکان برای منطقه جستجو، به عنوان یک جفت طول و عرض جغرافیایی و مقدار شعاع، بر حسب متر تعریف شده است.

این مثال درخواست جستجوی نزدیک مشخص می کند که اشیاء Place پاسخ حاوی فیلدهای مکان Place.Field.ID و Place.Field.DISPLAY_NAME برای هر شیء Place در نتایج جستجو هستند. همچنین پاسخ را فقط به مکان‌های برگشتی از نوع «رستوران» و «کافه» فیلتر می‌کند، اما مکان‌های نوع «پیتزا_رستوران» و «رستوران_آمریکایی» را حذف می‌کند.

// Define a list of fields to include in the response for each returned place.
final List<Place.Field> placeFields = Arrays.asList(Place.Field.ID, Place.Field.DISPLAY_NAME);

// Define the search area as a 1000 meter diameter circle in New York, NY.
LatLng center = new LatLng(40.7580, -73.9855);
CircularBounds circle = CircularBounds.newInstance(center, /* radius = */ 1000);

// Define a list of types to include.
final List<String> includedTypes = Arrays.asList("restaurant", "cafe");
// Define a list of types to exclude.
final List<String> excludedTypes = Arrays.asList("pizza_restaurant", "american_restaurant");

// Use the builder to create a SearchNearbyRequest object.
final SearchNearbyRequest searchNearbyRequest =
SearchNearbyRequest.builder(/* location restriction = */ circle, placeFields)
    .setIncludedTypes(includedTypes)
    .setExcludedTypes(excludedTypes)
    .setMaxResultCount(10)
    .build());

// Call placesClient.searchNearby() to perform the search.
// Define a response handler to process the returned List of Place objects.
placesClient.searchNearby(searchNearbyRequest)
    .addOnSuccessListener(response -> {
      List<Place> places = response.getPlaces();
    });

توجه: برای اطلاعات بیشتر در مورد مقداردهی اولیه PlacesClient ، به Initialize the Places API Client مراجعه کنید.

پاسخ‌های جستجوی نزدیک (جدید).

کلاس SearchNearbyResponse پاسخ یک درخواست جستجو را نشان می دهد. یک شی SearchNearbyResponse شامل:

فهرستی از اشیاء Place که همه مکان‌های منطبق را نشان می‌دهند، با یک شی Place در هر مکان منطبق.
هر شی Place فقط شامل فیلدهایی است که توسط لیست فیلد ارسال شده در درخواست تعریف شده است.

به عنوان مثال، در درخواست شما یک لیست فیلد را به صورت زیر تعریف کرده اید:

// Define a list of fields to include in the response for each returned place.
final List<Place.Field> placeFields = Arrays.asList(Place.Field.ID, Place.Field.NAME);

این لیست فیلد به این معنی است که هر شیء Place در پاسخ فقط شامل شناسه مکان و نام هر مکان منطبق است. سپس می توانید از متدهای Place.getId() و Place.getName() برای دسترسی به این فیلدها در هر شیء Place استفاده کنید.

برای مثال‌های بیشتر از دسترسی به داده‌ها در یک شی Place ، به فیلدهای داده شیء Access Place مراجعه کنید.

پارامترهای مورد نیاز

از شی SearchNearbyRequest برای تعیین پارامترهای مورد نیاز برای جستجو استفاده کنید.

لیست زمینه
وقتی جزئیات مکان را درخواست می‌کنید، باید داده‌هایی را که باید در شیء Place برای مکان به‌عنوان یک فیلد ماسک برگردانده شوند، مشخص کنید. برای تعریف فیلد ماسک، آرایه ای از مقادیر را از Place.Field به شی SearchNearbyRequest ارسال کنید. پوشاندن میدان یک روش طراحی خوب برای اطمینان از عدم درخواست داده‌های غیرضروری است که به جلوگیری از زمان پردازش غیرضروری و هزینه‌های صورت‌حساب کمک می‌کند.
یک یا چند مورد از فیلدهای زیر را مشخص کنید:
- فیلدهای زیر Nearby Search Pro SKU را فعال می‌کنند:
  Place.Field.ADDRESS_COMPONENTS
  Place.Field.BUSINESS_STATUS
  Place.Field.ADDRESS
  Place.Field.ICON_BACKGROUND_COLOR
  Place.Field.ICON_URL
  Place.Field.LAT_LNG
  Place.Field.PHOTO_METADATAS
  Place.Field.PLUS_CODE
  Place.Field.PRIMARY_TYPE
  Place.Field.PRIMARY_TYPE_DISPLAY_NAME
  Place.Field.ID
  Place.Field.NAME
  Place.Field.TYPES
  Place.Field.UTC_OFFSET
  Place.Field.VIEWPORT
  Place.Field.WHEELCHAIR_ACCESSIBLE_ENTRANCE
- فیلدهای زیر Nearby Search Enterprise SKU را فعال می کنند:
  Place.Field.CURRENT_OPENING_HOURS
  Place.Field.CURRENT_SECONDARY_OPENING_HOURS
  Place.Field.INTERNATIONAL_PHONE_NUMBER
  Place.Field.NATIONAL_PHONE_NUMBER
  Place.Field.OPENING_HOURS
  Place.Field.PRICE_LEVEL
  Place.Field.RATING
  Place.Field.SECONDARY_OPENING_HOURS
  Place.Field.USER_RATING_COUNT
  Place.Field.WEBSITE_URI
  فیلدهای منسوخ شده: فیلدهای Place.Field.PHONE_NUMBER و Place.Field.USER_RATINGS_TOTAL در نسخه 4.0 Places SDK برای Android منسوخ شدند. در عوض، به ترتیب از Place.Field.INTERNATIONAL_PHONE_NUMBER و Place.USER_RATING_COUNT استفاده کنید.
- فیلدهای زیر Nearby Search Enterprise Plus SKU را فعال می کنند:
  Place.Field.ALLOWS_DOGS
  Place.Field.CURBSIDE_PICKUP
  Place.Field.DELIVERY
  Place.Field.DINE_IN
  Place.Field.EDITORIAL_SUMMARY
  Place.Field.EV_CHARGE_OPTIONS
  Place.Field.FUEL_OPTIONS
  Place.Field.GOOD_FOR_CHILDREN
  Place.Field.GOOD_FOR_GROUPS
  Place.Field.GOOD_FOR_WATCHING_SPORTS
  Place.Field.LIVE_MUSIC
  Place.Field.MENU_FOR_CHILDREN
  Place.Field.OUTDOOR_SEATING
  Place.Field.PARKING_OPTIONS
  Place.Field.PAYMENT_OPTIONS
  Place.Field.RESERVABLE
  Place.Field.RESTROOM
  Place.Field.REVIEWS
  Place.Field.SERVES_BEER
  Place.Field.SERVES_BREAKFAST
  Place.Field.SERVES_BRUNCH
  Place.Field.SERVES_COCKTAILS
  Place.Field.SERVES_COFFEE
  Place.Field.SERVES_DESSERT
  Place.Field.SERVES_DINNER
  Place.Field.SERVES_LUNCH
  Place.Field.SERVES_VEGETARIAN_FOOD
  Place.Field.SERVES_WINE
  Place.Field.TAKEOUT
توجه: نسخه 4.0 Places SDK برای اندروید منسوخ شدن چندین فیلد داده Place و افزودن فیلدهای جدید را معرفی کرد. برای اطلاعات بیشتر، به انتقال به فیلدهای داده مکان جدید در Places SDK برای Android نسخه 4.0 مراجعه کنید.
برای تنظیم پارامتر لیست فیلد، هنگام ساختن شی SearchNearbyRequest ، متد setPlaceFields() را فراخوانی کنید.
مثال زیر فهرستی از دو مقدار فیلد را تعریف می کند تا مشخص کند که شی Place که توسط یک درخواست بازگردانده می شود شامل فیلدهای Place.Field.ID و Place.Field.DISPLAY_NAME باشد:

// Define a list of fields to include in the response for each returned place.
final List<Place.Field> placeFields = Arrays.asList(Place.Field.ID, Place.Field.DISPLAY_NAME);

محدودیت مکان
یک شی LocationRestriction که منطقه مورد جستجو را به عنوان یک دایره مشخص می کند، که با نقطه مرکزی و شعاع بر حسب متر تعریف می شود. شعاع باید بین بزرگتر از 0.0 و کمتر یا مساوی 50000.0 باشد، به خاطر داشته باشید که تعیین شعاع بسیار کوچک ZERO_RESULTS به عنوان پاسخ برمی گرداند.
برای تنظیم پارامتر محدودیت مکان، هنگام ساخت شی SearchNearbyRequest ، متد setLocationRestriction() را فراخوانی کنید.

پارامترهای اختیاری

از شی SearchNearbyRequest برای تعیین پارامترهای اختیاری برای جستجو استفاده کنید.

انواع و انواع اولیه
به شما امکان می دهد لیستی از انواع از انواع جدول A که برای فیلتر کردن نتایج جستجو استفاده می شود را مشخص کنید. حداکثر 50 نوع را می توان در هر دسته بندی محدودیت نوع مشخص کرد.
توجه: مقادیر جدول B فقط در پاسخ بازگردانده می شوند. شما نمی توانید از مقادیر جدول B به عنوان فیلتر استفاده کنید.
یک مکان فقط می تواند یک نوع اصلی از انواع جدول 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 = Arrays.asList("restaurant") و excludedPrimaryTypes = Arrays.asList("steak_house") را مشخص کنید، مکان های برگشتی خدمات مربوط به "restaurant" را ارائه می دهند اما در اصل به عنوان "steak_house" عمل نمی کنند.
اگر includedTypes ، excludedTypes ، includedPrimaryTypes ، و excludedPrimaryTypes را از درخواست حذف کنید، جستجو مکان‌ها را برای همه انواع از داخل محدوده محدودیت مکان برمی‌گرداند.
برای مثالی از نحوه استفاده از includedTypes و excludedTypes ، به درخواست‌های Nearby Search (جدید) مراجعه کنید.
انواع شامل
فهرستی از انواع مکان ها از جدول A برای جستجو. اگر این پارامتر حذف شود، مکان های همه نوع برگردانده می شوند.
برای تنظیم پارامتر انواع موجود، هنگام ساخت شی SearchNearbyRequest ، متد setIncludedTypes() را فراخوانی کنید.
انواع مستثنی شده
فهرستی از انواع مکان از جدول A برای حذف از جستجو.
اگر هر دو includedTypes (مانند "school" ) و excludedTypes (مانند "primary_school" ) را در درخواست مشخص کنید، پاسخ شامل مکان هایی است که به عنوان "school" طبقه بندی می شوند اما نه به عنوان "primary_school" . پاسخ شامل مکان‌هایی است که حداقل با یکی از includedTypes و هیچ یک از excludedTypes مطابقت ندارند.
اگر انواع متضاد وجود داشته باشد، مانند نوعی که در هر دو نوع includedTypes و excludedTypes ظاهر می شود، یک خطای INVALID_REQUEST برگردانده می شود.
برای تنظیم پارامتر انواع excluded، هنگام ساخت شی SearchNearbyRequest ، متد setExcludedTypes() را فراخوانی کنید.
شامل انواع اولیه
فهرستی از انواع مکان های اصلی از جدول A برای گنجاندن در جستجو.
برای تنظیم پارامتر انواع اولیه شامل، متد setIncludedPrimaryTypes() را هنگام ساختن شی SearchNearbyRequest فراخوانی کنید.
انواع اولیه مستثنی شده است
فهرستی از انواع مکان های اصلی از جدول A برای حذف از جستجو.
اگر انواع اصلی متناقض وجود داشته باشد، مانند نوعی که هم در includedPrimaryTypes و excludedPrimaryTypes ظاهر می شود، یک خطای INVALID_ARGUMENT برگردانده می شود.
برای تنظیم پارامتر انواع اولیه حذف شده، هنگام ساختن شی SearchNearbyRequest ، متد setExcludedPrimaryTypes() را فراخوانی کنید.
حداکثر تعداد نتایج
حداکثر تعداد نتایج مکان برای بازگشت را مشخص می کند. باید بین 1 تا 20 (پیش‌فرض) باشد.
برای تنظیم حداکثر پارامتر تعداد نتیجه، هنگام ساخت شی SearchNearbyRequest ، متد setMaxResultCount() را فراخوانی کنید.
اولویت رتبه
نوع رتبه بندی مورد استفاده اگر این پارامتر حذف شود، نتایج بر اساس محبوبیت رتبه بندی می شوند. ممکن است یکی از موارد زیر باشد:
- POPULARITY (پیش فرض) نتایج را بر اساس محبوبیت آنها مرتب می کند.
- DISTANCE مرتب‌سازی به ترتیب صعودی بر اساس فاصله آنها از مکان مشخص شده نتیجه می‌دهد.
برای تنظیم پارامتر اولویت رتبه، هنگام ساخت شی SearchNearbyRequest ، متد setRankPreference() را فراخوانی کنید.
کد منطقه
کد منطقه ای که برای قالب بندی پاسخ استفاده می شود، به عنوان مقدار کد CLDR دو کاراکتری مشخص شده است. هیچ مقدار پیش فرض وجود ندارد.
اگر نام کشور فیلد FORMATTED_ADDRESS در پاسخ با regionCode مطابقت داشته باشد، کد کشور از FORMATTED_ADDRESS حذف می شود.
اکثر کدهای CLDR با کدهای ISO 3166-1 یکسان هستند، با برخی استثناهای قابل توجه. برای مثال، ccTLD بریتانیا "uk" (.co.uk) است در حالی که کد ISO 3166-1 آن "gb" است (از لحاظ فنی برای نهاد "پادشاهی متحده بریتانیای کبیر و ایرلند شمالی"). این پارامتر می تواند بر نتایج بر اساس قانون قابل اجرا تأثیر بگذارد.
برای تنظیم پارامتر کد منطقه، هنگام ساخت شی SearchNearbyRequest ، متد setRegionCode() را فراخوانی کنید.

اسناد را در برنامه خود نمایش دهید

هنگامی که برنامه شما اطلاعات به دست آمده از PlacesClient را نمایش می دهد، مانند عکس ها و نظرات، برنامه باید اسناد مورد نیاز را نیز نمایش دهد.

برای اطلاعات بیشتر، به سیاست‌های مربوط به مکان‌ها SDK برای Android مراجعه کنید.

جستجوی نزدیک (جدید)

درخواست‌های جستجوی نزدیک (جدید).

پاسخ‌های جستجوی نزدیک (جدید).

پارامترهای مورد نیاز

لیست زمینه

محدودیت مکان

پارامترهای اختیاری

انواع و انواع اولیه

انواع شامل

انواع مستثنی شده

شامل انواع اولیه

انواع اولیه مستثنی شده است

حداکثر تعداد نتایج

اولویت رتبه

کد منطقه

اسناد را در برنامه خود نمایش دهید