جزئیات جا (جدید)

پلاتفرم را انتخاب کنید: Android iOS JavaScript سرویس وب
توسعه‌دهندگان منطقه اقتصادی اروپا (EEA)

«کیت توسعه نرم‌افزار مکان‌ها برای iOS» (جدید) اطلاعات غنی‌ای درباره مکان‌ها دراختیار برنامه‌تان قرار می‌دهد، ازجمله نام و نشانی مکان، مکان جغرافیایی مشخص‌شده به‌صورت مختصات طول/عرض جغرافیایی، نوع مکان (مثل کلوپ شبانه، فروشگاه حیوانات خانگی، موزه)، و موارد دیگر. برای دسترسی به این اطلاعات برای مکانی خاص، می‌توانید از شناسه مکان استفاده کنید، شناسه پایداری که مکان را به‌صورت یکتا شناسایی می‌کند.

دریافت جزئیات مکان

این GMSPlace کلاس حاوی اطلاعاتی درباره مکان خاصی است، ازجمله همه فیلدهای داده نشان‌داده‌شده در فیلدهای داده مکان (جدید). با فراخوانی GMSPlacesClient fetchPlaceWithRequest:، ارسال شیء GMSFetchPlaceRequest، و روش فراخوانی از نوع GMSPlaceResultCallback، شیء GMSPlace دریافت کنید.

شیء GMSFetchPlaceRequest مشخص می‌کند:

  • (الزامی) شناسه مکان، شناسه یکتایی برای مکان در پایگاه داده Google Places و در Google Maps.
  • (الزامی) فهرست فیلدهایی که باید در شیء GMSPlace برگردانده شود، که به آن پوشش فیلد نیز گفته می‌شود، همان‌طور که توسط GMSPlaceProperty تعریف شده است. اگر حداقل یک فیلد را در فهرست فیلد مشخص نکنید، یا اگر فهرست فیلد را حذف کنید، تماس خطا برمی‌گرداند.
  • (اختیاری) کد منطقه‌ای که برای قالب‌بندی پاسخ استفاده می‌شود.
  • (اختیاری) کد جلسه استفاده‌شده برای پایان دادن به جلسه «تکمیل خودکار (جدید)».

درخواست «جزئیات مکان» ایجاد کنید

این مثال مکان را براساس شناسه دریافت می‌کند و پارامترهای زیر را ارسال می‌کند:

  • شناسه مکان ChIJV4k8_9UodTERU5KXbkYpSYs.
  • فهرست فیلدی که مشخص می‌کند نام مکان و نشانی وب‌سایت برگردانده شود.
  • GMSPlaceResultCallback برای مدیریت نتیجه.

«میانای برنامه‌سازی کاربردی» روش فراخوانی مشخص‌شده را فرا می‌خواند و GMSPlace شیئی را به آن منتقل می‌کند. اگر مکان پیدا نشود، شیء مکان تهی است.

کیت توسعه نرم‌افزار Swift مکان‌ها

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

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

آبجکتیو-سی

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

پاسخ «جزئیات جا»

«جزئیات مکان» یک 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 است که نشان می‌دهد کسب‌وکار باز است، بسته است، یا وضعیت آن نامشخص است.

زبان مقدار درصورت باز بودن مقدار درصورت بسته بودن مقدار درصورت نامشخص بودن وضعیت
Places Swift true false nil
Swift .open .closed .unknown
آبجکتیو-سی GMSPlaceOpenStatusOpen GMSPlaceOpenStatusClosed GMSPlaceOpenStatusUnknown

صدور صورت‌حساب برای isOpenWithRequest

مثال: درخواست GMSPlaceIsOpenWithRequest بده

مثال زیر نحوه مقداردهی اولیه GMSPlaceIsOpenWithRequest را در شیء GMSPlace موجود نشان می‌دهد.

کیت توسعه نرم‌افزار Places Swift

        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
        }

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

آبجکتیو-سی

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

پارامترهای الزامی

از شیء GMSFetchPlaceRequest برای مشخص کردن پارامترهای الزامی استفاده کنید.

شناسه مکان

شناسه مکان استفاده‌شده در «کیت توسعه نرم‌افزار مکان‌ها برای iOS» همان شناسه استفاده‌شده در «میانای برنامه‌سازی کاربردی مکان‌ها»، «کیت توسعه نرم‌افزار مکان‌ها برای Android»، و دیگر «میاناهای برنامه‌سازی کاربردی Google» است. هر شناسه مکان فقط می‌تواند به یک مکان اشاره کند، اما یک مکان می‌تواند بیش‌از یک شناسه مکان داشته باشد.

