Tìm kiếm văn bản (Mới)

Tìm kiếm bằng văn bản trả về thông tin về một tập hợp địa điểm dựa trên một chuỗi. Ví dụ: "pizza ở New York", "cửa hàng giày gần Ottawa" hoặc "123 Main Street". Dịch vụ này phản hồi bằng danh sách các địa điểm khớp với chuỗi văn bản và mọi độ lệch vị trí đã đặt.

Dịch vụ này đặc biệt hữu ích khi tạo truy vấn địa chỉ không rõ ràng trong một hệ thống tự động, và các thành phần không phải địa chỉ của chuỗi có thể khớp với doanh nghiệp cũng như địa chỉ. Ví dụ về truy vấn địa chỉ không rõ ràng là địa chỉ có định dạng không chuẩn hoặc yêu cầu có các thành phần không phải địa chỉ, chẳng hạn như tên doanh nghiệp. Các yêu cầu như hai ví dụ đầu tiên có thể trả về kết quả rỗng trừ phi bạn đặt vị trí (chẳng hạn như khu vực, hạn chế về vị trí hoặc độ lệch vị trí).

Lấy danh sách địa điểm bằng cách tìm kiếm bằng văn bản

Tạo yêu cầu Tìm kiếm văn bản bằng cách gọi GMSPlacesClient searchByTextWithRequest:, truyền đối tượng GMSPlaceSearchByTextRequest xác định các tham số yêu cầu và một phương thức gọi lại thuộc loại GMSPlaceSearchByTextResultCallback để xử lý phản hồi.

Đối tượng GMSPlaceSearchByTextRequest chỉ định tất cả các tham số bắt buộc và không bắt buộc cho yêu cầu. Các tham số bắt buộc bao gồm:

• Danh sách các trường cần trả về trong đối tượng GMSPlace, còn 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.
• Cụm từ tìm kiếm dạng văn bản.

Yêu cầu tìm kiếm bằng văn bản mẫu này chỉ định rằng các đối tượng GMSPlace phản hồi chứa tên địa điểm và mã địa điểm cho mỗi đối tượng GMSPlace trong kết quả tìm kiếm. Hàm này cũng lọc phản hồi để chỉ trả về những địa điểm thuộc loại "nhà hàng".

// Create the GMSPlaceSearchByTextRequest object.
let myProperties = [GMSPlaceProperty.name, GMSPlaceProperty.placeID].map {$0.rawValue}
let request = GMSPlaceSearchByTextRequest(textQuery:"pizza in New York", placeProperties:myProperties)
request.isOpenNow = true
request.includedType = "restaurant"
request.maxResultCount = 5
request.minRating = 3.5
request.rankPreference = .distance
request.isStrictTypeFiltering = true
request.locationBias =  GMSPlaceCircularLocationOption(CLLocationCoordinate2DMake(40.7, -74.0), 200.0)

// Array to hold the places in the response
var placeResults: [GMSPlace] = []

let callback: GMSPlaceSearchByTextResultCallback = { [weak self] results, error in
  guard let self, error == nil else {
    if let error {
      print(error.localizedDescription)
    }
    return
  }
  guard let results = results as? [GMSPlace] else {
    return
  }
  placeResults = results
}

GMSPlacesClient.shared().searchByText(with: request, callback: callback)

// Create the GMSPlaceSearchByTextRequest object.
GMSPlaceSearchByTextRequest *request =
    [[GMSPlaceSearchByTextRequest alloc] initWithTextQuery:@"pizza in New York" placeProperties:@[GMSPlacePropertyName, GMSPlacePropertyPlaceID]];
request.isOpenNow = YES;
request.includedType = @"restaurant";
request.maxResultCount = 5;
request.minRating = 3.5;
request.rankPreference = GMSPlaceSearchByTextRankPreferenceDistance;
request.isStrictTypeFiltering = YES;
request.priceLevels = @[ @(kGMSPlacesPriceLevelFree), @(kGMSPlacesPriceLevelCheap) ];
request.locationBias = GMSPlaceCircularLocationOption(CLLocationCoordinate2DMake(40.7, -74.0), 200.0);

