جزئیات جا

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

جزئیات جا

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

• تماس با GMSPlacesClient findPlaceLikelihoodsFromUserLocationWithPlaceFields:. راهنمای دریافت مکان فعلی را ببینید.
• GMSPlacesClient fetchPlaceFromPlaceID: را فراخوانی کنید و GMSPlaceField، شناسه مکان، و روش فراخوانی را ارسال کنید. برای درخواست‌های «جزئیات جا»، اگر حداقل یک فیلد را با درخواست مشخص نکنید، یا اگر پارامتر fields را از درخواست حذف کنید، همه فیلدهای ممکن برگردانده خواهند شد و صورت‌حساب شما براساس آن صادر خواهد شد. راهنمای دریافت مکان با شناسه را ببینید.

وقتی مکانی را درخواست می‌کنید، باید مشخص کنید که کدام نوع داده‌های مکان برگردانده شود. برای انجام این کار، GMSPlaceField را ارسال کنید و نوع داده‌هایی را که باید برگردانده شود مشخص کنید. این نکته مهمی است، زیرا بر هزینه هر درخواست تأثیر می‌گذارد.

چون نتایج داده‌های مکان نمی‌تواند خالی باشد، فقط نتایج مکان دارای داده برگردانده می‌شود (برای مثال، اگر مکان درخواستی عکسی نداشته باشد، فیلد photos در نتیجه وجود نخواهد داشت).

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

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

      // Specify the place data types to return.
      let fields: GMSPlaceField = GMSPlaceField(rawValue: UInt(GMSPlaceField.name.rawValue) |
      UInt(GMSPlaceField.placeID.rawValue))
  

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

      // Specify the place data types to return.
      GMSPlaceField fields = (GMSPlaceFieldName | GMSPlaceFieldPlaceID);
  

درباره فیلدهای مکان بیشتر بدانید. برای اطلاعات بیشتر درباره نحوه صدور صورت‌حساب برای درخواست‌های داده‌های «مکان»، به استفاده و صدور صورت‌حساب مراجعه کنید.

کلاس GMSPlace می‌تواند حاوی داده‌های مکان زیر باشد:

• name – نام مکان.
• editorialSummary – شرحی از مکان ارائه می‌دهد.
• placeID – شناسه نوشتاری مکان. در ادامه این صفحه، درباره شناسه مکان بیشتر بخوانید.
• coordinate – مکان جغرافیایی محل، که به‌صورت مختصات طول و عرض جغرافیایی مشخص شده است.
• phoneNumber – شماره تلفن مکان، در قالب بین‌المللی.
• formattedAddress – نشانی قابل‌خواندن برای انسان این مکان.

  اغلب این نشانی معادل نشانی پستی است. توجه داشته باشید که برخی کشورها، مانند پادشاهی متحد، به‌دلیل محدودیت‌های صدور پروانه، اجازه توزیع نشانی‌های پستی واقعی را نمی‌دهند.

  نشانی قالب‌بندی‌شده به‌طور منطقی از یک یا چند مؤلفه نشانی تشکیل شده است. برای مثال، نشانی «111 8th Avenue, New York, NY» از مؤلفه‌های زیر تشکیل شده است: «111» (شماره خیابان)، «8th Avenue» (مسیر)، «New York» (شهر)، و «NY» (ایالت امریکا).

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

• openingHours – ساعات کاری مکان (همان‌طور که با GMSOpeningHours نشان داده شده است). GMSOpeningHours.weekdayText را فراخوانی کنید تا فهرستی از رشته‌های بومی‌سازی‌شده ساعات کاری روزانه برای هفته را دریافت کنید. GMSOpeningHours.Periods را فراخوانی کنید تا فهرستی از GMSPeriodها با اطلاعات دقیق‌تر که معادل داده‌های ارائه‌شده توسط weekdayText است برگردانده شود. توجه: اگر مکانی همیشه باز باشد، دوره زمانی به‌صورت نیمه‌شب یکشنبه نشان داده می‌شود و closeEvent تهی است.
• currentOpeningHours و secondaryOpeningHours – فیلدهایی که تغییرات موقت و تعطیلات را در زمان‌بندی مکان می‌پذیرند.

