Thông tin về địa điểm

Places SDK for iOS cung cấp cho ứng dụng của bạn thông tin phong phú về các địa điểm, bao gồm tên và địa chỉ của địa điểm, vị trí địa lý được chỉ định dưới dạng toạ độ vĩ độ/kinh độ, loại địa điểm (chẳng hạn như câu lạc bộ đêm, cửa hàng thú cưng, bảo tàng) và nhiều thông tin khác. Để truy cập vào thông tin này cho một địa điểm cụ thể, bạn có thể sử dụng mã địa điểm. Đây là một giá trị nhận dạng ổn định giúp xác định duy nhất một địa điểm.

Thông tin chi tiết về địa điểm

Lớp GMSPlace cung cấp thông tin về một địa điểm cụ thể. Bạn có thể lấy đối tượng GMSPlace theo những cách sau:

• Gọi GMSPlacesClient findPlaceLikelihoodsFromUserLocationWithPlaceFields:. Xem hướng dẫn về cách lấy địa điểm hiện tại.
• Gọi GMSPlacesClient fetchPlaceFromPlaceID:, truyền vào một GMSPlaceField, mã địa điểm và phương thức gọi lại. Đối với yêu cầu Chi tiết về địa điểm, nếu bạn không chỉ định ít nhất một trường trong yêu cầu hoặc nếu bạn bỏ qua tham số fields trong yêu cầu, TẤT CẢ các trường có thể sẽ được trả về và bạn sẽ bị tính phí tương ứng. Xem hướng dẫn về cách lấy một địa điểm theo mã nhận dạng.

Cảnh báo: Nếu không chỉ định ít nhất một trường trong yêu cầu hoặc nếu bỏ qua tham số fields trong yêu cầu, TẤT CẢ các trường có thể có sẽ được trả về và bạn sẽ bị tính phí tương ứng. Điều này chỉ áp dụng cho các yêu cầu về Thông tin chi tiết về địa điểm.

Khi yêu cầu một địa điểm, bạn phải chỉ định loại dữ liệu địa điểm cần trả về. Để thực hiện việc này, hãy truyền một GMSPlaceField, chỉ định các loại dữ liệu cần trả về. Đây là một yếu tố quan trọng cần cân nhắc, vì điều này sẽ ảnh hưởng đến chi phí cho mỗi yêu cầu.

Vì kết quả dữ liệu về địa điểm không được để trống, nên chỉ những kết quả về địa điểm có dữ liệu mới được trả về (ví dụ: nếu một địa điểm được yêu cầu không có ảnh, thì trường photos sẽ không xuất hiện trong kết quả).

Ví dụ sau đây truyền một danh sách gồm 2 giá trị trường để chỉ định dữ liệu do một yêu cầu trả về:

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);
  

GMSPlaceFieldTakeout, GMSPlaceFieldDelivery, GMSPlaceFieldDineIn, GMSPlaceFieldCurbsidePickup, GMSPlaceFieldPhoneNumber, GMSPlaceFieldWebsite, GMSPlaceFieldOpeningHours và GMSPlaceFieldAddressComponents không được hỗ trợ cho các đối tượng vị trí GMSPlaceLikelihoodList.

Tìm hiểu thêm về trường địa điểm. Để biết thêm thông tin về cách tính phí cho các yêu cầu về dữ liệu Địa điểm, hãy xem phần Mức sử dụng và việc thanh toán.

Lớp GMSPlace có thể chứa dữ liệu về địa điểm sau đây:

