جزئیات مکان (جدید)

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

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

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

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

شیء GMSFetchPlaceRequest موارد زیر را مشخص می‌کند:

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

درخواست جزئیات مکان را ثبت کنید

این مثال با ارسال پارامترهای زیر، یک مکان را بر اساس شناسه (ID) دریافت می‌کند:

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

API متد فراخوانی مشخص شده را فراخوانی می‌کند و یک شیء GMSPlace را ارسال می‌کند. اگر مکان پیدا نشود، شیء place برابر با nil خواهد بود.

مکان‌های Swift SDK 

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

سویفت 

// 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 یا رشته‌ای که شناسه مکان را مشخص می‌کند. برای اطلاعات بیشتر در مورد ایجاد شیء Place با فیلدهای لازم، به جزئیات Place مراجعه کنید.
  • یک شیء اختیاری NSDate (Obj-C) یا Date (Swift) که زمان مورد نظر برای بررسی را مشخص می‌کند. اگر زمانی مشخص نشود، مقدار پیش‌فرض now است.
  • یک متد GMSPlaceOpenStatusResponseCallback برای مدیریت پاسخ.
    • >

متد GMSPlaceIsOpenWithRequest نیاز دارد که فیلدهای زیر در شیء GMSPlace تنظیم شوند:

  • GMSPlacePropertyUTCOffsetMinutes
  • GMSPlacePropertyBusinessStatus
  • GMSPlacePropertyOpeningHours
  • GMSPlacePropertyCurrentOpeningHours
  • GMSPlacePropertySecondaryOpeningHours

اگر این فیلدها در شیء Place ارائه نشده باشند، یا اگر یک شناسه مکان ارسال کنید، متد GMSPlacesClient GMSFetchPlaceRequest: برای دریافت آنها استفاده می‌کند.

پاسخ isOpenWithRequest

isOpenWithRequest یک شیء GMSPlaceIsOpenResponse برمی‌گرداند که حاوی یک مقدار بولی به نام status است که نشان می‌دهد آیا کسب‌وکار باز، بسته یا وضعیت آن نامشخص است.

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

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

مثال: یک درخواست GMSPlaceIsOpenWithRequest ایجاد کنید

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

مکان‌های Swift SDK 

        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
        }

سویفت 

    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 برای تعیین پارامترهای مورد نیاز استفاده کنید.

شناسه مکان

شناسه مکان مورد استفاده در Places SDK برای iOS همان شناسه‌ای است که در Places API، Places SDK برای اندروید و سایر APIهای گوگل استفاده می‌شود. هر شناسه مکان می‌تواند فقط به یک مکان اشاره کند، اما یک مکان واحد می‌تواند بیش از یک شناسه مکان داشته باشد.

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

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

فهرست فیلدها

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

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

  • فیلدهای زیر، SKU مربوط به جزئیات مکان، ملزومات، شناسه، فقط را فعال می‌کنند:

    GMSPlacePropertyPlaceID
    GMSPlacePropertyPhotos

  • فیلدهای زیر SKU مربوط به جزئیات مکان (Place Details Essentials) را فعال می‌کنند:

    GMSPlacePropertyAddressComponents
    GMSPlacePropertyFormattedAddress
    GMSPlacePropertyCoordinate
    GMSPlacePropertyPlusCode
    GMSPlacePropertyTypes
    GMSPlacePropertyViewport

  • فیلدهای زیر، SKU مربوط به Place Details Pro را فعال می‌کنند:

    GMSPlacePropertyBusinessStatus
    GMSPlacePropertyIconBackgroundColor
    GMSPlacePropertyIconImageURL
    GMSPlacePropertyName
    GMSPlacePropertyUTCOffsetMinutes
    GMSPlacePropertyWheelchairAccessibleEntrance

  • فیلدهای زیر، SKU مربوط به Place Details Pro را فعال می‌کنند:

    GMSPlacePropertyCurrentOpeningHours
    GMSPlacePropertySecondaryOpeningHours
    GMSPlacePropertyPhoneNumber
    GMSPlacePropertyPriceLevel
    GMSPlacePropertyRating
    GMSPlacePropertyOpeningHours
    GMSPlacePropertyUserRatingsTotal
    GMSPlacePropertyWebsite

  • فیلدهای زیر، SKU مربوط به جزئیات مکان سازمانی را فعال می‌کنند:

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

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

مکان‌های Swift SDK 

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

سویفت 

// 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 برای تعیین پارامترهای اختیاری استفاده کنید.

کد منطقه

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

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

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

توکن جلسه

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

نمایش انتساب‌ها در برنامه شما

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

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

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