جزئیات جا

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

جزئیات جا

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

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

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

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

Swift

      // 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 تماس بگیرید. برای دریافت فهرستی از GMSPeriod با اطلاعات دقیق‌تر که معادل داده‌های ارائه‌شده توسط weekdayText است، با GMSOpeningHours.Periods تماس بگیرید. توجه: اگر مکانی همیشه باز باشد، دوره زمانی به‌صورت نیمه‌شب یکشنبه نشان داده می‌شود و 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 با «جزئیات مکان»، ویدیو نحوه دریافت ساعات کاری را ببینید .

دریافت ساعات استثنایی

درحالی‌که ساعات کاری عادی ازطریق openingHours، currentOpeningHours، و secondaryOpeningHours به‌دست می‌آید، از تغییرات موقت و تغییرات زمان‌بندی تعطیلات پشتیبانی می‌کند. ساعات کاری استثنایی برای این روزهای خاص را می‌توان درصورت وجود فیلتر و ارائه کرد.

Swift

    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 را به آن ارسال می‌کند. اگر مکان پیدا نشود، شیء مکان تهی است.

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

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

Swift

// 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 APIs استفاده می‌شود.

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

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

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

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