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.

Tính năng Tìm kiếm văn bản (Mới) tương tự như tính năng Tìm kiếm lân cận (Mới). Điểm khác biệt chính giữa hai loại này là tính năng Tìm kiếm văn bản (Mới) cho phép bạn chỉ định một chuỗi tìm kiếm tuỳ ý, trong khi tính năng Nearby Search (Mới) yêu cầu một khu vực cụ thể để tìm kiếm.

Yêu cầu Tìm kiếm văn bản

Yêu cầu Tìm kiếm văn bản có dạng như sau:

// Specify the list of fields to return.
final List<Place.Field> placeFields = Arrays.asList(Place.Field.ID, Place.Field.DISPLAY_NAME);

// Define latitude and longitude coordinates of the search area.
LatLng southWest = new LatLng(37.38816277477739, -122.08813770258874);
LatLng northEast = new LatLng(37.39580487866437, -122.07702325966572);

// Use the builder to create a SearchByTextRequest object.
final SearchByTextRequest searchByTextRequest = SearchByTextRequest.builder("Spicy Vegetarian Food", placeFields)
  .setMaxResultCount(10)
  .setLocationRestriction(RectangularBounds.newInstance(southWest, northEast)).build();

// Call PlacesClient.searchByText() to perform the search.
// Define a response handler to process the returned List of Place objects.
placesClient.searchByText(searchByTextRequest)
    .addOnSuccessListener(response -> {
      List<Place> places = response.getPlaces();
    });

Trong ví dụ này, bạn:

  • Đặt danh sách trường để chỉ bao gồm Place.Field.ID và Place.Field.DISPLAY_NAME. Điều đó có nghĩa là các đối tượng Place trong phản hồi đại diện cho từng địa điểm phù hợp chỉ chứa hai trường đó.

  • Sử dụng SearchByTextRequest.Builder để tạo một đối tượng SearchByTextRequest xác định nội dung tìm kiếm.

    • Đặt chuỗi truy vấn văn bản thành "Đồ ăn chay cay".

    • Đặt số lượng địa điểm tối đa trong kết quả thành 10. Giá trị mặc định và tối đa là 20.

    • Giới hạn khu vực tìm kiếm trong hình chữ nhật được xác định bằng toạ độ vĩ độ và kinh độ. Không có kết quả trùng khớp nào bên ngoài khu vực này được trả về.

  • Thêm OnSuccessListener và lấy các địa điểm phù hợp từ đối tượng SearchByTextResponse.

Câu trả lời của tính năng Tìm kiếm văn bản

Lớp SearchByTextResponse đại diện cho phản hồi từ một yêu cầu tìm kiếm. Đối tượng SearchByTextResponse chứa:

  • Danh sách các đối tượng Place đại diện cho tất cả địa điểm phù hợp, với một đối tượng Place cho mỗi địa điểm phù hợp.

  • Mỗi đối tượng Place chỉ chứa các trường được xác định theo danh sách trường được truyền trong yêu cầu.

Ví dụ: trong yêu cầu, bạn đã xác định danh sách trường như sau:

// Specify the list of fields to return.
final List<Place.Field> placeFields = Arrays.asList(Place.Field.ID, Place.Field.DISPLAY_NAME);

Danh sách trường này có nghĩa là mỗi đối tượng Place trong phản hồi chỉ chứa mã địa điểm và tên của từng địa điểm phù hợp. Sau đó, bạn có thể sử dụng các phương thức Place.getId() và Place.getName() để truy cập vào các trường này trong mỗi đối tượng Place.

Để xem thêm ví dụ về cách truy cập dữ liệu trong đối tượng Place, hãy xem phần Truy cập vào các trường dữ liệu của đối tượng Địa điểm

Phân trang

Lớp SearchByTextResponse của tính năng Tìm kiếm văn bản cung cấp quyền truy cập vào tính năng phân trang kết quả tìm kiếm văn bản thông qua phương thức getPagination(), phương thức này trả về một đối tượng Phân trang.