// Array to hold the places in the response
_placeResults = [NSArray array];

// Create the GMSPlaceSearchByTextRequest object.
[_placesClient searchByTextWithRequest:request
    callback:^(NSArray<GMSPlace *> *_Nullable placeResults, NSError * _Nullable error) {
      if (error != nil) {
        NSLog(@"An error occurred %@", [error localizedDescription]);
        return;
      } else {
        if (placeResults.count > 0) {
          // Get list of places.
          _placeResults = placeResults;
      }
    }
  }
];

let restriction = RectangularLocationRestriction(
      northEast: CLLocationCoordinate2D(latitude: 20, longitude: 30),
      southWest: CLLocationCoordinate2D(latitude: 40, longitude: 50)
)
let searchByTextRequest = SearchByTextRequest(
        textQuery: "pizza in New York",
        placeProperties: [ .name, .placeID ],
        locationRestriction: restriction,
        includedType: .restaurant,
        maxResultCount: 5,
        minRating: 3.5,
        priceLevels: [ .moderate, .inexpensive ],
        isStrictTypeFiltering: true
)
switch await placesClient.searchByText(with: searchByTextRequest) {
case .success(let places):
  // Handle places
case .failure(let placesError):
  // Handle error
}

Nội dung phản hồi của tính năng Tìm kiếm bằng văn bản

API Tìm kiếm văn bản trả về một mảng các kết quả trùng khớp ở dạng đối tượng GMSPlace, với mỗi đối tượng GMSPlace cho một vị trí trùng khớp.

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

Đối tượng GMSPlacesClient chứa một hàm thành viên có tên isOpenWithRequest (isOpenRequest trong Swift và isPlaceOpenRequest trong GooglePlacesSwift) trả về phản hồi cho biết liệu địa điểm đó có đang 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 Địa điểm 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, thời gian mặc định sẽ là 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 các trường này không được cung cấp trong đối tượng Địa điểm hoặc nếu bạn truyền mã địa điểm, thì phương thức này sẽ sử dụng GMSPlacesClient GMSFetchPlaceRequest: để tìm nạp các trường đó.

Phản hồi isOpenWithRequest

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

Thông tin thanh toán cho isOpenWithRequest

• Các trường GMSPlacePropertyUTCOffsetMinutes và GMSPlacePropertyBusinessStatus được tính phí theo SKU Dữ liệu cơ bản. Phần còn lại của Giờ mở cửa sẽ được tính phí theo SKU Thông tin chi tiết về địa điểm (Nâng cao).
• Nếu đối tượng GMSPlace đã có các trường này từ một yêu cầu trước đó, bạn sẽ không bị tính phí lại.

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

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

          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
          }
          

Thông số bắt buộc

Sử dụng đối tượng GMSPlaceSearchByTextRequest để chỉ định các tham số bắt buộc cho lượt tìm kiếm.

• Danh sách trường

  Chỉ định các thuộc tính dữ liệu địa điểm cần trả về. Truyền danh sách các thuộc tính GMSPlace chỉ định các trường dữ liệu cần trả về. Nếu bạn bỏ qua mặt nạ trường, yêu cầu sẽ trả về lỗi.

  Danh sách 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 sẽ kích hoạt SKU Tìm kiếm bằng văn bản (chỉ mã):

    GMSPlacePropertyPlaceID, GMSPlacePropertyName

  • Các trường sau đây sẽ kích hoạt SKU Tìm kiếm bằng văn bản (Cơ bản):

    GMSPlacePropertyAddressComponents, GMSPlacePropertyBusinessStatus, GMSPlacePropertyFormattedAddress, GMSPlacePropertyIconBackgroundColor, GMSPlacePropertyIconImageURL, GMSPlacePropertyCoordinate, GMSPlacePropertyPhotos, GMSPlacePropertyPlusCode, GMSPlacePropertyTypes, GMSPlacePropertyUTCOffsetMinutes, GMSPlacePropertyViewport, GMSPlacePropertyWheelchairAccessibleEntrance

  • Các trường sau đây sẽ kích hoạt SKU Tìm kiếm bằng văn bản (Nâng cao):

    GMSPlacePropertyCurrentOpeningHours, GMSPlacePropertySecondaryOpeningHours, GMSPlacePropertyPhoneNumber, GMSPlacePropertyPriceLevel, GMSPlacePropertyRating, GMSPlacePropertyOpeningHours, GMSPlacePropertyUserRatingsTotal, GMSPlacePropertyWebsite

  • Các trường sau đây sẽ kích hoạt SKU Tìm kiếm bằng văn bản (Ưu tiên):

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

