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

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

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

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

• اتّصِل على GMSPlacesClient findPlaceLikelihoodsFromUserLocationWithPlaceFields:. راجِع دليل الحصول على المكان الحالي.
• استدعِ الدالة Call GMSPlacesClient fetchPlaceFromPlaceID:، مع تمرير GMSPlaceField ورقم تعريف المكان وطريقة رد الاتصال. بالنسبة إلى طلبات "تفاصيل المكان"، إذا لم تحدّد حقلاً واحدًا على الأقل في الطلب، أو إذا حذفت المَعلمة fields من الطلب، سيتم عرض جميع الحقول الممكنة، وسيتم تحصيل الرسوم منك وفقًا لذلك. اطّلِع على دليل الحصول على مكان حسب رقم التعريف.

تحذير: في حال عدم تحديد حقل واحد على الأقل في الطلب، أو إذا حذفت المَعلمة 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);
  

لا تتوافق السمة

GMSPlaceFieldTakeout وGMSPlaceFieldDelivery وGMSPlaceFieldDineIn وGMSPlaceFieldCurbsidePickup وGMSPlaceFieldPhoneNumber وGMSPlaceFieldWebsite وGMSPlaceFieldOpeningHours وGMSPlaceFieldAddressComponents مع عناصر الأماكن GMSPlaceLikelihoodList.

مزيد من المعلومات حول حقول الأماكن لمزيد من المعلومات حول كيفية احتساب تكلفة طلبات بيانات "الأماكن"، يُرجى الاطّلاع على الاستخدام والفوترة.

يمكن أن يحتوي الصف 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 الأخرى.

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

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

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

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