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

انتخاب پلاتفرم: Android iOS JavaScript خدمات وب
توسعه‌دهندگان منطقه اقتصادی اروپا (EEA)

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

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

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

با فراخوانی GMSPlacesClient searchNearbyWithRequest:، درخواست «جستجوی مکان‌های اطراف» ایجاد کنید، شیء GMSPlaceSearchNearbyRequest را که پارامترهای درخواست را تعریف می‌کند و روش فراخوانی برگشتی از نوع GMSPlaceSearchNearbyResultCallback را برای مدیریت پاسخ ارسال کنید.

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

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

این نمونه درخواست جستجوی مکان‌های اطراف مشخص می‌کند که اشیای GMSPlace پاسخ حاوی نام مکان (GMSPlacePropertyName) و مختصات مکان (GMSPlacePropertyCoordinate) برای هر شیء GMSPlace در نتایج جستجو است. همچنین پاسخ را فیلتر می‌کند تا فقط مکان‌های نوع «رستوران» و «کافه» را برگرداند.

کیت توسعه نرم‌افزار Swift مکان‌ها

let restriction = CircularCoordinateRegion(center: CLLocationCoordinate2DMake(37.7937, -122.3965), radius: 500)
let searchNearbyRequest = SearchNearbyRequest(
  locationRestriction: restriction,
  placeProperties: [ .name, .coordinate],
  includedTypes: [ .restaurant, .cafe ],
)
switch await placesClient.searchNearby(with: searchNearbyRequest) {
case .success(let places):
  // Handle places
case .failure(let placesError):
  // Handle error
}

Swift

// Array to hold the places in the response
var placeResults: [GMSPlace] = []

// Define the search area as a 500 meter diameter circle in San Francisco, CA.
let circularLocationRestriction = GMSPlaceCircularLocationOption(CLLocationCoordinate2DMake(37.7937, -122.3965), 500)

// Specify the fields to return in the GMSPlace object for each place in the response.
let placeProperties = [GMSPlaceProperty.name, GMSPlaceProperty.coordinate].map {$0.rawValue}

// Create the GMSPlaceSearchNearbyRequest, specifying the search area and GMSPlace fields to return.
var request = GMSPlaceSearchNearbyRequest(locationRestriction: circularLocationRestriction, placeProperties: placeProperties)
let includedTypes = ["restaurant", "cafe"]
request.includedTypes = includedTypes

let callback: GMSPlaceSearchNearbyResultCallback = { [weak self] results, error in
  guard let self, error == nil else {
    if let error {
      print(error.localizedDescription)
    }
    return
  }
  guard let results = results as? [GMSPlace] else {
    return
  }
  placeResults = results
}

GMSPlacesClient.shared().searchNearby(with: request, callback: callback)

آبجکتیو-سی

// Array to hold the places in the response
_placeResults = [NSArray array];

// Define the search area as a 500 meter diameter circle in San Francisco, CA.
id<GMSPlaceLocationRestriction> circularLocation = GMSPlaceCircularLocationOption(CLLocationCoordinate2DMake(37.7937, -122.3965), 500);

// Create the GMSPlaceSearchNearbyRequest, specifying the search area and GMSPlace fields to return.
GMSPlaceSearchNearbyRequest *request = [[GMSPlaceSearchNearbyRequest alloc]
  initWithLocationRestriction:circularLocation
              placeProperties:@[ GMSPlacePropertyName, GMSPlacePropertyCoordinate ]];

// Set the place types to filter on.
NSArray<NSString *> *includedTypes = @[ @"restaurant", @"cafe" ];
request.includedTypes = [[NSMutableArray alloc] initWithArray:includedTypes];

[_placesClient searchNearbyWithRequest:request
  callback:^(NSArray<GMSPlace *> *_Nullable places, NSError *_Nullable error) {
    if (error != nil) {
      NSLog(@"An error occurred %@", [error localizedDescription]);
      return;
    } else {
        // Get list of places.
        _placeResults = places;
    }
  }
];

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

«میانای برنامه‌سازی کاربردی جستجوی اطراف» آرایه‌ای از موارد منطبق را در قالب GMSPlace اشیا برمی‌گرداند، با یک شیء GMSPlace برای هر مکان منطبق.

دریافت وضعیت باز

شیء GMSPlacesClient حاوی تابع عضوی به‌نام isOpenWithRequest (isOpenRequest در Swift و isPlaceOpenRequest در GooglePlacesSwift) است که براساس زمان مشخص‌شده در تماس، پاسخی را برمی‌گرداند که نشان می‌دهد مکان درحال‌حاضر باز است یا نه.

