تفاصيل المكان

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

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

تفاصيل المكان

توفّر صف GMSPlace معلومات حول مكان محدّد. يمكنك الحصول على كائن GMSPlace بالطرق التالية:

عند طلب مكان، عليك تحديد أنواع بيانات الأماكن المطلوب عرضها. لإجراء ذلك، مرِّر 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 – اسم المكان.
  • placeID – معرّف النص للمكان. يمكنك الاطّلاع على مزيد من المعلومات حول معرّفات الأماكن في بقية هذه الصفحة.
  • coordinate – الموقع الجغرافي للمكان، ويتم تحديده على أنه إحداثيات خطوط الطول والعرض.
  • phoneNumber – رقم هاتف المكان، بتنسيق دولي.
  • formattedAddress – عنوان هذا الموقع الذي يمكن للمستخدمين قراءته.

    ويساوي هذا العنوان غالبًا العنوان البريدي. لاحظ أن بعض البلدان، مثل المملكة المتحدة، لا تسمح بتوزيع عناوين بريدية صحيحة بسبب قيود الترخيص.

    يتكون العنوان المنسّق بشكل منطقي من مكوّن عنوان واحد أو أكثر. على سبيل المثال، يتكوّن العنوان "111 8th Avenue, New York, NY" من المكوّنات التالية: "111" (رقم الشارع) و"8th Avenue" (المسار) و"New York" (المدينة) و"NY" (ولاية الولايات المتحدة).

    عدم تحليل العنوان المنسَّق آليًا. وبدلاً من ذلك، عليك استخدام مكوّنات العناوين الفردية، التي تتضمّن استجابة واجهة برمجة التطبيقات بالإضافة إلى حقل العنوان المنسَّق.

  • openingHours – ساعات العمل الخاصة بالمكان (كما يمثّلها GMSOpeningHours). يمكنك الاتصال بـ GMSOpeningHours.weekdayText للحصول على قائمة بالسلاسل المترجمة لساعات العمل اليومية للأسبوع. اتصل بـ GMSOpeningHours.Periods لعرض قائمة تضم GMSPeriod تضم معلومات أكثر تفصيلاً والتي تعادل البيانات التي يقدمها weekdayText. ملاحظة: إذا كان أحد الأماكن مفتوحًا دائمًا، يتم تمثيل الفترة الزمنية على أنها الأحد في منتصف الليل، وتكون closeEvent فارغة.

  • addressComponents – مصفوفة من GMSAddressComponent كائنات تمثّل مكوّنات عنوان المكان. يتم تقديم هذه المكوّنات بغرض استخراج المعلومات المنظَّمة حول عنوان المكان، مثلاً للعثور على المدينة التي يقع فيها هذا المكان. لا تستخدم هذه المكوّنات لتنسيق العنوان، بل استخدِم الخاصية formattedAddress التي تقدّم عنوانًا منسقًا باللغة المحلية.

    يُرجى ملاحظة الحقائق التالية حول مصفوفة addressComponents:

    • قد تحتوي مصفوفة مكونات العنوان على مكونات أكثر من formattedAddress.
    • لا تشمل المصفوفة بالضرورة جميع الكيانات السياسية التي تحتوي على عنوان، باستثناء الكيانات المُدرَجة في formattedAddress.
    • لا يمكن ضمان بقاء تنسيق الاستجابة كما هو بين الطلبات. على وجه الخصوص، يختلف عدد addressComponents بناءً على العنوان المطلوب ويمكن أن يتغيّر بمرور الوقت للعنوان نفسه. يمكن لأحد المكونات تغيير الموضع في المصفوفة. يمكن تغيير نوع المكوِّن. قد يكون أحد المكوّنات غير متوفّر في استجابة لاحقة.
  • userRatingsTotal – تمثّل عدد المراجعات التي تشكّل تقييم المكان.

تحتوي الفئة GMSPlace على وظائف الأعضاء التالية:

  • تحتسب isOpen ما إذا كان المكان مفتوحًا أم لا في الوقت المحدّد، استنادًا إلى openingHours وUTCOffsetMinutes، بالإضافة إلى التاريخ والوقت الحاليين.
  • تحسب isOpenAtDate ما إذا كان المكان مفتوحًا في تاريخ محدّد أم لا، استنادًا إلى openingHours وUTCOffsetMinutes والتاريخ والوقت الحاليين.

    • عند استخدام هذه الدوال للحصول على أوقات العمل و/أو التواريخ، يجب أن يحدّد الطلب الأصلي fetchPlaceFromPlaceID: أو findPlaceLikelihoodsFromUserLocationWithPlaceFields: الحقلين GMSPlaceFieldOpeningHours وGMSPlaceFieldUTCOffsetMinutes. في حال عدم توفّر أي من هذه الحقول، لن يحتوي كائن GMSPlace الناتج على أوقات الفتح أو التواريخ، وسيعرض الاستدعاء GMSPlaceOpenStatusUnknown. لضمان الحصول على نتائج دقيقة، اطلب حقلي GMSPlaceFieldBusinessStatus وGMSPlaceFieldUTCOffsetMinutes في طلب المكان الأصلي. وإذا لم يتم طلبها، يُفترض أنّ النشاط التجاري يعمل.

    يمكنك الاطّلاع على هذا الفيديو لمعرفة كيفية استخدام isOpen مع تفاصيل المكان.

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

رقم تعريف المكان هو معرّف نصي يعرّف المكان بشكل فريد. في حزمة تطوير البرامج (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 هو نفسه المعرّف المستخدم في واجهة برمجة تطبيقات الأماكن، وحزمة تطوير برامج الأماكن لـ Android وغيرها من واجهات برمجة تطبيقات Google.

يمكن أن يشير معرّف المكان إلى مكان واحد فقط، ولكن يمكن أن يكون لمكان واحد أكثر من معرّف مكان واحد.

هناك حالات قد تؤدي إلى حصول مكان على رقم تعريف مكان جديد. على سبيل المثال، قد يحدث هذا إذا انتقل نشاط تجاري إلى موقع جديد.

عندما تطلب مكانًا من خلال تحديد معرّف مكان، يمكنك أن تكون واثقًا من أنك ستتلقى دائمًا نفس المكان في الاستجابة (إذا كان المكان لا يزال موجودًا). يُرجى العِلم بأن الاستجابة قد تحتوي على رقم تعريف مكان مختلف عن المعرّف الوارد في طلبك.

ولمزيد من المعلومات، يمكنك الاطّلاع على نظرة عامة على رقم تعريف المكان.