• addressComponents – آرایه‌ای از اشیاء GMSAddressComponent که نشان‌دهنده مؤلفه‌های نشانی یک مکان است. این مؤلفه‌ها با هدف استخراج اطلاعات ساختاریافته درباره نشانی مکان ارائه می‌شوند، برای مثال پیدا کردن شهری که مکان در آن واقع شده است. از این مؤلفه‌ها برای قالب‌بندی نشانی استفاده نکنید؛ درعوض، از ویژگی formattedAddress استفاده کنید که نشانی قالب‌بندی‌شده بومی‌سازی‌شده ارائه می‌دهد.

  به حقایق زیر درباره آرایه addressComponents توجه کنید:

  • آرایه مؤلفه‌های نشانی ممکن است مؤلفه‌های بیشتری نسبت به formattedAddress داشته باشد.
  • این آرایه لزوماً شامل همه نهادهای سیاسی که حاوی نشانی هستند نمی‌شود، به‌جز آن‌هایی که در formattedAddress گنجانده شده‌اند.
  • تضمینی وجود ندارد که قالب پاسخ بین درخواست‌ها یکسان باقی بماند. به‌ویژه، تعداد addressComponents براساس نشانی درخواست‌شده متفاوت است و می‌تواند درطول زمان برای نشانی یکسان تغییر کند. موقعیت مؤلفه می‌تواند در آرایه تغییر کند. نوع مؤلفه می‌تواند تغییر کند. ممکن است مؤلفه خاصی در پاسخ بعدی وجود نداشته باشد.
• userRatingsTotal – نشان‌دهنده تعداد مرورهایی است که رده‌بندی مکان را تشکیل می‌دهند.

کلاس GMSPlace شامل توابع عضو زیر است:

• isOpen محاسبه می‌کند که آیا مکانی در زمان مشخص‌شده باز است یا نه، براساس openingHours و UTCOffsetMinutes، و تاریخ و ساعت کنونی.
• isOpenAtDate براساس openingHours و UTCOffsetMinutes، و تاریخ و ساعت کنونی، محاسبه می‌کند که آیا مکانی در تاریخ مشخصی باز است یا نه.

هنگام استفاده از این توابع برای دریافت زمان و/یا تاریخ باز شدن، درخواست اصلی fetchPlaceFromPlaceID: یا findPlaceLikelihoodsFromUserLocationWithPlaceFields: باید هر دو فیلد GMSPlaceFieldOpeningHours و GMSPlaceFieldUTCOffsetMinutes را مشخص کند. اگر هرکدام از این فیلدها وجود نداشته باشد، شیء GMSPlace حاصل حاوی زمان یا تاریخ باز شدن نخواهد بود و تماس GMSPlaceOpenStatusUnknown را برمی‌گرداند. برای نتایج دقیق، فیلدهای GMSPlaceFieldBusinessStatus و GMSPlaceFieldUTCOffsetMinutes را در درخواست مکان اصلی‌تان درخواست کنید. اگر درخواست نشود، فرض می‌شود که کسب‌وکار فعال است.

برای نحوه استفاده از isOpen با «جزئیات جا»، ویدیو نحوه دریافت ساعت کاری را ببینید.

دریافت ساعت‌های کاری استثنایی

    func examineOpeningHours(place: GMSPlace) {

      // Check if the current opening hours contains a special day that has exceptional hours
      guard let currentOpeningHours = place.currentOpeningHours else { return }
      if let specialDays = currentOpeningHours.specialDays {
        guard !specialDays.isEmpty else { return }
        if let specialDay = specialDays.filter { $0.isExceptional }.first  {
          // Indicate exceptional hours
        }
      }

      // Check if current opening hours contains a truncated time period
      let periods = currentOpeningHours.periods

      if !periods.isEmpty {
        for period in periods {
          let open = period.open
          let close = period.close

          if let open = open {
            let date = open.date

            if open.isTruncated {
              // Indicate truncated time period
            }
          }
        }
      }

      // Check if the place's secondary opening hours indicate when delivery is available
      let secondaryOpeningHours = place.secondaryOpeningHours
      guard let hoursType = secondaryOpeningHours.first?.hoursType else {
      return
      }

      if (hoursType == GMSPlaceHoursTypeDelivery) {
        // Indicate hours where delivery is available
      }
  }