• name – Tên của địa điểm.
• editorialSummary – Cung cấp nội dung mô tả về một địa điểm.
• placeID – Giá trị nhận dạng dạng văn bản cho địa điểm. Đọc thêm về mã địa điểm ở phần còn lại của trang này.
• coordinate – Vị trí địa lý của địa điểm, được chỉ định dưới dạng toạ độ vĩ độ và kinh độ.
• phoneNumber – Số điện thoại của địa điểm, ở định dạng quốc tế.
• formattedAddress – Địa chỉ mà con người có thể đọc được của vị trí này.

  Địa chỉ này thường tương đương với địa chỉ bưu điện. Xin lưu ý rằng một số quốc gia, chẳng hạn như Vương quốc Anh, không cho phép phân phối địa chỉ bưu chính thực do các hạn chế về việc cấp phép.

  Địa chỉ được định dạng bao gồm một hoặc nhiều thành phần địa chỉ. Ví dụ: địa chỉ "111 8th Avenue, New York, NY" bao gồm các thành phần sau: "111" (số nhà), "8th Avenue" (tuyến đường), "New York" (thành phố) và "NY" (tiểu bang của Hoa Kỳ).

  Đừng phân tích cú pháp địa chỉ được định dạng theo phương thức lập trình. Thay vào đó, bạn nên sử dụng các thành phần địa chỉ riêng lẻ mà phản hồi API bao gồm ngoài trường địa chỉ được định dạng.

• openingHours – Giờ mở cửa của địa điểm (do GMSOpeningHours đại diện). Gọi GMSOpeningHours.weekdayText để nhận danh sách các chuỗi được bản địa hoá về giờ mở cửa hằng ngày trong tuần. Gọi GMSOpeningHours.Periods để trả về danh sách GMSPeriod có thông tin chi tiết hơn tương đương với dữ liệu do weekdayText cung cấp. Lưu ý: Nếu một địa điểm luôn mở cửa, thì khoảng thời gian sẽ được biểu thị là nửa đêm Chủ Nhật và closeEvent là giá trị rỗng.
• currentOpeningHours và secondaryOpeningHours – Các trường ghi nhận những thay đổi tạm thời và thay đổi vào ngày lễ trong lịch biểu của một địa điểm.

• addressComponents – Một mảng gồm các đối tượng GMSAddressComponent đại diện cho các thành phần của địa chỉ cho một địa điểm. Các thành phần này được cung cấp nhằm mục đích trích xuất thông tin có cấu trúc về địa chỉ của một địa điểm, ví dụ: tìm thành phố nơi một địa điểm toạ lạc. Đừng dùng các thành phần này để định dạng địa chỉ; thay vào đó, hãy dùng thuộc tính formattedAddress. Thuộc tính này cung cấp một địa chỉ được định dạng theo ngôn ngữ địa phương.

  Xin lưu ý những thông tin sau về mảng addressComponents:

  • Mảng thành phần địa chỉ có thể chứa nhiều thành phần hơn formattedAddress.
  • Mảng này không nhất thiết phải bao gồm tất cả các thực thể chính trị có chứa địa chỉ, ngoài những thực thể có trong formattedAddress.
  • Định dạng của phản hồi không được đảm bảo giữ nguyên giữa các yêu cầu. Cụ thể, số lượng addressComponents thay đổi tuỳ theo địa chỉ được yêu cầu và có thể thay đổi theo thời gian đối với cùng một địa chỉ. Một thành phần có thể thay đổi vị trí trong mảng. Loại thành phần có thể thay đổi. Một thành phần cụ thể có thể bị thiếu trong phản hồi sau này.
• userRatingsTotal – Cho biết số lượng bài đánh giá tạo nên điểm xếp hạng của địa điểm.

Lớp GMSPlace chứa các hàm thành viên sau:

• isOpen tính toán xem một địa điểm có mở cửa vào thời gian đã cho hay không, dựa trên openingHours và UTCOffsetMinutes, cũng như ngày và giờ hiện tại.
• isOpenAtDate tính toán xem một địa điểm có mở cửa vào một ngày nhất định hay không, dựa trên openingHours và UTCOffsetMinutes, cũng như ngày và giờ hiện tại.

Khi sử dụng các hàm này để lấy thời gian và/hoặc ngày mở cửa, yêu cầu fetchPlaceFromPlaceID: hoặc findPlaceLikelihoodsFromUserLocationWithPlaceFields: ban đầu phải chỉ định CẢ hai trường GMSPlaceFieldOpeningHours và GMSPlaceFieldUTCOffsetMinutes. Nếu thiếu một trong hai trường này, đối tượng GMSPlace thu được sẽ không chứa thời gian hoặc ngày mở cửa và lệnh gọi sẽ trả về GMSPlaceOpenStatusUnknown. Để có kết quả chính xác, hãy yêu cầu các trường GMSPlaceFieldBusinessStatus và GMSPlaceFieldUTCOffsetMinutes trong yêu cầu ban đầu về địa điểm. Nếu bạn không yêu cầu, thì chúng tôi giả định rằng doanh nghiệp đang hoạt động.

