Chi tiết địa điểm (Mới)

Chọn nền tảng: Android iOS JavaScript Dịch vụ web
Nhà phát triển ở Khu vực kinh tế Châu Âu (EEA)

Places SDK for iOS (Mới) 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.

Nhận thông tin chi tiết về địa điểm

Lớp GMSPlace chứa thông tin về một địa điểm cụ thể, bao gồm tất cả các trường dữ liệu xuất hiện trong Trường dữ liệu về địa điểm (Mới). Lấy đối tượng GMSPlace bằng cách gọi GMSPlacesClient fetchPlaceWithRequest:, truyền đối tượng GMSFetchPlaceRequest và phương thức gọi lại thuộc loại GMSPlaceResultCallback.

Đối tượng GMSFetchPlaceRequest chỉ định:

  • (Bắt buộc) Mã địa điểm, giá trị nhận dạng duy nhất cho một địa điểm trong cơ sở dữ liệu của Google Địa điểm và trên Google Maps.
  • (Bắt buộc) Danh sách các trường cần trả về trong đối tượng GMSPlace, còn được gọi là mặt nạ trường, do GMSPlaceProperty xác định. Nếu bạn không chỉ định ít nhất một trường trong danh sách trường hoặc nếu bạn bỏ qua danh sách trường, thì lệnh gọi sẽ trả về lỗi.
  • (Không bắt buộc) Mã khu vực dùng để định dạng phản hồi.
  • (Không bắt buộc) Mã thông báo phiên dùng để kết thúc một phiên Tự động hoàn thành (Mới).

Đưa ra yêu cầu Chi tiết về địa điểm

Ví dụ này lấy một địa điểm theo mã nhận dạng, truyền các tham số sau:

  • Mã địa điểm của ChIJV4k8_9UodTERU5KXbkYpSYs.
  • Danh sách trường chỉ định trả về tên địa điểm và URL của trang web.
  • Một GMSPlaceResultCallback để xử lý kết quả.

API này sẽ 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

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

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

Phản hồi về thông tin chi tiết về địa điểm

Place Details trả về một đối tượng GMSPlace chứa thông tin chi tiết về địa điểm. Chỉ những trường được chỉ định trong danh sách trường mới được điền vào đối tượng GMSPlace.

Lấy trạng thái đang mở

Đối tượng GMSPlacesClient chứa một hàm thành phần có tên là isOpenWithRequest (isOpenRequest trong Swift và isPlaceOpenRequest trong GooglePlacesSwift). Hàm này trả về một phản hồi cho biết địa điểm hiện có mở cửa hay không, dựa trên thời gian được chỉ định trong lệnh gọi.

Phương thức này nhận một đối số duy nhất thuộc loại GMSPlaceIsOpenWithRequest chứa:

  • Một đối tượng GMSPlace hoặc một chuỗi chỉ định mã địa điểm. Để biết thêm thông tin về cách tạo đối tượng Place bằng các trường cần thiết, hãy xem phần Thông tin chi tiết về địa điểm.
  • Một đối tượng NSDate (Obj-C) hoặc Date (Swift) không bắt buộc, chỉ định thời gian bạn muốn kiểm tra. Nếu bạn không chỉ định thời gian, giá trị mặc định sẽ là thời gian hiện tại.
  • Phương thức GMSPlaceOpenStatusResponseCallback để xử lý phản hồi.
    • >

Phương thức GMSPlaceIsOpenWithRequest yêu cầu bạn phải đặt các trường sau trong đối tượng GMSPlace:

  • GMSPlacePropertyUTCOffsetMinutes
  • GMSPlacePropertyBusinessStatus
  • GMSPlacePropertyOpeningHours
  • GMSPlacePropertyCurrentOpeningHours
  • GMSPlacePropertySecondaryOpeningHours

Nếu bạn không cung cấp các trường này trong đối tượng Place hoặc nếu bạn truyền một mã địa điểm, thì phương thức này sẽ dùng GMSPlacesClient GMSFetchPlaceRequest: để tìm nạp các trường đó.

isOpenWithRequest câu trả lời

isOpenWithRequest trả về một đối tượng GMSPlaceIsOpenResponse chứa một giá trị boolean có tên là status cho biết doanh nghiệp đang mở cửa, đóng cửa hay không xác định được trạng thái.

Ngôn ngữ Giá trị nếu mở Giá trị nếu đóng Giá trị nếu trạng thái không xác định
Places Swift true false nil
Swift .open .closed .unknown
Objective-C GMSPlaceOpenStatusOpen GMSPlaceOpenStatusClosed GMSPlaceOpenStatusUnknown

Thanh toán cho isOpenWithRequest

Ví dụ: Tạo yêu cầu GMSPlaceIsOpenWithRequest

Ví dụ sau đây cho thấy cách khởi tạo một GMSPlaceIsOpenWithRequest trong một đối tượng GMSPlace hiện có.

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

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

Thông số bắt buộc

Sử dụng đối tượng GMSFetchPlaceRequest để chỉ định các tham số bắt buộc.

Mã địa điểm