Sử dụng phương thức hasNextPage() của đối tượng Phân trang để xác định xem có thêm trang kết quả hay không. Phương thức này trả về một giá trị boolean (true hoặc false).

Khi hasNextPage() trả về giá trị true, hãy gọi phương thức fetchNextPage() để truy xuất trang kết quả tiếp theo.

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.

Kotlin

val searchByTextRequest =
      searchByTextRequest("restaurants", Arrays.asList(Place.Field.NAME)) {
        maxResultCount = 10
      }

// using pagination object (Preferred)
placesClient.searchByText(searchByTextRequest)   
    .addOnSuccessListener {response: SearchByTextResponse ->
        val places = response.places

        val pagination = response.pagination

        if (pagination.hasNextPage()) {
            pagination.setPageSize(20)
            pagination.fetchNextPage()
                    .addOnSuccessListener { nextPageResponse ->
                          val nextPagePlaces = nextPageResponse.getPlaces()
                    }
                    .addOnFailureListener {// Handle error with given status code}
        }
}
.addOnFailureListener {
// TODO: Handle error with given status code.
exception -> {
          exception.printStackTrace();
        }
}

Java

SearchByTextRequest searchByTextRequest =
  SearchByTextRequest.builder("restaurants", Arrays.asList(Place.Field.NAME)).setMaxResultCount(10).build();

// using pagination object (Preferred)
placesClient.searchByText(searchByTextRequest)
  .addOnSuccessListener((response) -> {
    List<Place> places = response.getPlaces();
    Log.i(TAG, "Places result: " + places);

    Pagination pagination =
      response.getPagination();

    if (pagination.hasNextPage()) {
      pagination.setPageSize(20); // change the page size from 10 to 20
      pagination.fetchNextPage()
    	  .addOnSuccessListener((nextPageResponse) -> {
            List<Place> nextPagePlaces = nextPageResponse.getPlaces();
            Log.i(TAG, "Next page places result: " + nextPagePlaces);
        });
    }
  })
  .addOnFailureListener((exception) -> {
    if (exception instanceof ApiException) {
    	// Handle error with given status code
    }
  });

Tham số bắt buộc

Các tham số bắt buộc cho SearchByTextRequest là:

  • Danh sách trường

    Chỉ định các trường dữ liệu địa điểm cần trả về. Truyền danh sách các giá trị Place.Field chỉ định các trường dữ liệu cần trả về. Không có danh sách mặc định về các trường được trả về trong phản hồ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:

      Place.Field.DISPLAY_NAME*
          * Sử dụng thay cho Place.Field.NAME (không dùng nữa trong phiên bản 4.0).
      Place.Field.ID
      Place.Field.RESOURCE_NAME*
          * Chứa tên tài nguyên địa điểm ở dạng: places/PLACE_ID.
           Sử dụng DISPLAY_NAME để truy cập tên văn bản của địa điểm.

      Để 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:

      Place.Field.ACCESSIBILITY_OPTIONS*
          Sử dụng thay cho Place.Field.WHEELCHAIR_ACCESSIBLE_ENTRANCE (không dùng nữa).
      Place.Field.ADDRESS_COMPONENTS
      Place.Field.ADR_FORMAT_ADDRESS
      Place.Field.BUSINESS_STATUS
      Place.Field.FORMATTED_ADDRESS*
          Sử dụng thay cho Place.Field.ADDRESS (không dùng nữa).
      Place.Field.GOOGLE_MAPS_URI
      Place.Field.ICON_BACKGROUND_COLOR
      Place.Field.ICON_MASK_URL *
          Sử dụng thay cho Place.Field.ICON_URL (không dùng nữa).
      Place.Field.LOCATION*
          Sử dụng thay cho Place.Field.LAT_LNG (không dùng nữa).
      Place.Field.PHOTO_METADATAS
      Place.Field.PLUS_CODE
      Place.Field.PRIMARY_TYPE
      Place.Field.PRIMARY_TYPE_DISPLAY_NAME
      Place.Field.SHORT_FORMATTED_ADDRESS
      Place.Field.SUB_DESTINATIONS
      Place.Field.TYPES
      Place.Field.UTC_OFFSET
      Place.Field.VIEWPORT

      Để 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:

      Place.Field.CURRENT_OPENING_HOURS
      Place.Field.CURRENT_SECONDARY_OPENING_HOURS
      Place.Field.INTERNATIONAL_PHONE_NUMBER*
          * Sử dụng thay cho Place.Field.PHONE_NUMBER, vốn không còn được dùng nữa.
      Place.Field.NATIONAL_PHONE_NUMBER
      Place.Field.OPENING_HOURS
      Place.Field.PRICE_LEVEL
      Place.Field.RATING
      Place.Field.SECONDARY_OPENING_HOURS
      Place.Field.USER_RATING_COUNT*
          * Sử dụng thay cho Place.Field.USER_RATINGS_TOTAL, vốn không còn được dùng nữa.
      Place.Field.WEBSITE_URI

      Để 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:

      Place.Field.ALLOWS_DOGS
      Place.Field.CURBSIDE_PICKUP
      Place.Field.DELIVERY
      Place.Field.DINE_IN
      Place.Field.EDITORIAL_SUMMARY
      Place.Field.EV_CHARGE_OPTIONS
      Place.Field.FUEL_OPTIONS
      Place.Field.GOOD_FOR_CHILDREN
      Place.Field.GOOD_FOR_GROUPS
      Place.Field.GOOD_FOR_WATCHING_SPORTS
      Place.Field.LIVE_MUSIC
      Place.Field.MENU_FOR_CHILDREN
      Place.Field.OUTDOOR_SEATING
      Place.Field.PARKING_OPTIONS
      Place.Field.PAYMENT_OPTIONS
      Place.Field.RESERVABLE
      Place.Field.RESTROOM
      Place.Field.REVIEWS
      Place.Field.SERVES_BEER
      Place.Field.SERVES_BREAKFAST
      Place.Field.SERVES_BRUNCH
      Place.Field.SERVES_COCKTAILS
      Place.Field.SERVES_COFFEE
      Place.Field.SERVES_DESSERT
      Place.Field.SERVES_DINNER
      Place.Field.SERVES_LUNCH
      Place.Field.SERVES_VEGETARIAN_FOOD
      Place.Field.SERVES_WINE
      Place.Field.TAKEOUT

      Để 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).

    Để đặt tham số danh sách trường, hãy gọi phương thức setPlaceFields() khi tạo đối tượng SearchByTextRequest.

  • Cụm từ tìm kiếm dạng văn bản

    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". API này trả về các kết quả phù hợp dựa trên chuỗi này và sắp xếp kết quả dựa trên mức độ liên quan mà API nhận thấy.

    Để đặt tham số truy vấn văn bản, hãy gọi phương thức setTextQuery() khi tạo đối tượng SearchByTextRequest.