Để biết cách sử dụng isOpen với Thông tin chi tiết về địa điểm, hãy xem video Cách lấy giờ mở cửa .

Nhận giờ đặc biệt

Mặc dù giờ mở cửa thông thường được lấy thông qua openingHours, currentOpeningHours và secondaryOpeningHours hỗ trợ các thay đổi về lịch vào ngày lễ và lịch tạm thời. Bạn có thể lọc và trình bày giờ hoạt động ngoại lệ cho những ngày đặc biệt này (nếu có).

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

Lấy một địa điểm theo mã nhận dạng

Mã địa điểm là một giá trị nhận dạng dạng văn bản xác định duy nhất một địa điểm. Trong Places SDK for iOS, bạn có thể truy xuất mã nhận dạng của một địa điểm từ đối tượng GMSPlace. Bạn có thể lưu trữ mã địa điểm và sử dụng mã này để truy xuất lại đối tượng GMSPlace sau này.

Để lấy một địa điểm theo mã nhận dạng, hãy gọi GMSPlacesClient fetchPlaceFromPlaceID:, truyền các tham số sau:

• Một chuỗi ký tự chứa Mã địa điểm.
• Một hoặc nhiều GMSPlaceField, chỉ định các kiểu dữ liệu cần trả về.
• Mã thông báo phiên nếu cuộc gọi được thực hiện để kết thúc một cụm từ tìm kiếm tự động hoàn thành. Nếu không, hãy truyền giá trị nil.
• Một GMSPlaceResultCallback để xử lý kết quả.

API này gọi phương thức gọi lại đã chỉ định, truyền vào một đối tượng GMSPlace. Nếu không tìm thấy địa điểm, đối tượng địa điểm sẽ là nil.

Places Swift SDK dành cho iOS

// Initialize Places Swift Client.
let placesClient = PlacesClient.shared

// A hotel in Saigon with an attribution
let placeID = "ChIJV4k8_9UodTERU5KXbkYpSYs"
    
// Fetch Place Request.
let fetchPlaceRequest = FetchPlaceRequest(
  placeID: placeID,
  placeProperties: [.displayName]
)
    
Task {
  switch await placesClient.fetchPlace(with: fetchPlaceRequest) {
  case .success(let place):
    print("The selected place is: \(place.displayName): \(String(describing: place.description))")
  case .failure(let placesError):
    print("Place not found: \(placeID); \(placesError)")
  }
}

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

Hiển thị thông tin ghi nhận quyền tác giả trong ứng dụng

Khi hiển thị thông tin thu được từ GMSPlacesClient lookUpPlaceID:callback:, ứng dụng của bạn cũng phải hiển thị thông tin ghi nhận quyền tác giả. Xem tài liệu về quyền ghi công.

Tìm hiểu thêm về mã địa điểm

Mã địa điểm dùng trong Places SDK cho iOS cũng là mã nhận dạng được dùng trong Places API, Places SDK cho Android và các API khác của Google.

Mỗi mã địa điểm chỉ có thể tham chiếu đến một địa điểm, nhưng một địa điểm có thể có nhiều mã địa điểm.

Có những trường hợp có thể khiến một địa điểm nhận được mã địa điểm mới. Ví dụ: điều này có thể xảy ra nếu một doanh nghiệp chuyển đến địa điểm mới.

Khi yêu cầu một địa điểm bằng cách chỉ định mã địa điểm, bạn có thể chắc chắn rằng bạn sẽ luôn nhận được cùng một địa điểm trong phản hồi (nếu địa điểm đó vẫn tồn tại). Tuy nhiên, hãy lưu ý rằng phản hồi có thể chứa một mã địa điểm khác với mã địa điểm trong yêu cầu của bạn.

Để biết thêm thông tin, hãy xem thông tin tổng quan về mã địa điểm.