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

توفّر حزمة تطوير البرامج (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: اسم المكان
  • ‫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 تغييرات الجدول الزمني خلال العطلات والمواسم. يمكن فلترة ساعات العمل الاستثنائية لهذه الأيام الخاصة وعرضها إذا كانت متاحة.

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 واحد أو أكثر لتحديد أنواع البيانات التي سيتم عرضها
  • رمز أمان الجلسة إذا تم إجراء المكالمة لإكمال طلب بحث إكمال تلقائي. بخلاف ذلك، يمكنك تمرير القيمة "nil".
  • GMSPlaceResultCallback للتعامل مع النتيجة

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

حزمة تطوير البرامج (SDK) لأماكن Google باستخدام 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 الأخرى.

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

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

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

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