شرایطی وجود دارد که ممکن است باعث شود مکانی شناسه مکان جدیدی دریافت کند. برای مثال، این اتفاق ممکن است زمانی رخ دهد که کسب‌وکار به مکان جدیدی منتقل شود.

وقتی مکانی را با مشخص کردن شناسه مکان درخواست می‌کنید، می‌توانید مطمئن باشید که همیشه همان مکان را در پاسخ دریافت خواهید کرد (اگر مکان هنوز وجود داشته باشد). توجه داشته باشید که پاسخ ممکن است حاوی شناسه مکانی باشد که با شناسه مکان موجود در درخواست شما متفاوت است.

فهرست فیلد

وقتی جزئیات مکان را درخواست می‌کنید، باید داده‌هایی را که باید در شیء GMSPlace برای مکان به‌عنوان ماسک فیلد برگردانده شود مشخص کنید. برای تعریف کردن پوشش فیلد، آرایه‌ای از مقادیر از GMSPlaceProperty به شیء GMSFetchPlaceRequest ارسال کنید. پوشاندن فیلد یک روش طراحی خوب است که مطمئن شوید داده‌های غیرضروری را درخواست نمی‌کنید، که به اجتناب از زمان پردازش غیرضروری و هزینه‌های صورت‌حساب کمک می‌کند.

یک یا چند فیلد زیر را مشخص کنید:

مثال زیر فهرستی از دو مقدار فیلد را برای مشخص کردن اینکه شیء GMSPlace برگردانده‌شده توسط درخواست حاوی فیلدهای name و placeID است ارسال می‌کند:

کیت توسعه نرم‌افزار Swift مکان‌ها

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

Swift

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

آبجکتیو-سی

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

پارامترهای اختیاری

از شیء GMSFetchPlaceRequest برای مشخص کردن پارامترهای اختیاری استفاده کنید.

regionCode

کد منطقه استفاده‌شده برای قالب‌بندی پاسخ، که به‌عنوان مقدار کد CLDR دو نویسه‌ای مشخص شده است. این پارامتر همچنین می‌تواند تأثیر جانبداری بر نتایج جستجو داشته باشد. مقدار پیش‌فرضی وجود ندارد.

اگر نام کشور فیلد نشانی در پاسخ با کد منطقه مطابقت داشته باشد، کد کشور از نشانی حذف می‌شود.

اکثر کدهای CLDR با کدهای ISO 3166-1 یکسان هستند، با چند استثنای قابل‌توجه. برای مثال، ccTLD پادشاهی متحد «uk»‏ (.co.uk) است، درحالی‌که کد ISO 3166-1 آن «gb» است (ازنظر فنی برای نهاد «پادشاهی متحد بریتانیای کبیر و ایرلند شمالی»). این پارامتر می‌تواند براساس قانون ذی‌ربط بر نتایج تأثیر بگذارد.

sessionToken

کدهای جلسه رشته‌های تولیدشده توسط کاربر هستند که تماس‌های «تکمیل خودکار» (جدید) را به‌عنوان «جلسه» پیگیری می‌کنند. «تکمیل خودکار» (جدید) از نشان‌های جلسه برای گروه‌بندی مراحل انتخاب مکان و پُرسمان جستجوی تکمیل خودکار کاربر در یک جلسه مجزا برای اهداف صدور صورت‌حساب استفاده می‌کند. کدهای جلسه به تماس‌های «جزئیات مکان (جدید)» که پس‌از تماس‌های «تکمیل خودکار (جدید)» برقرار می‌شوند منتقل می‌شوند. برای اطلاعات بیشتر، به نشانه های جلسه مراجعه کنید.

نمایش ارجاع‌ها در برنامه

وقتی برنامه‌تان اطلاعاتی را که از GMSPlacesClient به‌دست آورده است، مثل عکس‌ها و مرورها، نمایش می‌دهد، برنامه باید اسناد اقتباس الزامی را نیز نمایش دهد.

برای مثال، دارایی reviews شیء GMSPlacesClient شامل آرایه‌ای از حداکثر پنج شیء GMSPlaceReview است. هر شیء GMSPlaceReview می‌تواند شامل ارجاع‌ها و ارجاع‌های نویسنده باشد. اگر مرور را در برنامه‌تان نمایش می‌دهید، باید اسناد یا اسناد نویسنده را نیز نمایش دهید.

برای اطلاعات بیشتر، مستندات مربوط به ارجاع‌ها را ببینید.