حزمة تطوير برامج الأماكن لأجهزة iOS (الجديدة) تزوّد تطبيقك بمعلومات غنية عن الأماكن، بما في ذلك اسم المكان وعنوانه والموقع الجغرافي الموقع المحدد كإحداثيات خطوط الطول/العرض، ونوع المكان (مثل كملهى ليلي ومتجر حيوانات أليفة ومتحف) وأكثر من ذلك. للوصول إلى هذه المعلومات مكان محدد، يمكنك استخدام معرّف المكان، وهو معرّف ثابت تحدد مكانًا.
الحصول على تفاصيل المكان
تشير رسالة الأشكال البيانية
GMSPlace
تحتوي الفئة على معلومات حول مكان معين، تتضمن جميع حقول البيانات المعروضة في
حقول بيانات الأماكن (جديدة). احصل على
GMSPlace
عن طريق استدعاء
GMSPlacesClient
fetchPlaceWithRequest:
,
تمرير كائن GMSFetchPlaceRequest
نوع طريقة رد الاتصال
GMSPlaceResultCallback
.
يحدِّد الكائن GMSFetchPlaceRequest
ما يلي:
- (مطلوب) رقم تعريف المكان، وهو معرّف فريد لمكان في "أماكن Google" قاعدة البيانات وعلى خرائط Google.
- (مطلوب) قائمة الحقول المطلوب عرضها في الكائن
GMSPlace
، ويُطلق عليها أيضًا اسم قناع الحقل، كما هو محدد فيGMSPlaceProperty
إذا لم تحدد حقلاً واحدًا على الأقل في قائمة الحقول، أو إذا حذفتَ قائمة الحقول، فسيعرض الاستدعاء خطأ. - (اختياري) رمز المنطقة المستخدَم لتنسيق الردّ.
- (اختياري) الرمز المميّز للجلسة المستخدَم لإنهاء جلسة إكمال تلقائي (جديدة).
تقديم طلب للحصول على تفاصيل مكان
يحصل هذا المثال على مكان حسب رقم التعريف، مع تمرير المعلمات التالية:
- رقم تعريف المكان:
ChIJV4k8_9UodTERU5KXbkYpSYs
- قائمة حقول تحدد لعرض اسم المكان وعنوان URL للموقع الإلكتروني.
GMSPlaceResultCallback
للتعامل مع النتيجة.
تستدعي واجهة برمجة التطبيقات طريقة معاودة الاتصال المحددة، وتمرير
GMSPlace
الخاص بك. إذا لم يتم العثور على المكان، يكون كائن المكان nil.
Swift
// A hotel in Saigon with an attribution. let placeID = "ChIJV4k8_9UodTERU5KXbkYpSYs" // Specify the place data types to return. let myProperties = [GMSPlaceProperty.name, GMSPlaceProperty.website].map {$0.rawValue} // Create the GMSFetchPlaceRequest object. let fetchPlaceRequest = GMSFetchPlaceRequest(placeID: placeID, placeProperties: myProperties, sessionToken: nil) client.fetchPlace(with: fetchPlaceRequest, callback: { (place: GMSPlace?, error: Error?) in guard let place, error == nil else { return } print("Place found: \(String(describing: place.name))") })
Objective-C
// A hotel in Saigon with an attribution. NSString *placeID = @"ChIJV4k8_9UodTERU5KXbkYpSYs"; // Specify the place data types to return. NSArray<NSString *> *myProperties = @[GMSPlacePropertyName, GMSPlacePropertyWebsite]; // Create the GMSFetchPlaceRequest object. GMSFetchPlaceRequest *fetchPlaceRequest = [[GMSFetchPlaceRequest alloc] initWithPlaceID:placeID placeProperties: myProperties sessionToken:nil]; [placesClient fetchPlaceWithRequest: fetchPlaceRequest callback: ^(GMSPlace *_Nullable place, NSError *_Nullable error) { if (error != nil) { NSLog(@"An error occurred %@", [error localizedDescription]); return; } else { NSLog(@"Place Found: %@", place.name); NSLog(@"The place URL: %@", place.website); } }];
GooglePlacesSwift
// A hotel in Saigon with an attribution. let placeID = "ChIJV4k8_9UodTERU5KXbkYpSYs" let fetchPlaceRequest = FetchPlaceRequest( placeID: placeID, placeProperties: [.name, .website] ) switch await placesClient.fetchPlace(with: fetchPlaceRequest) { case .success(let place): // Handle place case .failure(let placesError): // Handle error }
رد تفاصيل المكان
تعرض "تفاصيل المكان" علامة
عنصر GMSPlace
يحتوي على تفاصيل عن المكان. لا تتم تعبئة سوى الحقول المحدّدة في قائمة الحقول في العنصر GMSPlace
.
بالإضافة إلى حقول البيانات، هناك كائن GMSPlace
في
تحتوي الاستجابة على الدوال الأعضاء التالية:
-
تحسب
isOpen
ما إذا كان المكان مفتوحًا في وقت محدّد. isOpenAtDate
لحساب ما إذا كان المكان مفتوحًا في تاريخ معين.
المعلمات المطلوبة
استخدِم الكائن GMSFetchPlaceRequest
لتحديد المعلَمات المطلوبة.
معرّف المكان
رقم تعريف المكان المستخدم في حزمة تطوير برامج الأماكن لأجهزة iOS هو المعرّف نفسه المستخدَم في Places API، وحزمة تطوير البرامج للأماكن لنظام التشغيل Android وغيرها من واجهات Google APIs. يمكن أن يشير كلّ رقم تعريف مكان إلى مكان واحد فقط، ولكن يمكن أن يتضمّن مكان واحد أكثر. معرّف مكان واحد
هناك ظروف قد تؤدي إلى حصول المكان على رقم تعريف جديد للمكان. على سبيل المثال، قد يحدث ذلك في حال انتقال نشاط تجاري إلى موقع جغرافي جديد.
عند طلب مكان من خلال تحديد معرّف مكان، يمكنك أن تكون واثقًا من أن ستتلقى دائمًا نفس المكان في الرد (إذا كان المكان لا يزال موجود). ومع ذلك، لاحظ أن الرد قد يحتوي على معرّف مكان مختلفة عن تلك المدرجة في طلبك.
قائمة الحقول
عندما تطلب تفاصيل مكان، يجب تحديد البيانات
لعرض الكائن GMSPlace
للمكان كقناع حقل. لتحديد قناع الحقل
تمرير صفيف من القيم من
GMSPlaceProperty
إلى الكائن GMSFetchPlaceRequest
.
يُعد إخفاء المجال ممارسة جيدة على التصميم لضمان عدم طلب بيانات غير ضرورية،
يساعد في تجنب وقت المعالجة ورسوم الفوترة غير الضرورية.
حدِّد حقلاً واحدًا أو أكثر من الحقول التالية:
تؤدي الحقول التالية إلى تشغيل رمز التخزين التعريفي لتفاصيل المكان (المعرّف فقط):
GMSPlacePropertyPlaceID
,GMSPlacePropertyName
,GMSPlacePropertyPhotos
تؤدّي الحقول التالية إلى تشغيل رمز التخزين التعريفي لتفاصيل المكان (الموقع الجغرافي فقط):
GMSPlacePropertyAddressComponents
,GMSPlacePropertyFormattedAddress
,GMSPlacePropertyCoordinate
,GMSPlacePropertyPlusCode
,GMSPlacePropertyTypes
,GMSPlacePropertyViewport
تؤدي الحقول التالية إلى تشغيل رمز التخزين التعريفي لتفاصيل المكان (الأساسي):
GMSPlacePropertyBusinessStatus
,GMSPlacePropertyIconBackgroundColor
,GMSPlacePropertyIconImageURL
,GMSPlacePropertyUTCOffsetMinutes
,GMSPlacePropertyWheelchairAccessibleEntrance
تؤدي الحقول التالية إلى تشغيل رمز التخزين التعريفي لتفاصيل المكان (المتقدّمة):
GMSPlacePropertyCurrentOpeningHours
,GMSPlacePropertySecondaryOpeningHours
,GMSPlacePropertyPhoneNumber
,GMSPlacePropertyPriceLevel
,GMSPlacePropertyRating
,GMSPlacePropertyOpeningHours
,GMSPlacePropertyUserRatingsTotal
,GMSPlacePropertyWebsite
تؤدي الحقول التالية إلى تشغيل رمز التخزين التعريفي لتفاصيل المكان (المفضّل):
GMSPlacePropertyCurbsidePickup
,GMSPlacePropertyDelivery
,GMSPlacePropertyDineIn
,GMSPlacePropertyEditorialSummary
,GMSPlacePropertyReservable
,GMSPlacePropertyReviews
,GMSPlacePropertyServesBeer
,GMSPlacePropertyServesBreakfast
,GMSPlacePropertyServesBrunch
,GMSPlacePropertyServesDinner
,GMSPlacePropertyServesLunch
,GMSPlacePropertyServesVegetarianFood
,GMSPlacePropertyServesWine
,GMSPlacePropertyTakeout
يجتاز المثال التالي قائمة من اثنين
قيم الحقول
لتحديد أن الكائن GMSPlace
الذي يعرضه طلب يحتوي على
حقلا name
وplaceID
:
Swift
// Specify the place data types to return. let fields: [GMSPlaceProperty] = [.placeID, .name]
Objective-C
// Specify the place data types to return. NSArray<GMSPlaceProperty *> *fields = @[GMSPlacePropertyPlaceID, GMSPlacePropertyName];
GooglePlacesSwift
// Specify the place data types to return. let fields: [PlaceProperty] = [.placeID, .displayName]
المعلمات الاختيارية
استخدِم الكائن GMSFetchPlaceRequest
لتحديد المَعلمات الاختيارية.
regionCode
رمز المنطقة المستخدَم لتنسيق الردّ، والذي يتم تحديده على أنّه رمز CLDR مؤلف من حرفين. يمكن أن يكون لهذه المعلمة أيضًا تأثير تحيز في نتائج البحث. لا يوجد قيمة افتراضية.
إذا تطابق اسم البلد في حقل العنوان في الرد مع كود المنطقة، فسيتم حذف رمز البلد من العنوان.
وتكون معظم رموز CLDR متطابقة مع رموز ISO 3166-1، مع بعض الاستثناءات الملحوظة. على سبيل المثال، نطاق المستوى الأعلى الذي يتم ترميزه حسب البلد (ccTLD) في المملكة المتحدة هو "uk" (co.uk.)، لكنّ رمزها وفقًا لمعيار ISO 3166-1 هو gb. (من الناحية الفنية بالنسبة كيان "المملكة المتحدة لبريطانيا العظمى وأيرلندا الشمالية"). ويمكن أن تؤثّر المَعلمة في النتائج استنادًا إلى القانون الساري.
sessionToken
الرموز المميزة للجلسة هي سلاسل من إنشاء المستخدمين تتتبّع الإكمال التلقائي (جديد) كـ "جلسات". تستخدم ميزة الإكمال التلقائي (جديدة) الرموز المميّزة للجلسة تجميع مراحل طلب البحث وتحديد الأماكن لعملية بحث المستخدم التي تتم من خلال ميزة "الإكمال التلقائي" في جلسة منفصلة لأغراض الفوترة. يتم تمرير الرموز المميّزة للجلسة إلى تفاصيل المكان (جديد) التي تتبع مكالمات الإكمال التلقائي (الجديدة). لمزيد من المعلومات، يُرجى مراجعة الرموز المميّزة للجلسة:
عرض عمليات تحديد المصدر في تطبيقك
عندما يعرض تطبيقك معلومات تم الحصول عليها من
GMSPlacesClient
،
مثل الصور والمراجعات، يجب أن يعرض التطبيق أيضًا معلومات المساهمين المطلوبة.
على سبيل المثال، السمة reviews
للكائن GMSPlacesClient
يحتوي على صفيف من خمسة
GMSPlaceReview
الأخرى. يمكن أن يحتوي كل عنصر GMSPlaceReview
على السمات وسمات المؤلف.
إذا عرضت المراجعة في تطبيقك، يجب أيضًا عرض أي مصدر أو مؤلف.
الإحالة.
لمزيد من المعلومات، راجع الوثائق المتعلقة الإحالة.