Places SDK برای iOS به برنامه شما اطلاعات غنی درباره مکان ها، از جمله نام و آدرس مکان، موقعیت جغرافیایی مشخص شده به عنوان مختصات طول و عرض جغرافیایی، نوع مکان (مانند کلوپ شبانه، فروشگاه حیوانات خانگی، موزه) و موارد دیگر را ارائه می دهد. برای دسترسی به این اطلاعات برای یک مکان خاص، می توانید از شناسه مکان استفاده کنید، یک شناسه پایدار که به طور منحصر به فرد مکان را شناسایی می کند.
جزئیات مکان
کلاس GMSPlace
اطلاعاتی در مورد یک مکان خاص ارائه می دهد. شما می توانید یک شی GMSPlace
را به روش های زیر بدست آورید:
- تماس با
GMSPlacesClient findPlaceLikelihoodsFromUserLocationWithPlaceFields:
راهنمای دریافت مکان فعلی را ببینید. - تماس با
GMSPlacesClient fetchPlaceFromPlaceID:
ارسال یکGMSPlaceField
، یک شناسه مکان، و یک روش برگشت به تماس. برای درخواستهای Place Details، اگر حداقل یک فیلد را با یک درخواست مشخص نکنید، یا اگر پارامتر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))
هدف-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 استفاده میشود.
هر شناسه مکان می تواند تنها به یک مکان اشاره داشته باشد، اما یک مکان واحد می تواند بیش از یک شناسه مکان داشته باشد.
شرایطی وجود دارد که ممکن است باعث شود یک مکان شناسه مکان جدیدی دریافت کند. برای مثال، اگر یک کسب و کار به مکان جدیدی نقل مکان کند، ممکن است این اتفاق بیفتد.
هنگامی که با تعیین شناسه مکان درخواست مکانی می کنید، می توانید مطمئن باشید که همیشه همان مکان را در پاسخ دریافت خواهید کرد (اگر مکان هنوز وجود دارد). با این حال، توجه داشته باشید که پاسخ ممکن است حاوی شناسه مکانی متفاوت از شناسه درخواست شما باشد.
برای اطلاعات بیشتر، نمای کلی شناسه مکان را ببینید.