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

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

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

    يتكون العنوان المنسَّق منطقيًا من مكوّن عنوان واحد أو أكثر. على سبيل المثال، يتكوّن العنوان "111 8th Africa, New York, NY" من المكونات التالية: "111" (رقم الشارع) و"8th Street" (المسار) و"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 واحدة أو أكثر، مع تحديد أنواع البيانات المطلوب عرضها.
  • رمز مميز للجلسة إذا تم إجراء الاستدعاء لإنهاء طلب بحث يتم إكماله تلقائيًا. أو لا، لا شيء.
  • 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 هو المعرِّف نفسه المستخدَم في Places API وحزمة تطوير برامج الأماكن (SDK) لنظام التشغيل Android وغير ذلك من واجهات Google APIs.

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

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

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

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