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

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

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

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

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

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

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
    }
}

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

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

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

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

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

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