- (void)examineOpeningHours:(GMSPlace *) place {

    // Check if the current opening hours contains a special day that has exceptional hours
    GMSOpeningHours *currentOpeningHours = place.currentOpeningHours;
    if (currentOpeningHours != nil) {
      NSArray<GMSPlaceSpecialDay *> *specialDays = currentOpeningHours.specialDays;
      if ([specialDays count] != 0) {
        for (GMSPlaceSpecialDay *specialDay in specialDays) {
          NSDate *date = specialDay.date;
          if ([specialDay isExceptional]) {
            // Indicate exceptional hours
          }
        }
      }
    }

    // Check if current opening hours contains a truncated time period
    NSArray <GMSPeriod *> * periods = currentOpeningHours.periods;

    if ([periods count] != 0) {
      for (GMSPeriod * period in periods) {
        GMSTimeOfWeek *open = period.open;
        GMSTimeOfWeek *close = period.close;

        if (open) {
          if ([open isTruncated]) {
            // Indicate truncated time period
          }
        }
      }
    }

    // Check if the place's secondary opening hours indicate when delivery is available
    GMSOpeningHours *secondaryOpeningHours = place.secondaryOpeningHours;
    GMSPlaceHoursType hoursType = secondaryOpeningHours.getHoursType;

    if (hoursType == GMSPlaceHoursTypeDelivery) {
      // Indicate hours where delivery is available
    }
}

دریافت مکان با شناسه

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

برای دریافت مکان با شناسه، GMSPlacesClient fetchPlaceFromPlaceID: را فراخوانی کنید و پارامترهای زیر را ارسال کنید:

• رشته‌ای که حاوی «شناسه مکان» است.
• یک یا چند GMSPlaceField که نوع داده‌های برگشتی را مشخص می‌کند.
• اگر تماس برای تکمیل پُرسمان تکمیل خودکار برقرار شده باشد، کد جلسه. درغیراین‌صورت، nil را ارسال کنید.
• ‫GMSPlaceResultCallback برای رسیدگی به نتیجه.

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

// Initialize Places Swift Client.
let placesClient = PlacesClient.shared

// A hotel in Saigon with an attribution
let placeID = "ChIJV4k8_9UodTERU5KXbkYpSYs"
    
// Fetch Place Request.
let fetchPlaceRequest = FetchPlaceRequest(
  placeID: placeID,
  placeProperties: [.displayName]
)
    
Task {
  switch await placesClient.fetchPlace(with: fetchPlaceRequest) {
  case .success(let place):
    print("The selected place is: \(place.displayName): \(String(describing: place.description))")
  case .failure(let placesError):
    print("Place not found: \(placeID); \(placesError)")
  }
}

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

// Specify the place data types to return.
let fields: GMSPlaceField = GMSPlaceField(rawValue: UInt(GMSPlaceField.name.rawValue) |
  UInt(GMSPlaceField.placeID.rawValue))!

placesClient?.fetchPlace(fromPlaceID: placeID, placeFields: fields, sessionToken: nil, callback: {
  (place: GMSPlace?, error: Error?) in
  if let error = error {
    print("An error occurred: \(error.localizedDescription)")
    return
  }
  if let place = place {
    self.lblName?.text = place.name
    print("The selected place is: \(place.name)")
  }
})

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

// Specify the place data types to return.
GMSPlaceField fields = (GMSPlaceFieldName | GMSPlaceFieldPlaceID);

[_placesClient fetchPlaceFromPlaceID:placeID placeFields:fields sessionToken:nil callback:^(GMSPlace * _Nullable place, NSError * _Nullable error) {
  if (error != nil) {
    NSLog(@"An error occurred %@", [error localizedDescription]);
    return;
  }
  if (place != nil) {
    NSLog(@"The selected place is: %@", [place name]);
  }
}];

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

وقتی برنامه‌تان اطلاعات به‌دست‌آمده از GMSPlacesClient lookUpPlaceID:callback: را نمایش می‌دهد، برنامه باید ارجاع‌ها را نیز نمایش دهد. مستندات مربوط به ارجاع‌ها را ببینید.

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

شناسه مکان استفاده‌شده در «کیت توسعه نرم‌افزار مکان‌ها» برای iOS همان شناسه‌ای است که در Places API، «کیت توسعه نرم‌افزار مکان‌ها» برای Android و دیگر میاناهای برنامه‌سازی کاربردی Google استفاده می‌شود.

هر شناسه مکان فقط می‌تواند به یک مکان اشاره کند، اما یک مکان می‌تواند بیش‌از یک شناسه مکان داشته باشد.

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

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

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