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

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

توسعه‌دهندگان منطقه اقتصادی اروپا (EEA)

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

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

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

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

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

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

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

// 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();
    });

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

کلاس 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 ، به بخش دسترسی به فیلدهای داده شیء Place مراجعه کنید.

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

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

  • فهرست فیلدها

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

    یک یا چند مورد از فیلدهای زیر را مشخص کنید:

    • فیلدهای زیر SKU مربوط به Nearby Search Pro را فعال می‌کنند:

      Place.Field.ADDRESS_COMPONENTS
      Place.Field.BUSINESS_STATUS
      Place.Field.ADDRESS
      Place.Field.DISPLAY_NAME >*
      * به جای Place.Field.NAME که منسوخ شده است، استفاده کنید.
      Place.Field.ICON_BACKGROUND_COLOR
      Place.Field.ICON_MASK_URL *
      * به جای Place.Field.ICON_URL که منسوخ شده است، استفاده کنید.
      Place.Field.ID
      Place.Field.LAT_LNG
      Place.Field.PHOTO_METADATAS
      Place.Field.PLUS_CODE
      Place.Field.PRIMARY_TYPE
      Place.Field.PRIMARY_TYPE_DISPLAY_NAME
      Place.Field.RESOURCE_NAME
      Place.Field.TYPES
      Place.Field.UTC_OFFSET
      Place.Field.VIEWPORT
      Place.Field.WHEELCHAIR_ACCESSIBLE_ENTRANCE

    • فیلدهای زیر SKU جستجوی نزدیک سازمانی را فعال می‌کنند:

      Place.Field.CURRENT_OPENING_HOURS
      Place.Field.CURRENT_SECONDARY_OPENING_HOURS
      Place.Field.INTERNATIONAL_PHONE_NUMBER *
      * به جای Place.Field.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.USER_RATINGS_TOTAL که منسوخ شده است، استفاده کنید.
      Place.Field.WEBSITE_URI

    • فیلدهای زیر، SKU مربوط به Nearby Search Enterprise Plus را فعال می‌کنند:

      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

    برای تنظیم پارامتر لیست فیلد، هنگام ساخت شیء 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 که برای فیلتر کردن نتایج جستجو استفاده می‌شوند، مشخص کنید. حداکثر ۵۰ نوع را می‌توان در هر دسته محدودیت نوع مشخص کرد.

    یک مکان فقط می‌تواند یک نوع اصلی از انواع جدول 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 ، به درخواست‌های Nearby Search (New) مراجعه کنید.

    انواع شامل

    فهرستی از انواع مکان‌ها از جدول A برای جستجو. اگر این پارامتر حذف شود، مکان‌هایی از همه نوع بازگردانده می‌شوند.

    برای تنظیم پارامتر انواع شامل شده، هنگام ساخت شیء SearchNearbyRequest متد setIncludedTypes() را فراخوانی کنید.

    انواع مستثنی

    فهرستی از انواع مکان‌ها از جدول A برای حذف از جستجو.

    اگر هم includedTypes (مانند "school" ) و هم نوع‌های excludedTypes (مانند "primary_school" ) را در درخواست مشخص کنید، پاسخ شامل مکان‌هایی می‌شود که به عنوان "school" طبقه‌بندی شده‌اند اما به عنوان "primary_school" طبقه‌بندی نشده‌اند. پاسخ شامل مکان‌هایی است که حداقل با یکی از includedTypes مطابقت دارند و هیچ‌کدام از excludedTypes نمی‌شوند.

    اگر انواع متناقضی وجود داشته باشد، مانند نوعی که هم در includedTypes و هم excludedTypes ظاهر می‌شود، خطای INVALID_REQUEST برگردانده می‌شود.

    برای تنظیم پارامتر انواع مستثنی، هنگام ساخت شیء SearchNearbyRequest ، متد setExcludedTypes() را فراخوانی کنید.

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

    فهرستی از انواع مکان‌های اصلی از جدول A برای گنجاندن در جستجو.

    برای تنظیم پارامتر انواع اصلیِ شامل‌شده، هنگام ساخت شیء SearchNearbyRequest متد setIncludedPrimaryTypes() را فراخوانی کنید.

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

    فهرستی از انواع مکان‌های اصلی از جدول A برای حذف از جستجو.

    اگر انواع اصلی متناقضی وجود داشته باشد، مانند نوعی که هم در includedPrimaryTypes و هم excludedPrimaryTypes ظاهر می‌شود، خطای INVALID_ARGUMENT برگردانده می‌شود.

    برای تنظیم پارامتر انواع اصلی مستثنی شده، هنگام ساخت شیء SearchNearbyRequest متد setExcludedPrimaryTypes() را فراخوانی کنید.

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

    حداکثر تعداد نتایج مکانی را که باید برگردانده شود، مشخص می‌کند. باید بین ۱ تا ۲۰ (پیش‌فرض) باشد.

    برای تنظیم پارامتر حداکثر تعداد نتایج، هنگام ساخت شیء 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 ، مانند عکس‌ها و نظرات را نمایش می‌دهد، باید ویژگی‌های مورد نیاز را نیز نمایش دهد.

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