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

Tính năng tìm kiếm văn bản trả về thông tin về một tập hợp các đị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ụ phản hồi bằng một danh sách các địa điểm khớp với chuỗi văn bản và mọi xu hướng vị trí đã đặt.

Dịch vụ này đặc biệt hữu ích khi tạo các truy vấn địa chỉ không rõ ràng trong hệ thống tự động và các thành phần không có đị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ỉ hoặc yêu cầu có định dạng kém, 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ả bằng 0 trừ phi một vị trí (chẳng hạn như khu vực, hạn chế về vị trí hoặc thiên kiến về vị trí) được đặt.

"10 High Street, UK" hoặc "123 Main Street, Hoa Kỳ" Nhiều đường "High Street" ở Vương quốc Anh; nhiều đường "Main Street" ở Hoa Kỳ. Truy vấn không trả về kết quả mong muốn trừ phi bạn đặt giới hạn về vị trí.
"Nhà hàng chuỗi New York" Có nhiều vị trí "Nhà hàng chuỗi" ở New York; không có địa chỉ đường phố hoặc thậm chí không có tên đường phố.
"10 High Street, Escher UK" hoặc "123 Main Street, Pleasanton US" Chỉ một "Đường cao tốc" ở thành phố Escher của Vương quốc Anh; chỉ một "đường Main" ở thành phố Pleasanton CA của Hoa Kỳ.
"UniqueCustomerName New York" Chỉ một cơ sở có tên này ở New York; không cần địa chỉ đường phố để phân biệt.
"nhà hàng pizza ở New York" Truy vấn này chứa giới hạn vị trí và "nhà hàng pizza" là loại địa điểm được xác định rõ ràng. Phương thức này trả về nhiều kết quả.
"+1 514-670-8700"

Truy vấn này chứa một số điện thoại. Phương thức này trả về nhiều kết quả cho các địa điểm liên kết với số điện thoại đó.

Nhận danh sách địa điểm bằng phương thức 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 tham số yêu cầu và 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ộckhô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ề một lỗi.
  • Cụm từ tìm kiếm dạng văn bản.

Ví dụ về yêu cầu tìm kiếm văn bản 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 từng đối tượng GMSPlace trong kết quả tìm kiếm. Thao tác này cũng lọc phản hồi để chỉ trả về các địa điểm thuộc loại "nhà hàng".

Swift

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

Objective-C

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

GooglePlacesSwift

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
}

Phản hồi cho Tìm kiếm văn bản

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

Cùng với các trường dữ liệu, đối tượng GMSPlace trong phản hồi chứa các hàm thành phần sau đây:

  • isOpen tính toán xem một địa điểm có mở cửa vào thời gian nhất định hay không.
  • 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.

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 nội dung 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 thuộc tính GMSPlace để chỉ định trường dữ liệu cần trả về. Nếu bạn bỏ qua mặt nạ trường (field mask), yêu cầu sẽ trả về một lỗi.

    Danh sách trường là một phương pháp thiết kế hiệu quả để đảm bảo 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à chi 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 của Tìm kiếm văn bản (chỉ nhận dạng):

      GMSPlacePropertyPlaceID, GMSPlacePropertyName
    • Các trường sau đây kích hoạt SKU của Tìm kiếm 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 kích hoạt SKU của công cụ Tìm kiếm văn bản (Nâng cao):

      GMSPlacePropertyCurrentOpeningHours, GMSPlacePropertySecondaryOpeningHours, GMSPlacePropertyPhoneNumber, GMSPlacePropertyPriceLevel, GMSPlacePropertyRating, GMSPlacePropertyOpeningHours, GMSPlacePropertyUserRatingsTotal, GMSPlacePropertyWebsite
    • Các trường sau đây kích hoạt SKU của công cụ Tìm kiếm 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 cần tìm kiếm, ví dụ: "nhà hàng", "123 Main Street" hoặc "địa điểm tốt nhất để ghé thăm ở 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

    Giới hạn kết quả ở các vị trí khớp với loại đã chỉ định được xác định trong Bảng A. 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 giá trị là false, hãy trả về tất cả các doanh nghiệp, bất kể trạng thái đang mở cửa. Các địa điểm không chỉ định giờ mở cửa trong cơ sở dữ liệu của Google Địa điểm sẽ được trả về nếu bạn đặt tham số này thành false.

  • isStrictTypeFiltering

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

  • locationBias

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

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

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

    • Một đường tròn được xác định bởi điểm ở giữa 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à một khung nhìn theo vĩ độ, được thể hiện dưới dạng hai điểm thấp và cao theo đường chéo đối diện. Điểm thấp đánh dấu góc phía Tây Nam của hình chữ nhật, còn điểm cao biểu thị góc phía đông bắc của hình chữ nhật.

      Khung nhìn được coi là một khu vực khép kín, có nghĩa là khung nhìn bao gồm ranh giới của khu vực đó. 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 điểm duy nhất đó.
      • Nếu low.longitude > high.longitude, phạm vi kinh độ sẽ bị đảo ngược (khung nhìn 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ả các kinh độ.
      • Nếu low.longitude = 180 độ và high.longitude = -180 độ, thì phạm vi 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. Kết quả nằm ngoài khu vực đã chỉ định sẽ không được trả về. Chỉ định khu vực 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 thể chỉ định cả hai. Hãy xem locationRestriction là khu vực chỉ định kết quả nằm gần đó, còn locationBias là khu vực chỉ định 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ề. Giá trị phải nằm trong khoảng từ 1 đến 20 (mặc định).

  • minRating

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

  • priceLevels

    Hạn chế tìm kiếm trong các địa điểm được đánh dấu theo các mức giá nhất định. Tuỳ chọn mặc định là chọn tất cả các mức 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 phân loại, chẳng hạn như "Nhà hàng ở thành phố New York", .relevance (kết quả xếp hạng theo mức độ liên quan với 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 cụm từ tìm kiếm không phân loại, chẳng hạn như " Mountain View, CA", bạn nên không đặt rankPreference.
  • regionCode

    Mã vùng dùng để định dạng phản hồi, được chỉ định dưới dạng giá trị mã CLDR gồm hai ký tự. Tham số này cũng có thể ảnh hưởng đến 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ã vùng, thì mã quốc gia sẽ bị loại khỏi địa chỉ.

    Hầu hết các mã CLDR đều giống hệt với mã ISO 3166-1, trừ một số trường hợp ngoại lệ đáng chú ý. Ví dụ: ccTLD (miền cấp cao nhất theo mã quốc gia) 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à pháp nhân của "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.

Hiển thị thuộc tính trong ứng dụng của bạn

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

Để biết thêm thông tin, vui lòng xem tài liệu về mô hình phân bổ.