جستجوی اطراف (جدید)

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

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

درخواست‌های «جستجوی اطراف» (جدید)

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

هدف 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();
    });

پاسخ‌های «جستجوی اطراف» (جدید)

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

پارامترهای الزامی

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

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

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

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

  • فیلدهای زیر جستجوی اطراف حرفه‌ای واحد نگهداری موجودی را راه‌اندازی می‌کنند:

    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

    برای فهرست کامل فیلدها و «واحد نگهداری کالا» مرتبط با آن‌ها، فیلدهای داده مکان (جدید) را ببینید.

  • فیلدهای زیر باعث راه‌اندازی جستجوی مکان‌های اطراف 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

    برای مشاهده فهرست کامل فیلدها و SKUهای مرتبط با آن‌ها، به فیلدهای داده مکان (جدید) مراجعه کنید.

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

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

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

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

• انواع و انواع اصلی

  به شما امکان می‌دهد فهرستی از انواع را از انواع جدول 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 = Arrays.asList("restaurant") و excludedPrimaryTypes = Arrays.asList("steak_house") را مشخص کنید، مکان‌های برگردانده‌شده خدمات مرتبط با "restaurant" را ارائه می‌دهند اما در درجه اول به‌عنوان "steak_house" فعالیت نمی‌کنند.

  برای مشاهده نمونه‌ای از نحوه استفاده از includedTypes و excludedTypes، درخواست‌های «جستجوی مکان‌های اطراف (جدید)» را ببینید.

  نوع‌های گنجانده‌شده

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

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

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

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

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

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

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

  نوع‌های اصلی لحاظ‌شده

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

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

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