• textQuery

  Chuỗi văn bản để tìm kiếm, ví dụ: "nhà hàng", "123 Main Street" hoặc "địa điểm du lịch nổi tiếng nhất ở San Francisco".

Thông số tùy chọn

Sử dụng đối tượng GMSPlaceSearchByTextRequest để chỉ định các tham số không bắt buộc cho nội dung tìm kiếm.

• includedType

  Hạn chế kết quả ở những địa điểm khớp với loại được chỉ định do Bảng A xác định. Bạn chỉ có thể chỉ định một loại. Ví dụ:

  • request.includedType = "bar"
  • request.includedType = "pharmacy"

• isOpenNow

  Nếu là true, chỉ trả về những địa điểm đang mở cửa kinh doanh tại thời điểm gửi truy vấn. Nếu là false, hãy trả về tất cả doanh nghiệp bất kể trạng thái mở cửa. Những địa điểm không chỉ định giờ mở cửa trong cơ sở dữ liệu Google Places sẽ được trả về nếu bạn đặt tham số này thành false.

• isStrictTypeFiltering

  Dùng với tham số includeType. Khi được đặt thành true, chỉ những địa điểm khớp với các loại đã chỉ định do includeType chỉ định mới được trả về. Khi giá trị là false (sai), theo mặc định, phản hồi có thể chứa những địa điểm không khớp với các loại được chỉ định.

• locationBias

  Chỉ định một khu vực để tìm kiếm. Vị trí này đóng vai trò là độ lệch, nghĩa là kết quả xung quanh vị trí đã chỉ định có thể được trả về, bao gồm cả kết quả bên ngoài khu vực đã chỉ định.

  Bạn có thể chỉ định locationRestriction hoặc locationBias, nhưng không được chỉ định cả hai. Hãy coi locationRestriction là chỉ định khu vực mà kết quả phải nằm trong đó và locationBias là chỉ định khu vực mà kết quả phải ở gần nhưng có thể nằm ngoài khu vực đó.

  Chỉ định khu vực dưới dạng Khung nhìn hình chữ nhật hoặc hình tròn.

  • Đường tròn được xác định bằng tâm điểm và bán kính tính bằng mét. Bán kính phải nằm trong khoảng từ 0 đến 50000. Bán kính mặc định là 0.0. Ví dụ:

    request.locationBias =  GMSPlaceCircularLocationOption(CLLocationCoordinate2DMake(40.7, -74.0), 200.0)

  • Hình chữ nhật là khung nhìn vĩ độ-kinh độ, được biểu thị dưới dạng hai điểm thấp và cao đối diện nhau theo đường chéo. Điểm thấp đánh dấu góc tây nam của hình chữ nhật và điểm cao đại diện cho góc đông bắc của hình chữ nhật.

    Khung nhìn được coi là một vùng kín, nghĩa là bao gồm cả ranh giới của vùng đó. Giới hạn vĩ độ phải nằm trong khoảng từ -90 đến 90 độ và giới hạn kinh độ phải nằm trong khoảng từ -180 đến 180 độ:

    • Nếu low = high, khung nhìn sẽ bao gồm một điểm duy nhất đó.
    • Nếu low.longitude > high.longitude, thì phạm vi kinh độ sẽ bị đảo ngược (khung nhìn sẽ vượt qua đường kinh độ 180 độ).
    • Nếu low.longitude = -180 độ và high.longitude = 180 độ, thì khung nhìn sẽ bao gồm tất cả kinh độ.
    • Nếu low.longitude = 180 độ và high.longitude = -180 độ, thì dải kinh độ sẽ trống.
    • Nếu low.latitude > high.latitude, thì phạm vi vĩ độ sẽ trống.

