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

توفّر حزمة تطوير البرامج (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 8th Avenue, New York, NY" من المكوّنات التالية: "111" (رقم الشارع) و"8th Avenue" (الطريق) و"New York" (المدينة) و "NY" (الولاية الأمريكية).

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

  • ‫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) لـ 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:، يجب أن يعرض التطبيق أيضًا معلومات تحديد المصدر. يمكنك الاطّلاع على المستندات حول عمليات تحديد المصدر.

مزيد من المعلومات عن أرقام تعريف الأماكن

رقم تعريف المكان المستخدَم في حزمة تطوير البرامج بالاستناد إلى الموقع الجغرافي لنظام التشغيل iOS هو المعرّف نفسه المستخدَم في Places API وحزمة تطوير البرامج بالاستناد إلى الموقع الجغرافي لنظام التشغيل Android وواجهات Google APIs الأخرى.

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

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

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

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