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

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

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

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

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

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

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

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

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

مکان‌های Swift SDK 

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
}

سویفت 

// 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;
    }
  }
];

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

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

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

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

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

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

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

  • GMSPlacePropertyUTCOffsetMinutes
  • GMSPlacePropertyBusinessStatus
  • GMSPlacePropertyOpeningHours
  • GMSPlacePropertyCurrentOpeningHours
  • GMSPlacePropertySecondaryOpeningHours

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

پاسخ isOpenWithRequest

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

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

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

مثال: یک درخواست GMSPlaceIsOpenWithRequest ایجاد کنید

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

مکان‌های Swift SDK 

        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
        }

سویفت 

    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 مربوط به Nearby Search Pro را فعال می‌کنند:

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

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

      GMSPlacePropertyCurrentOpeningHours
      GMSPlacePropertySecondaryOpeningHours
      GMSPlacePropertyPhoneNumber
      GMSPlacePropertyPriceLevel
      GMSPlacePropertyRating
      GMSPlacePropertyOpeningHours
      GMSPlacePropertyUserRatingsTotal
      GMSPlacePropertyWebsite

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

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

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

    مکان‌های Swift SDK 

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

    سویفت 

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

    هدف-سی 

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

  • محدودیت مکانی

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

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

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

  • انواع گنجانده‌شده/انواع مستثنی‌شده، انواع اولیه گنجانده‌شده/انواع اولیه مستثنی‌شده

    به شما امکان می‌دهد لیستی از انواع را از انواع جدول 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": ["restaurant"], "excludedPrimaryTypes": ["steak_house"]} را مشخص کنید، مکان‌های برگردانده شده خدمات مرتبط با "restaurant" را ارائه می‌دهند اما در درجه اول به عنوان "steak_house" فعالیت نمی‌کنند.

    شاملانواع

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

    انواع مستثنی

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

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

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

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

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

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

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

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

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

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

  • رتبه بندی

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

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

  • کد منطقه

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

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

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

نمایش انتساب‌ها در برنامه شما

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

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

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