• locationRestriction

  Chỉ định một khu vực để tìm kiếm. Hệ thống sẽ không trả về kết quả nằm ngoài khu vực đã chỉ định. Chỉ định vùng này dưới dạng Khung nhìn hình chữ nhật. Hãy xem nội dung mô tả về locationBias để biết thông tin về cách xác định Khung nhìn.

  Bạn có thể chỉ định locationRestriction hoặc locationBias, nhưng không được chỉ định cả hai. Hãy coi locationRestriction là chỉ định khu vực mà kết quả phải nằm trong đó và locationBias là chỉ định khu vực mà kết quả phải ở gần nhưng có thể nằm ngoài khu vực đó.

• maxResultCount

  Chỉ định số lượng kết quả địa điểm tối đa cần trả về. Phải nằm trong khoảng từ 1 đến 20 (mặc định).

• minRating

  Chỉ giới hạn kết quả ở những người dùng có điểm xếp hạng trung bình từ người dùng lớn hơn hoặc bằng hạn mức này. Giá trị phải nằm trong khoảng từ 0 đến 5 (tính cả hai giá trị này) với mức tăng là 0,5. Ví dụ: 0, 0,5, 1,0, ... , 5,0. Các giá trị được làm tròn lên đến 0,5 gần nhất. Ví dụ: giá trị 0,6 sẽ loại bỏ tất cả kết quả có điểm xếp hạng dưới 1,0.

• priceLevels

  Hạn chế kết quả tìm kiếm ở những địa điểm được đánh dấu ở một số mức giá nhất định. Chế độ mặc định là chọn tất cả các cấp giá.

  Chỉ định một mảng gồm một hoặc nhiều giá trị do PriceLevel xác định.

  Ví dụ:

  request.priceLevels = [GMSPlacesPriceLevel.moderate.rawValue, GMSPlacesPriceLevel.cheap.rawValue]

• rankPreference

  Chỉ định cách xếp hạng kết quả trong phản hồi dựa trên loại truy vấn:

  • Đối với cụm từ tìm kiếm theo danh mục như "Nhà hàng ở Thành phố New York", .relevance (xếp hạng kết quả theo mức độ liên quan của nội dung tìm kiếm) là giá trị mặc định. Bạn có thể đặt rankPreference thành .relevance hoặc .distance (xếp hạng kết quả theo khoảng cách).
  • Đối với truy vấn không theo danh mục như "Mountain View, CA", bạn nên không đặt rankPreference.

• regionCode

  Mã khu vực dùng để định dạng phản hồi, được chỉ định dưới dạng giá trị mã CLDR gồm hai chữ cái. Tham số này cũng có thể gây ra 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 khỏi địa chỉ.

  Hầu hết mã CLDR giống hệt với mã ISO 3166-1, ngoại 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 là "gb" (về mặt kỹ thuật là cho thực thể "Vương quốc Anh và Bắc Ireland"). Thông số này có thể ảnh hưởng đến kết quả dựa trên luật hiện hành.

Hiển thị thông tin phân bổ trong ứng dụng

Khi ứng dụng của bạn hiển thị thông tin thu được từ GMSPlacesClient, chẳng hạn như ảnh và bài đánh giá, thì ứng dụng đó cũng phải hiển thị các thông tin ghi công 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 các thuộc tính và thuộc tính tác giả. Nếu hiển thị bài đánh giá trong ứng dụng, thì bạn cũng phải hiển thị mọi thông tin ghi công hoặc thông tin ghi công tác giả.

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