تمت ترجمة هذه الصفحة بواسطة Cloud Translation API‏.

تفاصيل المكان (جديد)

اختَر النظام الأساسي: Android iOS JavaScript خدمة الويب

توفّر حزمة تطوير برامج الأماكن لأجهزة iOS (الجديدة) تطبيقك معلومات غنية عن الأماكن، بما في ذلك اسم المكان وعنوانه والموقع الجغرافي المحدّد كإحداثيات خطوط الطول والعرض ونوع المكان (مثل ملهى ليلي ومتجر حيوانات أليفة ومتحف والمزيد). للوصول إلى هذه المعلومات الخاصة بمكان معيّن، يمكنك استخدام معرّف المكان، وهو معرّف ثابت يعرّف المكان بشكل فريد.

الحصول على تفاصيل المكان

تتضمن الفئة GMSPlace معلومات حول مكان معيّن، بما في ذلك جميع حقول البيانات المعروضة في حقول بيانات الأماكن (جديدة). احصل على عنصر GMSPlace من خلال استدعاء GMSPlacesClient fetchPlaceWithRequest:، وتمرير عنصر GMSFetchPlaceRequest، وطريقة معاودة الاتصال من نوع GMSPlaceResultCallback.

يحدّد الكائن GMSFetchPlaceRequest ما يلي:

(مطلوب) رقم تعريف المكان، وهو معرّف فريد لمكان في قاعدة بيانات "أماكن Google" وعلى "خرائط Google".
(مطلوبة) قائمة الحقول المطلوب عرضها في الكائن GMSPlace، وتسمى أيضًا قناع الحقل، كما هو محدّد في GMSPlaceProperty. إذا لم تحدّد حقلاً واحدًا على الأقل في قائمة الحقول، أو إذا حذفت قائمة الحقول، سيعرض الطلب رسالة خطأ.
(اختياري) رمز المنطقة المستخدَم لتنسيق الرد.
(اختياري) الرمز المميّز للجلسة المستخدَم لإنهاء جلسة الإكمال التلقائي (جديدة)

تقديم طلب للحصول على تفاصيل المكان

يحصل هذا المثال على مكان بواسطة رقم التعريف، من خلال تمرير المعلّمات التالية:

تمثّل هذه السمة رقم تعريف المكان ChIJV4k8_9UodTERU5KXbkYpSYs.
قائمة حقول تحدد عرض اسم المكان وعنوان URL للموقع الإلكتروني.
تمثّل هذه السمة GMSPlaceResultCallback لمعالجة النتيجة.

تستدعي واجهة برمجة التطبيقات طريقة معاودة الاتصال المحدّدة، ويتم تمرير كائن GMSPlace. إذا لم يتم العثور على المكان، فهذا يعني أن عنصر المكان لا قيمة.

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 فارغة. على سبيل المثال، إذا كانت قائمة الحقول تتضمّن GMSPlacePropertyPhotos لطلب الحقل photos في الاستجابة، وكان الحقل photos في الاستجابة فارغًا، سيتم حذفه من العنصر 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 على عمليات تحديد المصدر وذِكر أسماء المؤلفين. إذا عرضت المراجعة في تطبيقك، عليك أيضًا عرض أي معلومات عن مصدر أو اسم مؤلف.

لمزيد من المعلومات، اطّلِع على المستندات حول جهات تحديد المصدر.