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ìm kiếm văn bản (Mới) 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" hoặc "cửa hàng giày gần Ottawa" hoặc "123 Main Street"). Dịch vụ này sẽ 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í đã được đặt.

Ngoài các tham số bắt buộc, Tính năng Tìm kiếm văn bản (Mới) hỗ trợ tinh chỉnh cụm từ tìm kiếm bằng các tham số không bắt buộc để có kết quả chính xác hơn.

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

Thực hiện 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, theo định nghĩa của GMSPlaceProperty. 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. Yêu cầu 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 = GMSPlaceRectangularLocationOption(
      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;
      }
    }
  }
];

Câu trả lời của tính năng 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ả trùng khớp dưới dạng các đối tượng GMSPlace, trong đó mỗi đối tượng GMSPlace tương ứng với một địa điểm trùng khớp.

Lấy trạng thái mở cửa

Đối tượng GMSPlacesClient chứa một hàm thành viên có tên là isOpenWithRequest (isOpenRequest trong Swift và isPlaceOpenRequest trong GooglePlacesSwift) trả về một phản hồi cho biết liệu đị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 hàm.

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 có các trường cần thiết, hãy xem phần Thông tin chi tiết về địa điểm.
  • Đố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ì 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 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 đó.

isOpenWithRequest câu trả lời

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

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

Tính phí cho isOpenWithRequest

  • Các trường GMSPlacePropertyUTCOffsetMinutes và GMSPlacePropertyBusinessStatus được tính phí theo SKU dữ liệu cơ bản. Giờ mở cửa còn lại được tính phí theo SKU Chi tiết địa điểm dành cho doanh nghiệp.
  • Nếu đối tượng GMSPlace của bạn đã có các trường này từ một yêu cầu trước đó, thì bạn sẽ không bị tính phí lại.

Ví dụ: Gửi yêu cầu GMSPlaceIsOpenWithRequest

Ví dụ sau đây cho thấy cách khởi động 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
            }
          }];

Phân trang

Tính năng Tìm kiếm văn bản cung cấp một đối tượng phân trang, boolean hasNextPage, được trả về trong phản hồi đầu tiên cho lệnh gọi Tìm kiếm văn bản. Nếu có trang tiếp theo, bạn có thể sử dụng hàm fetchNextPage() để tải trang đó.

Ví dụ sau đây cho biết cách kiểm tra xem có trang tiếp theo hay không, sau đó tải trang.

Swift

public struct PlaceSearchPagination {
  public var pageSize: Int
  public var hasNextPage: Bool
  public func fetchNextPage() async -> SearchByTextResponse
}

public struct SearchByTextResponse {
  public var pagination: PlaceSearchPagination?
  public var places: [Place]?
  public var error: PlaceError?
}

PlacesClient.swift
public func searchByText(with request: SearchByTextRequest) async -> SearchByTextResponse

let searchByTextRequest = SearchByTextRequest(textQuery: "restaurants",
    placeProperties: [PlaceProperty.displayName],
    locationBias: CircularCoordinateRegion(center: CLLocationCoordinate2D(latitude: 0, longitude: 0), radius: 100))

searchByTextRequest.maxResultCount = 10

var searchByTextResponse = await PlacesClient.shared.searchByText(with: searchByTextRequest)
print("Found \(searchByTextResponse.places.count) places")

searchByTextResponse.pagination.pageSize = 20

// Continue making requests until no more results are found in pagination object
while searchByTextResponse.pagination.hasNextPage {
    searchByTextResponse = await searchByTextResponse.pagination.fetchNextPage()
    print("Found \(searchByTextResponse.places.count) places")
}

Objective-C

GMSPlaceSearchByTextRequest *searchByTextRequest = [[GMSPlaceSearchByTextRequest alloc]
    initWithTextQuery: @"restaurants"
    placeProperties: @[GMSPlacePropertyAll]];

searchByTextRequest.maxResultCount = 10;

__block void (^recursiveCallback)(GMSPlaceSearchByTextResponse *, NSError *);
recursiveCallback = ^(GMSPlaceSearchByTextResponse * response, NSError* error) {
    NSLog(@"Found %d places", response.places.count);
    if (response.pagination.hasNextPage) {
      [response.pagination fetchNextPageWithCompletion:recursiveCallback];
   }
};
[GMSPlacesClient.sharedClient searchByTextWithRequest:searchByTextRequest  
                                           completion:recursiveCallback];

Tham 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 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 Chỉ mã nhận dạng cơ bản của tính năng Tìm kiếm văn bản:

      GMSPlacePropertyPlaceID

      Để xem danh sách đầy đủ các trường và SKU liên quan, hãy xem phần Trường dữ liệu địa điểm (Mới).

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

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

      Để xem danh sách đầy đủ các trường và SKU liên quan, hãy xem phần Trường dữ liệu địa điểm (Mới).

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

      GMSPlacePropertyCurrentOpeningHours
      GMSPlacePropertySecondaryOpeningHours
      GMSPlacePropertyPhoneNumber
      GMSPlacePropertyPriceLevel
      GMSPlacePropertyRating
      GMSPlacePropertyOpeningHours
      GMSPlacePropertyUserRatingsTotal
      GMSPlacePropertyWebsite

      Để xem danh sách đầy đủ các trường và SKU liên quan, hãy xem phần Trường dữ liệu địa điểm (Mới).

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

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

      Để xem danh sách đầy đủ các trường và SKU liên quan, hãy xem phần Trường dữ liệu địa điểm (Mới).

  • 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 tham quan lý tưở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

    Giới hạn kết quả ở những địa điểm khớp với loại được chỉ định trong Bảng A. 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 hoạt động 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 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 được đặt thành true, chỉ những địa điểm khớp với các loại được chỉ định bằng includeType 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 đã chỉ định.

  • locationBias

    Chỉ định một khu vực để tìm kiếm. Vị trí này đóng vai trò là một độ lệch, tức là hệ thống có thể trả về kết quả xung quanh vị trí đã chỉ định, 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à việc chỉ định khu vực mà kết quả phải nằm trong đó, còn locationBias là việc 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.

    • 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 đến 50.000, bao gồm cả hai giá trị này. 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 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 khép kín, nghĩa là nó bao gồm cả ranh giới của nó. Ranh giới vĩ độ phải nằm trong khoảng từ -90 đến 90 độ và ranh giới kinh độ phải nằm trong khoảng từ -180 đến 180 độ:

      • Nếu low = high, thì 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ả 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 nhìn hình chữ nhật. 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à việc chỉ định khu vực mà kết quả phải nằm trong đó, còn locationBias là việc 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ỉ trả về những kết quả có điểm xếp hạng từ người dùng trung bình 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) với mức tăng là 0,5. Ví dụ: 0, 0,5, 1,0, ... , 5,0 (bao gồm cả 5,0). 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

    Giới hạn 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. 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 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à 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 phân loại như "Mountain View, CA", bạn nên để trống 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ể có tác động thiên vị đế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ã khu vực, thì mã quốc gia sẽ bị bỏ qua khỏi địa chỉ.

    Hầu hết các mã CLDR đều giống 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 của quốc gia này là "gb" (về mặt kỹ thuật là cho thực thể "Vương quốc Liên hiệp 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 là true, thì sẽ trả về các doanh nghiệp thuần tuý cung cấp dịch vụ tại cơ sở khách hàng trong kết quả tìm kiếm. Doanh nghiệp chỉ phục vụ tận nơi 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 tác giả trong ứng dụng

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