تزود حزمة الأماكن لحزمة تطوير البرامج (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 8th Africa, New York, NY" من المكونات التالية: "111" (رقم الشارع) و"8th Street" (المسار) و"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
مع "تفاصيل المكان".
ساعات استثنائية
يتم تحديد ساعات العمل العادية من خلال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 } }
الحصول على مكان باستخدام رقم التعريف
رقم تعريف المكان هو معرّف نصي يعرّف المكان بشكل فريد. في حزمة تطوير برامج الأماكن لأجهزة 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 هو المعرِّف نفسه المستخدَم في Places API وحزمة تطوير برامج الأماكن (SDK) لنظام التشغيل Android وغير ذلك من واجهات Google APIs.
ويمكن أن يشير كل رقم تعريف مكان إلى مكان واحد فقط، ولكن يمكن أن يتضمّن المكان الواحد أكثر من رقم تعريف مكان واحد.
هناك ظروف قد تؤدي إلى حصول المكان على رقم تعريف مكان جديد. على سبيل المثال، قد يحدث ذلك إذا تم نقل نشاط تجاري إلى موقع جديد.
عندما تطلب مكانًا معيّنًا من خلال تحديد معرّف مكان، يمكنك أن تثق في أنّك ستتلقّى دائمًا المكان نفسه في الردّ (إذا كان المكان لا يزال متوفرًا). يُرجى العِلم بأنّ الردّ قد يحتوي على معرّف مكان مختلف عن المعرّف الوارد في طلبك.
لمزيد من المعلومات، اطّلِع على نظرة عامة على معرّف المكان.