تفاصيل المكان (جديد)

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

الحصول على تفاصيل المكان

تحتوي فئة GMSPlace على معلومات عن مكان معيّن، بما في ذلك جميع حقول البيانات المعروضة في حقول بيانات الأماكن (جديد). يمكنك الحصول على كائن GMSPlace من خلال استدعاء GMSPlacesClient fetchPlaceWithRequest:، مع تمرير كائن GMSFetchPlaceRequest وطريقة callback من النوع GMSPlaceResultCallback.

يحدِّد عنصر GMSFetchPlaceRequest ما يلي:

• (سمة مطلوبة) رقم تعريف المكان، وهو معرّف فريد للمكان في قاعدة بيانات أماكن Google وعلى "خرائط Google".
• (مطلوبة) قائمة الحقول التي سيتم عرضها في عنصر GMSPlace، وتُعرف أيضًا باسم قناع الحقل، على النحو المحدّد من قِبل GMSPlaceProperty. إذا لم تحدِّد حقلًا واحدًا على الأقل في قائمة الحقول، أو إذا حذفت قائمة الحقول، سيعرض الطلب خطأ.
• (اختياري) رمز المنطقة المستخدَم لتنسيق الردّ
• (اختياري) الرمز المميّز للجلسة المستخدَم لإنهاء جلسة "الملء التلقائي (جديد)"

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

يحصل هذا المثال على مكان حسب رقم التعريف، مع تمرير المَعلمات التالية:

• معرّف المكان ChIJV4k8_9UodTERU5KXbkYpSYs
• قائمة حقول تحدّد عرض اسم المكان وعنوان URL للموقع الإلكتروني
• GMSPlaceResultCallback للتعامل مع النتيجة

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

// A hotel in Saigon with an attribution.
let placeID = "ChIJV4k8_9UodTERU5KXbkYpSYs"

// Specify the place data types to return.
let myProperties = [GMSPlaceProperty.name, GMSPlaceProperty.website].map {$0.rawValue}

// Create the GMSFetchPlaceRequest object.
let fetchPlaceRequest = GMSFetchPlaceRequest(placeID: placeID, placeProperties: myProperties, sessionToken: nil)

client.fetchPlace(with: fetchPlaceRequest, callback: {
  (place: GMSPlace?, error: Error?) in
  guard let place, error == nil else { return }
  print("Place found: \(String(describing: place.name))")
})

// A hotel in Saigon with an attribution.
NSString *placeID = @"ChIJV4k8_9UodTERU5KXbkYpSYs";

// Specify the place data types to return.
NSArray<NSString *> *myProperties = @[GMSPlacePropertyName, GMSPlacePropertyWebsite];

// Create the GMSFetchPlaceRequest object.
GMSFetchPlaceRequest *fetchPlaceRequest = [[GMSFetchPlaceRequest alloc] initWithPlaceID:placeID placeProperties: myProperties sessionToken:nil];

[placesClient fetchPlaceWithRequest: fetchPlaceRequest callback: ^(GMSPlace *_Nullable place, NSError *_Nullable error) {
    if (error != nil) {
      NSLog(@"An error occurred %@", [error localizedDescription]);
      return;
    } else {
    NSLog(@"Place Found: %@", place.name);
    NSLog(@"The place URL: %@", place.website);
  }
}];

// A hotel in Saigon with an attribution.
let placeID = "ChIJV4k8_9UodTERU5KXbkYpSYs"
let fetchPlaceRequest = FetchPlaceRequest(
  placeID: placeID,
  placeProperties: [.name, .website]
)
switch await placesClient.fetchPlace(with: fetchPlaceRequest) {
case .success(let place):
  // Handle place
case .failure(let placesError):
  // Handle error
}

استجابة تفاصيل المكان

تعرِض سمة "تفاصيل المكان" عنصرًا من نوع GMSPlace يحتوي على تفاصيل عن المكان. لا تتم تعبئة سوى الحقول المحدّدة في قائمة الحقول في عنصر GMSPlace.

الحصول على حالة "مفتوح"

يحتوي عنصر GMSPlacesClient على دالة عضوية تُسمى isOpenWithRequest (isOpenRequest في Swift وisPlaceOpenRequest في GooglePlacesSwift) تعرض استجابة تشير إلى ما إذا كان المكان مفتوحًا حاليًا استنادًا إلى الوقت المحدّد في الطلب.

تأخذ هذه الطريقة وسيطة واحدة من النوع GMSPlaceIsOpenWithRequest تحتوي على ما يلي:

• عنصر GMSPlace أو سلسلة تحدّد معرّف مكان لمزيد من المعلومات عن إنشاء عنصر "الموقع الجغرافي" باستخدام الحقول اللازمة، يُرجى الاطّلاع على تفاصيل الموقع الجغرافي.
  
• عنصر اختياري من النوع NSDate (Obj-C) أو Date (Swift) يحدِّد الوقت الذي تريد التحقّق منه. إذا لم يتم تحديد وقت، يكون الإعداد التلقائي هو الآن.
• طريقة GMSPlaceOpenStatusResponseCallback لمعالجة الاستجابة
>

تتطلّب طريقة GMSPlaceIsOpenWithRequest ضبط الحقول التالية في كائن GMSPlace:

• GMSPlacePropertyUTCOffsetMinutes
• GMSPlacePropertyBusinessStatus
• GMSPlacePropertyOpeningHours
• GMSPlacePropertyCurrentOpeningHours
• GMSPlacePropertySecondaryOpeningHours

إذا لم يتم توفير هذه الحقول في عنصر "الموقع الجغرافي"، أو إذا تم ضبط معرّف مكان، تستخدم الطريقة GMSPlacesClient GMSFetchPlaceRequest: لجلبها.

ردّ واحد (isOpenWithRequest)

تعرض isOpenWithRequest عنصر GMSPlaceIsOpenResponse يحتوي على قيمة منطقية باسم status تشير إلى ما إذا كان النشاط التجاري مفتوحًا أو مغلقًا أو إذا كانت الحالة غير معروفة.

الفوترة لحساب isOpenWithRequest

• يتم تحصيل رسوم حقلَي GMSPlacePropertyUTCOffsetMinutes وGMSPlacePropertyBusinessStatus ضمن رمز التخزين التعريفي للبيانات الأساسية. يتم تحصيل رسوم بقية ساعات العمل ضمن رمز التخزين التعريفي لـ "تفاصيل المكان (متقدّمة)".
• إذا كان GMSPlace العنصر يحتوي على هذه الحقول من طلب سابق، لن يتم تحصيل رسوم منك مرة أخرى.