این روش یک آرگومان واحد از نوع GMSPlaceIsOpenWithRequest می‌گیرد که شامل موارد زیر است:

  • یک GMSPlace شیء، یا رشته‌ای که شناسه مکان را مشخص می‌کند. برای اطلاعات بیشتر درباره ایجاد شیء «مکان» با فیلدهای لازم، جزئیات مکان را ببینید.
  • یک شیء اختیاری NSDate (Obj-C) یا Date (Swift) که زمان موردنظر برای بررسی را مشخص می‌کند. اگر زمانی مشخص نشود، پیش‌فرض اکنون است.
  • روش GMSPlaceOpenStatusResponseCallback برای مدیریت پاسخ.
    • >

روش GMSPlaceIsOpenWithRequest مستلزم است که فیلدهای زیر در شیء GMSPlace تنظیم شود:

  • GMSPlacePropertyUTCOffsetMinutes
  • GMSPlacePropertyBusinessStatus
  • GMSPlacePropertyOpeningHours
  • GMSPlacePropertyCurrentOpeningHours
  • GMSPlacePropertySecondaryOpeningHours

اگر این فیلدها در شیء «مکان» ارائه نشده باشند، یا اگر شناسه مکان را ارسال کنید، این روش از GMSPlacesClient GMSFetchPlaceRequest: برای واکشی آن‌ها استفاده می‌کند.

پاسخ isOpenWithRequest

‫isOpenWithRequest یک شیء GMSPlaceIsOpenResponse برمی‌گرداند که حاوی مقدار بولی به‌نام status است که نشان می‌دهد کسب‌وکار باز است، بسته است، یا وضعیت آن نامشخص است.

زبان مقدار درصورت باز بودن مقدار درصورت بسته بودن مقدار درصورت نامشخص بودن وضعیت
Places Swift true false nil
Swift .open .closed .unknown
آبجکتیو-سی GMSPlaceOpenStatusOpen GMSPlaceOpenStatusClosed GMSPlaceOpenStatusUnknown

صدور صورت‌حساب برای isOpenWithRequest

مثال: درخواست GMSPlaceIsOpenWithRequest بده

مثال زیر نحوه مقداردهی اولیه GMSPlaceIsOpenWithRequest را در شیء GMSPlace موجود نشان می‌دهد.

