جزئیات مکان

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

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

جزئیات مکان

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

وقتی مکانی را درخواست می کنید، باید نوع داده های مکان را مشخص کنید. برای انجام این کار، یک 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))

هدف-C

      // 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". " (ایالت ایالات متحده).

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

  • 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 با جزئیات مکان، این ویدیو را ببینید.

ساعات استثنایی داشته باشید

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

سریع

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

هدف-C

- (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 SDK برای iOS، می‌توانید شناسه مکان را از یک شی GMSPlace بازیابی کنید. می‌توانید شناسه مکان را ذخیره کنید و بعداً از آن برای بازیابی شی GMSPlace استفاده کنید.

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

  • رشته ای حاوی شناسه مکان.
  • یک یا چند عدد GMSPlaceField که انواع داده‌های مورد نظر را مشخص می‌کند.
  • یک نشانه جلسه در صورتی که تماس برای نتیجه گیری یک پرس و جو تکمیل خودکار انجام شود. در غیر این صورت، از صفر عبور کنید.
  • یک GMSPlaceResultCallback برای رسیدگی به نتیجه.

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

سریع

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

هدف-C

// 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: را نمایش می دهد، برنامه همچنین باید اسناد را نمایش دهد. اسناد مربوط به اسناد را ببینید.

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

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

هر شناسه مکان می تواند تنها به یک مکان اشاره داشته باشد، اما یک مکان واحد می تواند بیش از یک شناسه مکان داشته باشد.

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

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

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