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

Chọn nền tảng: Android iOS JavaScript Web Service

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 (chẳng hạn như "pizza ở New York" hoặc "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 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í đã đượ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) còn hỗ trợ tinh chỉnh truy vấn bằng các tham số không bắt buộc để có kết quả tốt hơn.

Lấy danh sách địa điểm bằng tính năng 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à 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 bắt buộc và không bắt buộc tham số 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, như được xác định bởi 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.
  • Truy vấn văn bản .

Yêu cầu tìm kiếm bằng văn bản trong ví dụ 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ề các đị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;
      }
    }
  }
];

Phản hồi Tìm kiếm 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ưới dạng đố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ở cửa

Đố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 đ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:

  • Đối tượng GMSPlace object 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 bài viết 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 không chỉ định thời gian, thì thời gian mặc định 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 đặ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 sẽ sử dụng GMSPlacesClient GMSFetchPlaceRequest: để tìm nạp các trường này.

Phản hồi isOpenWithRequest

isOpenWithRequest trả về đố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 trạng thái không xác định.

Ngôn ngữ Giá trị nếu mở cửa Giá trị nếu đóng cửa 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

  • 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 được tính phí theo SKU Doanh nghiệp Place Details.
  • 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ụ: Tạo yêu cầu GMSPlaceIsOpenWithRequest

Ví dụ sau đây cho biết cách khởi chạy 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ì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];

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 tìm kiếm.

  • Danh sách trường

    Chỉ định thuộc tính dữ liệu địa điểm nào cần trả về. Truyền danh sách các GMSPlace thuộc tính 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 để đả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 kích hoạt SKU Chỉ có mã nhận dạng Nguyên tắc cơ bản của Tìm kiếm:

      GMSPlacePropertyPlaceID

    • Các trường sau 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

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

      GMSPlacePropertyCurrentOpeningHours
      GMSPlacePropertySecondaryOpeningHours
      GMSPlacePropertyPhoneNumber
      GMSPlacePropertyPriceLevel
      GMSPlacePropertyRating
      GMSPlacePropertyOpeningHours
      GMSPlacePropertyUserRatingsTotal
      GMSPlacePropertyWebsite

    • Các trường sau 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

  • 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ả chỉ hiện các đị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 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, 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 là false (giá trị mặc định), phản hồi có thể chứa những địa điểm không khớp 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í được chỉ định có thể được trả về, bao gồm cả kết quả bên ngoài khu vực đượ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 dưới dạng hình tròn.

    • Hình tròn được xác định bằng đ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,0 đến 50000,0, 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à khung nhìn 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 và đ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 khu vực khép kín, nghĩa là bao gồm cả ranh giới của nó. Giới hạn vĩ độ phải nằm trong khoảng từ -90 đến 90 độ, bao gồm cả hai giá trị này và giới hạn 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, dải kinh độ sẽ bị đảo ngược (khung nhìn cắt đường kinh độ 180 độ).
      • Nếu low.longitude = -180 độ và high.longitude = 180 độ, khung nhìn sẽ bao gồm tất cả kinh độ.
      • Nếu low.longitude = 180 độ và high.longitude = -180 độ, dải kinh độ sẽ trống.
      • Nếu low.latitude > high.latitude, dải 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 phần 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), bao gồm cả hai giá trị này.

  • minRating

    Giới hạn kết quả chỉ hiện 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,0 đến 5,0 (bao gồm cả hai giá trị này) theo bước tăng là 0,5. Ví dụ: 0, 0,5, 1,0, ..., 5,0 bao gồm cả hai giá trị này. 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 nhỏ hơn 1,0.

  • priceLevels

    Giới hạn tìm kiếm chỉ hiện những địa điểm được đánh dấu ở một số mức giá nhất định. Giá trị 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ụ:

        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 truy vấn theo danh mục, chẳng hạn 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 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, chẳng hạn như "Mountain View, CA", bạn nên để rankPreference không được đặt.

  • 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 ký tự . Tham số này cũng có thể có hiệu ứng độ lệch đố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 các mã CLDR đều giống với mã ISO 3166-1, với 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"). 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, trả về các doanh nghiệp phục vụ tận nơi trong kết quả tìm kiếm. Doanh nghiệp 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 công trạng 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á, ứng dụng cũng phải hiển thị thông tin ghi nhận công trạ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 GMSPlaceReview đối tượng. Mỗi đối tượng GMSPlaceReview có thể chứa thông tin ghi nhận công trạng và thông tin ghi nhận công trạng của tác giả. Nếu bạn 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 nhận công trạng hoặc thông tin ghi nhận công trạng của tác giả.

Để biết thêm thông tin, hãy xem tài liệu về thông tin ghi nhận công trạng.