Thông số tùy chọn

Sử dụng đối tượng SearchByTextRequest để chỉ định các tham số không bắt buộc cho yêu cầu của bạn.

  • Loại đưa vào

    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ụ:

    • setIncludedType("bar")
    • setIncludedType("pharmacy")

    Để đặt tham số loại được bao gồm, hãy gọi phương thức setIncludedType() khi tạo đối tượng SearchByTextRequest.

  • Thiên kiến về vị trí

    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 quy định hạn chế về vị trí hoặc độ lệch vị trí, nhưng không được chỉ định cả hai. Hãy coi quy định hạn chế về vị trí là việc chỉ định khu vực mà kết quả phải nằm trong đó, còn thiên vị vị trí là việc chỉ định khu vực mà kết quả có khả năng nằm trong hoặc gần đó. Xin lưu ý rằng khi sử dụng thiên vị vị trí, kết quả vẫn có thể nằm ngoài khu vực được chỉ định.

    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. Ví dụ:

      // Define latitude and longitude coordinates of the center of the search area.
      LatLng searchCenter = new LatLng(37.38816277477739, -122.08813770258874);
      
      // Use the builder to create a SearchByTextRequest object.
      // Set the radius of the search area to 500.0 meters.
      final SearchByTextRequest searchByTextRequest = SearchByTextRequest.builder("Spicy Vegetarian Food", placeFields)
        .setMaxResultCount(10)
        .setLocationBias(CircularBounds.newInstance(searchCenter, 500.0)).build();
    • 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.

      Cả giá trị thấp và cao đều phải được điền sẵn và hộp được biểu thị không được để trống. Khung nhìn trống sẽ dẫn đến lỗi.

      Ví dụ: đối với khung nhìn hình chữ nhật, hãy xem phần Yêu cầu tìm kiếm văn bản.

      Để đặt tham số thiên vị vị trí, hãy gọi phương thức setLocationBias() khi tạo đối tượng SearchByTextRequest.

  • Hạn chế về vị trí

    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ề Xu hướng vị trí để biết thông tin về cách xác định Khung nhìn.

    Bạn có thể chỉ định quy định hạn chế về vị trí hoặc độ lệch vị trí, nhưng không được chỉ định cả hai. Hãy coi việc hạn chế vị trí là chỉ định khu vực mà kết quả phải nằm trong đó, còn thiên vị vị trí 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 đó.

    Để đặt tham số hạn chế vị trí, hãy gọi phương thức setLocationRestriction() khi tạo đối tượng SearchByTextRequest.

  • Số lượng kết quả tối đa

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

    Để đặt tham số số lượng kết quả tối đa, hãy gọi phương thức setMaxResultCount() khi tạo đối tượng SearchByTextRequest.

  • Xếp hạng tối thiểu

    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.

    Để đặt tham số điểm xếp hạng tối thiểu, hãy gọi phương thức setMinRating() khi tạo đối tượng SearchByTextRequest.

  • Đang mở

    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.

    Để đặt tham số đang mở, hãy gọi phương thức setOpenNow() khi tạo đối tượng SearchByTextRequest.

  • Mức giá

    Theo mặc định, kết quả sẽ bao gồm những địa điểm cung cấp dịch vụ ở mọi mức giá. Để giới hạn kết quả chỉ bao gồm các địa điểm ở một mức giá cụ thể, bạn có thể truyền một danh sách các giá trị số nguyên tương ứng với mức giá của những địa điểm mà bạn muốn trả về:

    • 1 – Địa điểm cung cấp dịch vụ giá rẻ.
    • 2 – Địa điểm cung cấp dịch vụ có giá vừa phải.
    • 3 – Địa điểm cung cấp dịch vụ đắt tiền.
    • 4 – Địa điểm cung cấp dịch vụ rất đắt.

    Để đặt tham số mức giá, hãy gọi phương thức setPriceLevels() khi tạo đối tượng SearchByTextRequest.

  • Lựa chọn ưu tiên về thứ hạng

    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", SearchByTextRequest.RankPreference.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 lựa chọn ưu tiên về thứ hạng thành SearchByTextRequest.RankPreference.RELEVANCE hoặc SearchByTextRequest.RankPreference.DISTANCE (xếp hạng kết quả theo khoảng cách).
    • Đối với một truy vấn không phân loại như "Mountain View, CA", bạn nên để trống tham số ưu tiên xếp hạng.

    Để đặt tham số lựa chọn ưu tiên về thứ hạng, hãy gọi phương thức setRankPreference() khi tạo đối tượng SearchByTextRequest.

  • Mã vùng

    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.

    Để đặt tham số mã khu vực, hãy gọi phương thức setRegionCode() khi tạo đối tượng SearchByTextRequest.

  • Lọc loại nghiêm ngặt

    Được dùng với tham số loại bao gồm. Khi bạn đặt thành true, chỉ những địa điểm khớp với các loại được chỉ định bằng loại bao gồm mới được trả về. Khi 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.

    Để đặt tham số lọc loại nghiêm ngặt, hãy gọi phương thức setStrictTypeFiltering() khi tạo đối tượng SearchByTextRequest.