مثال: تقديم طلب GMSPlaceIsOpenWithRequest

    let isOpenRequest = GMSPlaceIsOpenRequest(place: place, date: nil)
      GMSPlacesClient.shared().isOpen(with: isOpenRequest) { response, error in
        if let error = error {
          // Handle Error
        }
        switch response.status {
          case .open:
            // Handle open
          case .closed:
            // Handle closed
          case .unknown:
            // Handle unknown
        }
      }
        

          GMSPlaceIsOpenRequest *isOpenRequest = [[GMSPlaceIsOpenRequest alloc] initWithPlace:place date:nil];
  
          [[GMSPlacesClient sharedClient] isOpenWithRequest:isOpenRequest callback:^(GMSPlaceIsOpenResponse response, NSError *_Nullable error) {
            if (error) {
              // Handle error
            }
  
            switch (response.status) {
              case GMSPlaceOpenStatusOpen:
                // Handle open
              case GMSPlaceOpenStatusClosed:
                // Handle closed
              case GMSPlaceOpenStatusUnknown:
                // Handle unknown
            }
          }];
          

          let isOpenRequest = IsPlaceOpenRequest(place: place)
          switch await placesClient.isPlaceOpen(with: isOpenRequest) {
            case .success(let isOpenResponse):
              switch isOpenResponse.status {
                case true:
                  // Handle open
                case false:
                  // Handle closed
                case nil:
                  // Handle unknown
            case .failure(let placesError):
              // Handle error
          }
          

المعلمات المطلوبة

استخدِم العنصر GMSFetchPlaceRequest لتحديد المَعلمات المطلوبة.

معرّف المكان

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

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

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

قائمة الحقول

عند طلب تفاصيل المكان، يجب تحديد البيانات التي تريد إعادتها في عنصر GMSPlace للمكان كقناع حقل. لتحديد قناع الحقل، اضبط صفيفًا من القيم من GMSPlaceProperty إلى كائن GMSFetchPlaceRequest. إنّ إخفاء الحقول هو ممارسة تصميم جيدة لضمان عدم طلب بيانات غير ضرورية، ما يساعد في تجنب وقت المعالجة غير الضروري ورسوم الفوترة.

حدِّد حقلًا واحدًا أو أكثر من الحقول التالية:

• تؤدي الحقول التالية إلى تنشيط رمز التخزين التعريفي لـ "تفاصيل المكان (رقم التعريف فقط)":

  GMSPlacePropertyPlaceID، GMSPlacePropertyName، GMSPlacePropertyPhotos

• تؤدي الحقول التالية إلى تنشيط رمز التخزين التعريفي لـ "تفاصيل المكان (الموقع الجغرافي فقط)":

  GMSPlacePropertyAddressComponents، GMSPlacePropertyFormattedAddress، GMSPlacePropertyCoordinate، GMSPlacePropertyPlusCode، GMSPlacePropertyTypes، GMSPlacePropertyViewport

• تؤدي الحقول التالية إلى تنشيط رمز التخزين التعريفي لـ "تفاصيل المكان (أساسية)":

  GMSPlacePropertyBusinessStatus، GMSPlacePropertyIconBackgroundColor، GMSPlacePropertyIconImageURL، GMSPlacePropertyUTCOffsetMinutes، GMSPlacePropertyWheelchairAccessibleEntrance

• تؤدي الحقول التالية إلى تنشيط رمز التخزين التعريفي لـ "تفاصيل المكان" (متقدّمة):

  GMSPlacePropertyCurrentOpeningHours، GMSPlacePropertySecondaryOpeningHours، GMSPlacePropertyPhoneNumber، GMSPlacePropertyPriceLevel، GMSPlacePropertyRating، GMSPlacePropertyOpeningHours، GMSPlacePropertyUserRatingsTotal، GMSPlacePropertyWebsite

• تؤدي الحقول التالية إلى تنشيط رمز التخزين التعريفي (المفضّل) لتفاصيل المكان:

  GMSPlacePropertyCurbsidePickup، GMSPlacePropertyDelivery، GMSPlacePropertyDineIn، GMSPlacePropertyEditorialSummary، GMSPlacePropertyReservable، GMSPlacePropertyReviews، GMSPlacePropertyServesBeer، GMSPlacePropertyServesBreakfast، GMSPlacePropertyServesBrunch، GMSPlacePropertyServesDinner، GMSPlacePropertyServesLunch، GMSPlacePropertyServesVegetarianFood، GMSPlacePropertyServesWine، GMSPlacePropertyTakeout

يُرسِل المثال التالي قائمة بوحدتَي قيمة حقل لتحديد أنّ عنصر GMSPlace الذي يعرضه الطلب يحتوي على الحقلَين name وplaceID:

// Specify the place data types to return.
let fields: [GMSPlaceProperty] = [.placeID, .name]
  

// Specify the place data types to return.
NSArray<GMSPlaceProperty *> *fields = @[GMSPlacePropertyPlaceID, GMSPlacePropertyName];
  

// Specify the place data types to return.
let fields: [PlaceProperty] = [.placeID, .displayName]
    

المعلمات الاختيارية

استخدِم العنصر GMSFetchPlaceRequest لتحديد المَعلمات الاختيارية.

regionCode

رمز المنطقة المستخدَم لتنسيق الاستجابة، ويتم تحديده على أنّه قيمة رمز CLDR المكوّن من حرفَين. يمكن أن تؤثر هذه المَعلمة أيضًا بشكلٍ متحيّز في نتائج البحث. لا تتوفّر قيمة تلقائية.

إذا كان اسم البلد في حقل العنوان في الردّ يتطابق مع رمز المنطقة، يتم حذف رمز البلد من العنوان.

تتطابق معظم رموز CLDR مع رموز ISO 3166-1، مع بعض الاستثناءات البارزة. على سبيل المثال، رمز المستوى الأعلى للمنطقة الجغرافية للمملكة المتحدة هو "uk" (‎.co.uk)، بينما رمزه وفقًا لمعيار ISO 3166-1 هو "gb" (من الناحية الفنية لموضوع "المملكة المتحدة لبريطانيا العظمى وأيرلندا الشمالية"). يمكن أن تؤثّر المَعلمة في النتائج استنادًا إلى القانون الساري.

sessionToken

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

عرض الإسنادات في تطبيقك

عندما يعرض تطبيقك معلومات تم الحصول عليها من GMSPlacesClient، مثل الصور والمراجعات، يجب أن يعرض التطبيق أيضًا الإسنادات المطلوبة.

على سبيل المثال، تحتوي السمة reviews للكائن GMSPlacesClient على صفيف يصل إلى خمسة كائنات GMSPlaceReview. يمكن أن يحتوي كل عنصر GMSPlaceReview على إحالات واقتباسات للمؤلف. إذا عرضت المراجعة في تطبيقك، يجب أيضًا عرض أيّ مصدر أو مصدر للمؤلف.

لمزيد من المعلومات، يُرجى الاطّلاع على المستندات المتعلّقة بموضوع الإحالات.