جزئیات مکان (جدید)

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

این ویژگی مستلزم آن است که Places API (جدید)، نسل بعدی Places API را فعال کنید. برای اطلاعات بیشتر، فعال کردن API ها را ببینید.

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

جزئیات مکان را دریافت کنید

کلاس GMSPlace حاوی اطلاعاتی در مورد یک مکان خاص است، از جمله تمام فیلدهای داده نشان داده شده در Place Data Fields (جدید) . با فراخوانی GMSPlacesClient fetchPlaceWithRequest: ارسال یک شیء GMSFetchPlaceRequest و یک روش پاسخ به تماس از نوع GMSPlaceResultCallback یک شی GMSPlace دریافت کنید.

شی GMSFetchPlaceRequest مشخص می کند:

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

درخواست جزئیات مکان کنید

این مثال با عبور از پارامترهای زیر یک مکان با شناسه دریافت می کند:

• شناسه مکان ChIJV4k8_9UodTERU5KXbkYpSYs .
• یک لیست فیلدی که مشخص می کند نام مکان و URL وب سایت را برگرداند.
• یک GMSPlaceResultCallback برای رسیدگی به نتیجه.

API روش برگشت تماس مشخص شده را فراخوانی می کند و در یک شی GMSPlace ارسال می کند. اگر مکان پیدا نشد، شی مکان صفر است.

سویفت

// A hotel in Saigon with an attribution.
let placeID = "ChIJV4k8_9UodTERU5KXbkYpSYs"

// Specify the place data types to return.
let myProperties = [GMSPlaceProperty.name, GMSPlaceProperty.website].map {$0.rawValue}

// Create the GMSFetchPlaceRequest object.
let fetchPlaceRequest = GMSFetchPlaceRequest(placeID: placeID, placeProperties: myProperties, sessionToken: nil)

client.fetchPlace(with: fetchPlaceRequest, callback: {
  (place: GMSPlace?, error: Error?) in
  guard let place, error == nil else { return }
  print("Place found: \(String(describing: place.name))")
})

هدف-C

// A hotel in Saigon with an attribution.
NSString *placeID = @"ChIJV4k8_9UodTERU5KXbkYpSYs";

// Specify the place data types to return.
NSArray<NSString *> *myProperties = @[GMSPlacePropertyName, GMSPlacePropertyWebsite];

// Create the GMSFetchPlaceRequest object.
GMSFetchPlaceRequest *fetchPlaceRequest = [[GMSFetchPlaceRequest alloc] initWithPlaceID:placeID placeProperties: myProperties sessionToken:nil];

[placesClient fetchPlaceWithRequest: fetchPlaceRequest callback: ^(GMSPlace *_Nullable place, NSError *_Nullable error) {
    if (error != nil) {
      NSLog(@"An error occurred %@", [error localizedDescription]);
      return;
    } else {
    NSLog(@"Place Found: %@", place.name);
    NSLog(@"The place URL: %@", place.website);
  }
}];

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

// A hotel in Saigon with an attribution.
let placeID = "ChIJV4k8_9UodTERU5KXbkYpSYs"
let fetchPlaceRequest = FetchPlaceRequest(
  placeID: placeID,
  placeProperties: [.name, .website]
)
switch await placesClient.fetchPlace(with: fetchPlaceRequest) {
case .success(let place):
  // Handle place
case .failure(let placesError):
  // Handle error
}

پاسخ جزئیات مکان

Place Details یک شی GMSPlace حاوی جزئیات مربوط به مکان را برمی گرداند. فقط فیلدهایی که در لیست فیلد مشخص شده اند در شی GMSPlace پر می شوند.

توجه: فیلدهای شی پاسخ GMSPlace نمی تواند خالی باشد. به عنوان مثال، اگر لیست فیلد شامل GMSPlacePropertyPhotos برای درخواست فیلد photos در پاسخ باشد، و فیلد photos در پاسخ خالی باشد، از شیء پاسخ GMSPlace حذف می‌شود.

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

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

توجه: توابع منسوخ شده GMSPlace isOpen: و GMSPlace isOpenAtDate: ممکن است نادرست باشند و قرار نیست با Places API (جدید) استفاده شوند.

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

• یک شی GMSPlace یا رشته ای که شناسه مکان را مشخص می کند. برای اطلاعات بیشتر در مورد ایجاد شی Place با فیلدهای لازم، جزئیات مکان را ببینید.
  
  توجه: شی 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 شما قبلاً دارای این فیلدها از درخواست قبلی است، دیگر هزینه ای از شما کسر نخواهد شد.
• اخطار اگر شی GMSPlace شما این فیلدها را نداشته باشد، مجدداً هزینه Basic Data SKU از شما کسر می شود. بقیه ساعات کار تحت SKU جزئیات مکان (پیشرفته) شارژ می شود. اگر پروژه شما از isOpenWithRequest استفاده می کند، توصیه می کنیم اطمینان حاصل کنید که جزئیات مکان لازم را دریافت کرده اید.

مثال: یک درخواست 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
          }
          

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

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

شناسه مکان

شناسه مکان مورد استفاده در Places SDK برای iOS همان شناسه‌ای است که در Places API، Places SDK برای Android و سایر APIهای Google استفاده می‌شود. هر شناسه مکان می تواند تنها به یک مکان اشاره داشته باشد، اما یک مکان واحد می تواند بیش از یک شناسه مکان داشته باشد.

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

هنگامی که با تعیین شناسه مکان درخواست مکانی می کنید، می توانید مطمئن باشید که همیشه همان مکان را در پاسخ دریافت خواهید کرد (اگر مکان هنوز وجود دارد). با این حال، توجه داشته باشید که پاسخ ممکن است حاوی شناسه مکانی متفاوت از شناسه درخواست شما باشد.

لیست زمینه

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

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

• فیلدهای زیر SKU جزئیات مکان (فقط شناسه) را فعال می کنند:

  GMSPlacePropertyPlaceID ، GMSPlacePropertyName ، GMSPlacePropertyPhotos

• فیلدهای زیر SKU جزئیات مکان (فقط مکان) را فعال می کنند:

  GMSPlacePropertyAddressComponents ، GMSPlacePropertyFormattedAddress ، GMSPlacePropertyCoordinate ، GMSPlacePropertyPlusCode ، GMSPlacePropertyTypes ، GMSPlacePropertyViewport

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

  GMSPlacePropertyBusinessStatus ، GMSPlacePropertyIconBackgroundColor ، GMSPlacePropertyIconImageURL ، GMSPlacePropertyUTCOffsetMinutes ، GMSPlacePropertyWheelchairAccessibleEntrance

• فیلدهای زیر 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]
    

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

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

منطقه کد

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

اگر نام کشور فیلد آدرس در پاسخ با کد منطقه مطابقت داشته باشد، کد کشور از آدرس حذف می شود.

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

sessionToken

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

اسناد را در برنامه خود نمایش دهید

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

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

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