تساعد حزمة تطوير البرامج (SDK) للأماكن التي تعمل بنظام التشغيل iOS في تزويد تطبيقك بمعلومات مفيدة عن الأماكن، بما في ذلك اسم المكان وعنوانه والموقع الجغرافي المحدّد كإحداثيات خطوط الطول والعرض ونوع المكان (مثل النوادي الليلية ومتاجر الحيوانات الأليفة والمتحف) وغير ذلك. للوصول إلى هذه المعلومات حول مكان محدد، يمكنك استخدام معرّف المكان، وهو معرّف ثابت يحدّد مكانًا فريدًا.
تفاصيل المكان
توفّر الصف
GMSPlace
معلومات عن مكان محدّد. يمكنك تجميد عنصر GMSPlace
بالطرق التالية:
- يمكنك استخدام
GMSPlacesClient findPlaceLikelihoodsFromUserLocationWithPlaceFields:
. اطّلِع على دليل الحصول على المكان الحالي. - الاتصال
GMSPlacesClient fetchPlaceFromPlaceID:
، وتمريرGMSPlaceField
، ورقم تعريف المكان، وطريقة معاودة الاتصال. بالنسبة إلى طلبات تفاصيل المكان، إذا لم تحدّد حقلاً واحدًا على الأقل يتضمّن طلبًا، أو إذا حذفت مَعلمةfields
من طلب، سيتم عرض جميع الحقول المحتملة وستتم محاسبتك وفقًا لذلك. اطّلِع على دليل الحصول على مكان من خلال رقم التعريف.
عند طلب مكان، عليك تحديد أنواع بيانات المكان التي تريد عرضها. ولإجراء ذلك، مرِّر 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))
Objective-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 شارع 8، نيويورك، نيويورك" من المكوّنات التالية: "111" (رقم الشارع)، و"شارع 8" (المسار) و"نيويورك" (المدينة) و "نيويورك" (ولاية الولايات المتحدة).
لا يمكنك تحليل العنوان الذي تم تنسيقه آليًا. وبدلاً من ذلك، عليك استخدام مكوّنات العنوان الفردي التي تتضمّنها استجابة واجهة برمجة التطبيقات بالإضافة إلى حقل العنوان المنسَّق.
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
يسمحان بإجراء تغييرات في العطلات والجدول الزمني المؤقت.
يمكنك فلترة ساعات العمل الاستثنائية في هذه الأيام الخاصة وتقديمها في حال توفّرها.
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 } }
Objective-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 } }
الحصول على مكان باستخدام رقم التعريف
رقم تعريف المكان هو معرّف نصي يحدِّد مكانًا بشكلٍ فريد. في
حزمة تطوير البرامج (SDK) للأماكن على جهاز iOS، يمكنك استرداد معرّف المكان من
الكائن GMSPlace
. يمكنك تخزين رقم تعريف المكان واستخدامه لاسترداد
العنصر GMSPlace
مرة أخرى لاحقًا.
للحصول على مكان حسب رقم التعريف، اطلب
GMSPlacesClient
fetchPlaceFromPlaceID:
، مع تمرير المعلّمات التالية:
- سلسلة تحتوي على رقم تعريف مكان.
GMSPlaceField
أو أكثر، مع تحديد أنواع البيانات التي تريد عرضها.- رمز مميز للجلسة إذا تم إجراء المكالمة لإنهاء طلب بحث تلقائي وبخلاف ذلك، يجب اجتياز الاختبار.
- تمثّل هذه السمة
GMSPlaceResultCallback
للتعامل مع النتيجة.
تستدعي واجهة برمجة التطبيقات طريقة معاودة الاتصال المحدّدة، تنتقل في عنصر GMSPlace
. إذا لم يتم العثور على المكان، يكون عنصر المكان فارغًا.
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)") } })
Objective-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:
، يجب أن يعرض التطبيق أيضًا معلومات عن مصدر الإحالات.
راجِع المواد المتعلّقة بالإحالات.
مزيد من المعلومات حول أرقام تعريف الأماكن
معرّف المكان المستخدَم في حزمة تطوير البرامج (SDK) للأماكن على نظام التشغيل iOS هو المعرّف نفسه المستخدَم في واجهة برمجة تطبيقات الأماكن وحزمة تطوير البرامج (SDK) للأماكن المخصّصة لنظام التشغيل Android وغيرها من واجهات برمجة تطبيقات Google.
يمكن أن يشير رقم تعريف المكان إلى مكان واحد فقط، ولكن يمكن أن يحتوي مكان واحد على أكثر من رقم تعريف واحد.
في بعض الحالات، قد يحصل مكان على رقم تعريف جديد للمكان. على سبيل المثال، قد يحدث ذلك إذا انتقل نشاط تجاري إلى موقع جغرافي جديد.
عند طلب مكان من خلال تحديد رقم تعريف المكان، يمكنك التأكد من أنك ستتلقى دائمًا المكان نفسه في الرد (إذا كان المكان لا يزال موجودًا). يُرجى العِلم بأنّ الاستجابة قد تحتوي على رقم تعريف مكان مختلف عن المعرّف الوارد في طلبك.
للحصول على مزيد من المعلومات، يمكنك الاطّلاع على نظرة عامة على رقم تعريف المكان.