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

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

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

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

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

يحدِّد الكائن GMSFetchPlaceRequest ما يلي:

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

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

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

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

تستدعي واجهة برمجة التطبيقات طريقة معاودة الاتصال المحددة، وتمرير GMSPlace الخاص بك. إذا لم يتم العثور على المكان، يكون كائن المكان nil.

Swift

// 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))")
})

Objective-C

// 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);
  }
}];

حزمة تطوير برامج الأماكن Swift لنظام التشغيل iOS (معاينة)

// 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 للتعامل مع الردّ.
    • &gt;

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

  • GMSPlacePropertyUTCOffsetMinutes
  • GMSPlacePropertyBusinessStatus
  • GMSPlacePropertyOpeningHours
  • GMSPlacePropertyCurrentOpeningHours
  • GMSPlacePropertySecondaryOpeningHours

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

ردّ واحد (isOpenWithRequest)

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

Language القيمة إذا كانت مفتوحة القيمة في حال الإغلاق القيمة إذا كانت الحالة غير معروفة
Swift .open .closed .unknown
Objective-C GMSPlaceOpenStatusOpen GMSPlaceOpenStatusClosed GMSPlaceOpenStatusUnknown
GooglePlacesSwift (معاينة) true false nil

فوترة "isOpenWithRequest"

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

يوضّح المثال التالي كيفية إعداد GMSPlaceIsOpenWithRequest ضمن عنصر GMSPlace حالي.

Swift

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

Objective-C

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

GooglePlacesSwift

          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 لتحديد المعلَمات المطلوبة.

معرّف المكان

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

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

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

قائمة الحقول

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

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

يجتاز المثال التالي قائمة من اثنين قيم الحقول لتحديد أن الكائن GMSPlace الذي يعرضه طلب يحتوي على حقلا name وplaceID:

Swift

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

Objective-C

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

حزمة تطوير برامج الأماكن Swift لنظام التشغيل iOS (معاينة)

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

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

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

regionCode

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

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

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

sessionToken

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

عرض عمليات تحديد المصدر في تطبيقك

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

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

لمزيد من المعلومات، راجع الوثائق المتعلقة الإحالة.