کیت توسعه نرم‌افزار Swift مکان‌ها

        let isOpenRequest = IsPlaceOpenRequest(place: place)
        switch await placesClient.isPlaceOpen(with: isOpenRequest) {
          case .success(let isOpenResponse):
            switch isOpenResponse.status {
              case true:
                // Handle open
              case false:
                // Handle closed
              case nil:
                // Handle unknown
          case .failure(let placesError):
            // Handle error
        }

Swift

    let isOpenRequest = GMSPlaceIsOpenRequest(place: place, date: nil)
      GMSPlacesClient.shared().isOpen(with: isOpenRequest) { response, error in
        if let error = error {
          // Handle Error
        }
        switch response.status {
          case .open:
            // Handle open
          case .closed:
            // Handle closed
          case .unknown:
            // Handle unknown
        }
      }

آبجکتیو-سی

          GMSPlaceIsOpenRequest *isOpenRequest = [[GMSPlaceIsOpenRequest alloc] initWithPlace:place date:nil];

          [[GMSPlacesClient sharedClient] isOpenWithRequest:isOpenRequest callback:^(GMSPlaceIsOpenResponse response, NSError *_Nullable error) {
            if (error) {
              // Handle error
            }

            switch (response.status) {
              case GMSPlaceOpenStatusOpen:
                // Handle open
              case GMSPlaceOpenStatusClosed:
                // Handle closed
              case GMSPlaceOpenStatusUnknown:
                // Handle unknown
            }
          }];

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

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

  • فهرست فیلد

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

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

    • فیلدهای زیر باعث راه‌اندازی SKU حرفه‌ای جستجوی اطراف می‌شوند:

      GMSPlacePropertyAddressComponents
      GMSPlacePropertyBusinessStatus
      GMSPlacePropertyCoordinate
      GMSPlacePropertyFormattedAddress
      GMSPlacePropertyName
      GMSPlacePropertyIconBackgroundColor
      GMSPlacePropertyIconImageURL
      GMSPlacePropertyPhotos
      GMSPlacePropertyPlaceID
      GMSPlacePropertyPlusCode
      GMSPlacePropertyTypes
      GMSPlacePropertyUTCOffsetMinutes
      GMSPlacePropertyViewport
      GMSPlacePropertyWheelchairAccessibleEntrance

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

    • فیلدهای زیر Nearby Search Enterprise SKU را راه‌اندازی می‌کنند:

      GMSPlacePropertyCurrentOpeningHours
      GMSPlacePropertySecondaryOpeningHours
      GMSPlacePropertyPhoneNumber
      GMSPlacePropertyPriceLevel
      GMSPlacePropertyRating
      GMSPlacePropertyOpeningHours
      GMSPlacePropertyUserRatingsTotal
      GMSPlacePropertyWebsite

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

    • فیلدهای زیر باعث راه‌اندازی واحد نگهداری کالای Nearby Search Enterprise Plus می‌شوند:

      GMSPlacePropertyCurbsidePickup
      GMSPlacePropertyDelivery
      GMSPlacePropertyDineIn
      GMSPlacePropertyEditorialSummary
      GMSPlacePropertyReservable
      GMSPlacePropertyReviews
      GMSPlacePropertyServesBeer
      GMSPlacePropertyServesBreakfast
      GMSPlacePropertyServesBrunch
      GMSPlacePropertyServesDinner
      GMSPlacePropertyServesLunch
      GMSPlacePropertyServesVegetarianFood
      GMSPlacePropertyServesWine
      GMSPlacePropertyTakeout

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

    مثال زیر فهرستی از دو مقدار فیلد را برای مشخص کردن اینکه شیء GMSPlace برگردانده‌شده توسط درخواست حاوی فیلدهای name و placeID است ارسال می‌کند:

    کیت توسعه نرم‌افزار Swift مکان‌ها

    // Specify the place data types to return.
let fields: [PlaceProperty] = [.placeID, .displayName]

    Swift

    // Specify the place data types to return.
let fields: [GMSPlaceProperty] = [.placeID, .name]

    آبجکتیو-سی

    // Specify the place data types to return.
NSArray<GMSPlaceProperty *> *fields = @[GMSPlacePropertyPlaceID, GMSPlacePropertyName];

  • locationRestriction

    شیء GMSPlaceLocationRestriction که منطقه جستجو را به‌صورت دایره‌ای تعریف می‌کند و با نقطه مرکزی و شعاع برحسب متر مشخص می‌شود. شعاع باید بین ۰٫۰ و ۵۰۰۰۰٫۰ باشد و می‌تواند این دو عدد را نیز دربر بگیرد. شعاع پیش‌فرض ۰٫۰ است. باید آن را در درخواستتان روی مقداری بزرگ‌تر از ۰٫۰ تنظیم کنید.

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

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

  • 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

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

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

  • maxResultCount

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

  • rankPreference

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

    • ‫.popularity (پیش‌فرض) نتایج را براساس محبوبیت آن‌ها مرتب می‌کند.
    • .distance نتایج را به‌ترتیب صعودی براساس فاصله‌شان از مکان مشخص‌شده مرتب می‌کند.

  • regionCode

    کد منطقه‌ای که برای قالب‌بندی پاسخ استفاده می‌شود، به‌عنوان مقدار کد CLDR دو نویسه‌ای مشخص شده است. مقدار پیش‌فرضی وجود ندارد.

    اگر نام کشور فیلد formattedAddress در پاسخ با regionCode مطابقت داشته باشد، کد کشور از formattedAddress حذف می‌شود. این پارامتر هیچ تأثیری بر adrFormatAddress ندارد، که همیشه نام کشور را دربرمی‌گیرد، یا بر shortFormattedAddress، که هرگز آن را دربرنمی‌گیرد.

    اکثر کدهای CLDR با کدهای ISO 3166-1 یکسان هستند، با چند استثنای قابل‌توجه. برای مثال، ccTLD پادشاهی متحد «uk» (.co.uk) است، درحالی‌که کد ISO 3166-1 آن «gb» است (ازنظر فنی برای نهاد «پادشاهی متحد بریتانیای کبیر و ایرلند شمالی»). این پارامتر می‌تواند براساس قانون ذی‌ربط بر نتایج تأثیر بگذارد.

نمایش ارجاع‌ها در برنامه

وقتی برنامه‌تان اطلاعاتی را که از GMSPlacesClient به‌دست آورده است، مثل عکس‌ها و مرورها، نمایش می‌دهد، برنامه باید اسناد اقتباس الزامی را نیز نمایش دهد.

برای مثال، دارایی reviews شیء GMSPlacesClient شامل آرایه‌ای از حداکثر پنج شیء GMSPlaceReview است. هر شیء GMSPlaceReview می‌تواند شامل ارجاع‌ها و ارجاع‌های نویسنده باشد. اگر مرور را در برنامه‌تان نمایش می‌دهید، باید اسناد یا اسناد نویسنده را نیز نمایش دهید.

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