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

Chọn nền tảng: Android iOS JavaScript Dịch vụ web

SDK địa điểm dành cho 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 như 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 thông tin này cho một địa điểm cụ thể, bạn có thể sử dụng mã địa điểm, là giá trị nhận dạng ổn định giúp nhận dạng một địa điểm duy nhất.

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ể giữ đối tượng GMSPlace theo các cách sau:

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

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

Khi yêu cầu cung cấp 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 chuyển GMSPlaceField, chỉ định loại dữ liệu cần trả về. Đây là một điều quan trọng bạn cần cân nhắc bởi vì điều này sẽ ảnh hưởng đến chi phí cho mỗi yêu cầu.

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

Ví dụ sau đây chuyển danh sách hai giá trị trường để chỉ định dữ liệu được trả về bởi một yêu cầu:

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 địa điểmGMSPlaceLikelihoodList.

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

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

• name – Tên địa điểm.
• editorialSummary – Cung cấp thông tin mô tả đơn giản về một địa điểm.
• placeID – Giá trị nhận dạng dạng văn bản của địa điểm. Đọc thêm về ID địa điểm trong 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 tọa độ theo 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 địa điểm này.

  Thông thường, địa chỉ này 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 sự do các quy định hạn chế.

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

  Không phân tích cú pháp địa chỉ đã đị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 (như do GMSOpeningHours đại diện). Gọi GMSOpeningHours.weekdayText để nhận danh sách các chuỗi đã bản địa hóa của giờ mở cửa hằng ngày trong tuần. Gọi GMSOpeningHours.Periods để trả về danh sách GMSPeriod kèm theo 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 đị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 có lịch nghỉ cho các ngày lễ và sự thay đổi tạm thời về một địa điểm.

• addressComponents – Một mảng 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. Những 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, chẳng hạn như tìm thành phố nơi đặt địa điểm đó. Đừng sử dụng các thành phần này để định dạng địa chỉ. Thay vào đó, hãy sử dụng thuộc tính formattedAddress. Thuộc tính này cung cấp một địa chỉ được định dạng đã được định dạng.

  Hãy lưu ý những thông tin sau đây 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ả 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 sẽ giữ nguyên giữa các yêu cầu. Cụ thể, số lượng addressComponents sẽ 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. Có thể thiếu một thành phần cụ thể trong phản hồi sau đó.
• userRatingsTotal – Biểu thị số lượng bài đánh giá xếp hạng cho địa điểm.

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

• isOpen tính toán việc một địa điểm có mở cửa vào một thời điểm nhất định 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 để nhận thời gian mở và/hoặc ngày, yêu cầu fetchPlaceFromPlaceID: hoặc findPlaceLikelihoodsFromUserLocationWithPlaceFields: ban đầu phải chỉ định CẢ trường GMSPlaceFieldOpeningHours và GMSPlaceFieldUTCOffsetMinutes. Nếu một trong hai trường này bị thiếu, đối tượng GMSPlace thu được sẽ không chứa thời gian hay ngày mở và lệnh gọi sẽ trả về GMSPlaceOpenStatusUnknown. Để đảm bảo 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 vị trí ban đầu. Nếu không có yêu cầu, Google sẽ xem như doanh nghiệp đang hoạt động.

Xem video này để biết cách sử dụng isOpen với Thông tin chi tiết về địa điểm.

Nhận được giờ đặc biệt

Trong khi giờ mở cửa thông thường có được là thông qua openingHours, currentOpeningHours và secondaryOpeningHours hỗ trợ các thay đổi về ngày lễ và lịch biểu tạm thời. Bạn có thể lọc và hiển thị số giờ đặc biệt 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
    }
}

Nhận một địa điểm theo ID

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

Để xác định một địa điểm theo mã, hãy gọi GMSPlacesClient fetchPlaceFromPlaceID: với các tham số sau:

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

API gọi phương thức gọi lại được chỉ định, chuyể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 là nil.

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ị thuộc tính trong ứng dụng của bạn

Khi hiển thị thông tin thu được từ GMSPlacesClient lookUpPlaceID:callback:, ứng dụng đó cũng phải hiển thị thông tin phân bổ. Hãy xem tài liệu về mô hình phân bổ.

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

ID địa điểm được sử dụng trong SDK địa điểm dành cho iOS có cùng số nhận dạng như được sử dụng trong API địa điểm, SDK địa điểm dành cho Android và các API khác của Google.

Mỗi mã địa điểm chỉ có thể đề cập đến một địa điểm, nhưng một địa điểm có thể chứa 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 vị trí mới.

Khi yêu cầu một địa điểm bằng cách chỉ định một mã địa điểm, bạn có thể tin tưởng 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, xin lưu ý rằng phản hồi đó có thể chứa 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 bài viết Tổng quan về mã địa điểm.