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