Mã địa điểm được dùng trong Places SDK cho iOS là mã nhận dạng giống như 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ể yên tâm rằng mình 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, xin 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.

Danh sách trường

Khi yêu cầu thông tin chi tiết về địa điểm, bạn phải chỉ định dữ liệu cần trả về trong đối tượng GMSPlace cho địa điểm dưới dạng một mặt nạ trường. Để xác định mặt nạ trường, hãy truyền một mảng giá trị từ GMSPlaceProperty đến đối tượng GMSFetchPlaceRequest. Che phủ trường là một phương pháp thiết kế hay để đảm bảo rằng bạn không yêu cầu dữ liệu không cần thiết, giúp tránh thời gian xử lý và phí thanh toán không cần thiết.

Chỉ định một hoặc nhiều trường sau:

  • Các trường sau đây kích hoạt SKU chỉ có mã nhận dạng thông tin cơ bản về địa điểm:

    GMSPlacePropertyPlaceID
    GMSPlacePropertyPhotos

  • Các trường sau đây kích hoạt SKU Thông tin cơ bản về địa điểm:

    GMSPlacePropertyAddressComponents
    GMSPlacePropertyFormattedAddress
    GMSPlacePropertyCoordinate
    GMSPlacePropertyPlusCode
    GMSPlacePropertyTypes
    GMSPlacePropertyViewport

  • Các trường sau đây kích hoạt SKU Chi tiết về địa điểm Pro:

    GMSPlacePropertyBusinessStatus
    GMSPlacePropertyIconBackgroundColor
    GMSPlacePropertyIconImageURL
    GMSPlacePropertyName
    GMSPlacePropertyUTCOffsetMinutes
    GMSPlacePropertyWheelchairAccessibleEntrance

  • Các trường sau đây kích hoạt SKU Chi tiết về địa điểm Pro:

    GMSPlacePropertyCurrentOpeningHours
    GMSPlacePropertySecondaryOpeningHours
    GMSPlacePropertyPhoneNumber
    GMSPlacePropertyPriceLevel
    GMSPlacePropertyRating
    GMSPlacePropertyOpeningHours
    GMSPlacePropertyUserRatingsTotal
    GMSPlacePropertyWebsite

  • Các trường sau đây kích hoạt SKU Chi tiết về địa điểm dành cho doanh nghiệp:

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

Ví dụ sau đây truyền một danh sách gồm 2 giá trị trường để chỉ định rằng đối tượng GMSPlace do một yêu cầu trả về chứa các trường name và placeID:

Places Swift SDK

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

Objective-C

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

Thông số tùy chọn

Sử dụng đối tượng GMSFetchPlaceRequest để chỉ định các tham số không bắt buộc.

regionCode

Mã khu vực dùng để định dạng phản hồi, được chỉ định là giá trị mã CLDR gồm 2 ký tự. Tham số này cũng có thể có hiệu ứng thiên vị đối với kết quả tìm kiếm. Không có giá trị mặc định.

Nếu tên quốc gia của trường địa chỉ trong phản hồi khớp với mã khu vực, thì mã quốc gia sẽ bị bỏ qua trong địa chỉ.

Hầu hết mã CLDR đều giống với mã ISO 3166-1, trừ một số trường hợp ngoại lệ đáng chú ý. Ví dụ: ccTLD của Vương quốc Anh là "uk" (.co.uk) trong khi mã ISO 3166-1 của quốc gia này là "gb" (về mặt kỹ thuật, mã này dành cho thực thể "Vương quốc Anh và Bắc Ireland"). Tham số này có thể ảnh hưởng đến kết quả dựa trên luật hiện hành.

sessionToken

Mã thông báo phiên là chuỗi do người dùng tạo để theo dõi các lệnh gọi Autocomplete (Mới) dưới dạng "phiên". Tính năng Tự động hoàn thành (Mới) sử dụng mã thông báo phiên để nhóm các giai đoạn chọn vị trí và truy vấn của một cụm từ tìm kiếm tự động hoàn thành của người dùng thành một phiên riêng biệt cho mục đích thanh toán. Mã thông báo phiên được truyền vào các lệnh gọi Chi tiết về địa điểm (Mới) theo sau các lệnh gọi Tự động hoàn thành (Mới). Để biết thêm thông tin, hãy xem phần Mã thông báo phiên.

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 lấy từ GMSPlacesClient, chẳng hạn như ảnh và bài đánh giá, ứng dụng của bạn cũng phải hiển thị thông tin ghi nhận bắt buộc.

Ví dụ: thuộc tính reviews của đối tượng GMSPlacesClient chứa một mảng gồm tối đa 5 đối tượng GMSPlaceReview. Mỗi đối tượng GMSPlaceReview có thể chứa thông tin ghi nhận quyền tác giả và thông tin ghi nhận tác giả. Nếu hiển thị bài đánh giá trong ứng dụng, bạn cũng phải hiển thị mọi thông tin ghi nhận quyền tác giả hoặc thông tin ghi nhận tác giả.

Để biết thêm thông tin, hãy xem tài liệu về phân bổ.