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

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

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

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

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

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

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

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

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

سویفت 

// 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)

هدف-C 

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

مکان‌ها Swift SDK برای iOS (پیش‌نمایش) 

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
}

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

Nearby Search API آرایه‌ای از منطبق‌ها را در قالب اشیاء GMSPlace با یک شی GMSPlace در هر مکان منطبق برمی‌گرداند.

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

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

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

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

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

  • GMSPlacePropertyUTCOffsetMinutes
  • GMSPlacePropertyBusinessStatus
  • GMSPlacePropertyOpeningHours
  • GMSPlacePropertyCurrentOpeningHours
  • GMSPlacePropertySecondaryOpeningHours

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

پاسخ isOpenWithRequest

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

زبان ارزش در صورت باز بودن ارزش در صورت بسته شدن در صورت ناشناخته بودن وضعیت، مقدار را تعیین کنید
سویفت .open .closed .unknown
هدف-C GMSPlaceOpenStatusOpen GMSPlaceOpenStatusClosed GMSPlaceOpenStatusUnknown
GooglePlacesSwift (پیش نمایش) true false nil

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

  • فیلدهای GMSPlacePropertyUTCOffsetMinutes و GMSPlacePropertyBusinessStatus تحت عنوان Basic Data SKU شارژ می شوند. بقیه ساعات کار تحت SKU جزئیات مکان (پیشرفته) شارژ می شود.
  • اگر شی GMSPlace شما قبلاً دارای این فیلدها از درخواست قبلی است، دیگر هزینه ای از شما کسر نخواهد شد.

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

مثال زیر نشان می دهد که چگونه یک GMSPlaceIsOpenWithRequest را در یک شی GMSPlace موجود مقداردهی کنید.

سویفت 

    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
        }
      }

هدف-C 

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

GooglePlacesSwift 

          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
          }

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

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

  • لیست زمینه

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

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

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

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

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

      GMSPlacePropertyCurrentOpeningHours , GMSPlacePropertySecondaryOpeningHours , GMSPlacePropertyPhoneNumber , GMSPlacePropertyPriceLevel , GMSPlacePropertyRating , GMSPlacePropertyOpeningHours , GMSPlacePropertyUserRatingsTotal GMSPlacePropertyWebsite

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

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

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

    سویفت 

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

    هدف-C 

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

    مکان‌ها Swift SDK برای iOS (پیش‌نمایش) 

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

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

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

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

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

  • includeTypes/excludedTypes، includePrimaryTypes/excludedPrimaryTypes

    به شما امکان می دهد لیستی از انواع از انواع جدول A که برای فیلتر کردن نتایج جستجو استفاده می شود را مشخص کنید. حداکثر 50 نوع را می توان در هر دسته بندی محدودیت نوع مشخص کرد.

    یک مکان فقط می تواند یک نوع اصلی از انواع جدول 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 برای جستجو. اگر این پارامتر حذف شود، مکان های همه نوع برگردانده می شوند.

    excludedTypes

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

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

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

    شامل PrimaryTypes

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

    excludedPrimaryTypes

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

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

  • maxResultCount

    حداکثر تعداد نتایج مکان برای بازگشت را مشخص می کند. باید بین 1 تا 20 (پیش‌فرض) باشد.

  • رتبه اولویت

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

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

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