Tìm kiếm văn bản (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)

Tính năng Tìm kiếm bằng văn bản trả về thông tin về một nhóm đị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 đường Main". Dịch vụ này sẽ 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 độ lệch vị trí đã đặt.

Dịch vụ này đặc biệt hữu ích khi thực hiện các 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ũng có thể khớp với doanh nghiệp cũng như địa chỉ. Ví dụ về cụm từ tìm kiếm địa chỉ không rõ ràng là địa chỉ có định dạng không chính xác 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ể không trả về kết quả nào, trừ phi bạn đặt 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í).

"10 High Street, UK" (10 High Street, Vương quốc Anh) hoặc "123 Main Street, US" (123 Main Street, Hoa Kỳ) Nhiều "High Street" ở Vương quốc Anh; nhiều "Main Street" ở Hoa Kỳ. Cụm từ tìm kiếm không trả về kết quả mong muốn trừ phi bạn đặt một chế độ hạn chế về vị trí.
"Chuỗi nhà hàng ở New York" Nhiều vị trí "Nhà hàng chuỗi" ở New York; không có địa chỉ đường phố hoặc thậm chí là tên đường.
"10 High Street, Escher UK" hoặc "123 Main Street, Pleasanton US" Chỉ có một "High Street" ở thành phố Escher của Vương quốc Anh; chỉ có một "Main Street" ở thành phố Pleasanton, California, Hoa Kỳ.
"UniqueRestaurantName New York" Chỉ có 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" Cụm từ tìm kiếm này có quy định hạn chế về vị trí và "nhà hàng pizza" là một loại địa điểm được xác định rõ. Hàm này trả về nhiều kết quả.
"+1 514-670-8700"

Cụm từ tìm kiếm này có chứa số điện thoại. Hàm này trả về nhiều kết quả cho những địa điểm được liên kết với số điện thoại đó.

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

Đưa ra yêu cầu Tìm kiếm văn bản bằng cách gọi GMSPlacesClient searchByTextWithRequest:, truyền một đố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 đượ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.
  • Cụm từ tìm kiếm bằng văn bản.

Yêu cầu tìm kiếm văn bản này chỉ định rằng các đối tượng GMSPlace trong 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. Thao tác 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".

Places Swift SDK

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
}

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

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

Text Search API trả về một mảng các kết quả trùng khớp dưới dạng các đối tượng GMSPlace, với một đối tượng GMSPlace cho mỗi địa điểm trùng khớp.

Lấy trạng thái 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

Tính phí 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 GMSPlaceSearchByTextRequest để chỉ định các tham số bắt buộc cho hoạt động tìm kiếm.

  • Danh sách trường

    Chỉ định thuộc tính dữ liệu địa điểm cần trả về. Truyền một 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 hay về thiết kế để đả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 Text Search Essentials ID Only SKU:

      GMSPlacePropertyPlaceID

    • Các trường sau đây kích hoạt SKU Tìm kiếm văn bản chuyên nghiệp:

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

    • Các trường sau đây kích hoạt SKU Tìm kiếm văn bản dành cho doanh nghiệp:

      GMSPlacePropertyCurrentOpeningHours
      GMSPlacePropertySecondaryOpeningHours
      GMSPlacePropertyPhoneNumber
      GMSPlacePropertyPriceLevel
      GMSPlacePropertyRating
      GMSPlacePropertyOpeningHours
      GMSPlacePropertyUserRatingsTotal
      GMSPlacePropertyWebsite

    • Các trường sau đây kích hoạt SKU Text Search Enterprise Plus:

      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 tham quan đẹp 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 tìm kiếm.

  • includedType

    Giới hạn 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ụ:

    • let request = SearchByTextRequest()
      request.includedType = "bar"
    • let request = SearchByTextRequest()
      request.includedType = "pharmacy"

  • isOpenNow

    Nếu 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 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

    Được 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 được chỉ định do includeType chỉ định mới được trả về. Khi giá trị là false (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à một thiên kiến, tức 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, còn 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.

    • Một hình 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,0 đến 50000,0. Bán kính mặc định là 0.0. Ví dụ:

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

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

      Khung nhìn được coi là một vùng khép kín, tức là bao gồm cả ranh giới của vùng đó. Phạm vi vĩ độ phải nằm trong khoảng từ -90 đến 90 độ (bao gồm cả hai giá trị này), còn phạm vi kinh độ phải nằm trong khoảng từ -180 đến 180 độ (bao gồm cả hai giá trị này):

      • Nếu low = high, khung nhìn sẽ bao gồm điểm duy nhất đó.
      • Nếu low.longitude > high.longitude, thì 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ả bên ngoài khu vực được chỉ định sẽ không được trả về. Chỉ định khu vực dưới dạng Khung hiển thị 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 hiển thị.

    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, còn 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ả về đị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 kết quả có điểm xếp hạng trung bình của 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,0 đến 5,0 (tính toàn bộ) theo mức tăng 0,5. Ví dụ: 0, 0,5, 1,0, ..., 5,0 (bao gồm cả 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ế tìm kiếm ở những địa điểm được đánh dấu ở một số mức giá nhất định. Theo mặc định, tất cả các mức giá đều được chọn.

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

    Ví dụ:

        let request = SearchByTextRequest()
    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 một 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 cụm từ tìm kiếm) là chế độ 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 một cụm từ tìm kiếm không theo danh mục, chẳng hạn như "Mountain View, CA", bạn nên để rankPreference chưa đặt.

  • 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 là 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.

  • shouldIncludePureServiceAreaBusinesses

    Nếu true, trả về các doanh nghiệp chỉ cung cấp dịch vụ trong kết quả tìm kiếm. Doanh nghiệp chỉ cung cấp dịch vụ tại cơ sở khách hàng là doanh nghiệp trực tiếp cung cấp dịch vụ tận nơi hoặc giao hàng cho khách hàng, nhưng không phục vụ khách hàng tại địa chỉ doanh nghiệp.

    Ví dụ:

    Places Swift SDK

    let request = SearchByTextRequest()
request.shouldIncludePureServiceAreaBusinesses = true

    Swift

    let request = SearchByTextRequest()
request.shouldIncludePureServiceAreaBusinesses: true

    Objective-C

    GMSPlaceSearchByTextRequest *request =
    [[GMSPlaceSearchByTextRequest alloc] initWithTextQuery:@"pizza in New York" placeProperties:@[GMSPlacePropertyAll]];
request.shouldIncludePureServiceAreaBusinesses = YES;

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ổ.