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

Chọn nền tảng: Android iOS JavaScript Dịch vụ web

Tìm kiếm văn bản (Mới) trả về thông tin về một tập hợp đị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 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à bất kỳ độ lệch vị trí nào đã được đặ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 có địa chỉ của chuỗi có thể khớp với các doanh nghiệp cũng như địa chỉ. Ví dụ về truy vấn địa chỉ không rõ ràng là địa chỉ có định dạng kém hoặc yêu cầu chứa các thành phần không có địa chỉ như tên doanh nghiệp. Các yêu cầu như 2 ví dụ đầu tiên có thể trả về kết quả bằng 0 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 sai lệch về vị trí).

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 2 loại này là tính năng Tìm kiếm văn bản (New) cho phép bạn chỉ định một chuỗi tìm kiếm tuỳ ý, trong khi tính năng Tìm kiếm lân cận (New) yêu cầu một khu vực cụ thể để tìm kiếm.

"10 High Street, UK" hoặc "123 Main Street, US" Nhiều "Đường cao tốc" ở Vương quốc Anh; nhiều "Đường chính" ở 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í.
"ChainRestaurant New York" Nhiều địa điểm "ChainRestaurant" ở New York; không có địa chỉ đường phố hoặc thậm chí là tên đường phố.
"10 High Street, Escher UK" hoặc "123 Main Street, Pleasanton US" Chỉ có một "High Street" (Đường cao tốc) trong thành phố Escher của Vương quốc Anh; chỉ có một "Main Street" ở thành phố Pleasanton CA của Hoa Kỳ.
"UniqueRestaurantName New York" Chỉ có một cơ sở có tên này tại 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 có chứa giới hạn 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"

Truy vấn này có chứa số điện thoại. Công 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 đó.

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ó trong biểu mẫu:

// Specify the list of fields to return.
final List<Place.Field> placeFields = Arrays.asList(Place.Field.ID, Place.Field.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:

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

  • Sử dụng SearchByTextRequest.Builder để tạo đố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 "Sngy Vegetarian Food".

    • Đặt số lượng vị trí kết quả tối đa 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 ở hình chữ nhật được xác định bằng các toạ độ vĩ độ và kinh độ. Không có kết quả phù hợp nào nằm ngoài khu vực này được trả về.

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

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

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

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

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

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

// Specify the list of fields to return.
final List<Place.Field> placeFields = Arrays.asList(Place.Field.ID, Place.Field.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 trùng khớp. Sau đó, bạn có thể 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 từng đối tượng Place.

Để biết 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 đối tượng Địa điểm

Thông số bắt buộc

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

  • Danh sách trường

    Chỉ định những 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 gồm các trường được trả về trong phản hồi.

    Bạn nên thiết kế danh sách trường để đảm bảo rằng bạn không yêu cầu dữ liệu không cần thiết, nhờ đó tránh được các khoản phí thanh toán và thời gian xử lý 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ỉ mã nhận dạng):

      Place.Field.ID, Place.Field.NAME

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

      Place.Field.ADDRESS_COMPONENTS, Place.Field.BUSINESS_STATUS, Place.Field.ADDRESS, Place.Field.ICON_BACKGROUND_COLOR, Place.Field.ICON_URL, Place.Field.LAT_LNG, Place.Field.PHOTO_METADATAS, Place.Field.PLUS_CODE, Place.Field.TYPES, Place.Field.UTC_OFFSET, Place.Field.VIEWPORT, Place.Field.WHEELCHAIR_ACCESSIBLE_ENTRANCE

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

      Place.Field.CURRENT_OPENING_HOURS, Place.Field.SECONDARY_OPENING_HOURS, Place.Field.PHONE_NUMBER, Place.Field.PRICE_LEVEL, Place.Field.RATING, Place.Field.OPENING_HOURS, Place.Field.USER_RATINGS_TOTAL, Place.Field.WEBSITE_URI

    • Các trường sau đây kích hoạt SKU của Tìm kiếm văn bản (Ưu tiên):

      Place.Field.CURBSIDE_PICKUP, Place.Field.DELIVERY, Place.Field.DINE_IN, Place.Field.EDITORIAL_SUMMARY, Place.Field.RESERVABLE, Place.Field.REVIEWS, Place.Field.SERVES_BEER, Place.Field.SERVES_BREAKFAST, Place.Field.SERVES_BRUNCH, Place.Field.SERVES_DINNER, Place.Field.SERVES_LUNCH, Place.Field.SERVES_VEGETARIAN_FOOD, Place.Field.SERVES_WINE, Place.Field.TAKEOUT

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

  • Truy vấn bằ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 "nơi tốt nhất để ghé thăm ở San Francisco". API trả về các kết quả trùng khớp đề xuất dựa trên chuỗi này và sắp xếp các kết quả dựa trên mức độ liên quan mà người dùng 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 được bao gồm

    Giới hạn kết quả ở các vị trí khớp với loại đã 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 đưa vào, hãy gọi phương thức setIncludedType() khi tạo đối tượng SearchByTextRequest.

  • Xu hướng vị trí

    Chỉ định một vùng để tìm kiếm. Vị trí này đóng vai trò là một độ lệch, tức là có thể trả về kết quả liên quan đến vị trí đã chỉ định, bao gồm cả kết quả nằm ngoài khu vực đã chỉ định.

    Bạn có thể chỉ định quy định hạn chế về vị trí hoặc sự thiên vị về vị trí, nhưng không được chỉ định cả hai. Hãy coi việc hạn chế vị trí là việc xác định khu vực mà kết quả phải nằm trong đó, và sai lệch về vị trí là việc xác định khu vực mà kết quả phải ở gần nhưng có thể ở bên ngoài khu vực đó.

    Chỉ định khu vực dưới dạng Cửa sổ xem hình chữ nhật hoặc hình tròn.

    • Một đường tròn được xác định bởi 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 50000, 0. 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 đường chéo đối diện điểm thấp và điểm cao. Đ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.

      Một khung nhìn được coi là một khu vực đóng, có nghĩa là khu vực đó bao gồm cả ranh giới của khung nhìn đó. Giới hạn vĩ độ phải nằm trong khoảng từ -90 đến 90 độ, còn 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 một đ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 độ, 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.

      Bạn phải điền cả giá trị thấp và cao và không được để trống ô được đại diện. Khung nhìn trống dẫn đến lỗi.

      Ví dụ: về 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ố độ lệch của vị trí, hãy gọi phương thức setLocationBias() khi tạo đối tượng SearchByTextRequest.

  • Hạn chế vị trí

    Chỉ định một vùng để 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 một 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 sự thiên vị về vị trí, nhưng không được chỉ định cả hai. Hãy coi việc hạn chế vị trí là việc xác định khu vực mà kết quả phải nằm trong đó, và độ lệch vị trí là việc chỉ định khu vực mà kết quả phải ở gần nhưng có thể ở bên ngoài khu vực đó.

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

  • Số 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 thông 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ỉ cung cấp kết quả cho những người dùng 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 đến 5 (bao gồm) và tăng từng 0,5. Ví dụ: bao gồm 0, 0.5, 1.0, ... , 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ỏ mọi kết quả có điểm xếp hạng nhỏ hơn 1.

    Để đặt thông số 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 là true, hãy 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, hãy trả về tất cả cá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 Địa điểm sẽ được trả về nếu bạn đặt tham số này thành false.

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

  • Các mức giá

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

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

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

  • Tùy chọn xếp hạng

    Chỉ định cách xếp hạng kết quả trong phản hồi dựa trên loại cụm từ tìm kiếm:

    • Đối với cụm từ tìm kiếm theo danh mục, chẳng hạn 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 với cụm từ tìm kiếm) là giá trị 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 cụm từ tìm kiếm không theo danh mục, chẳng hạn như "Mountain View, CA", bạn không nên đặt thông số lựa chọn ưu tiên về thứ 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 hai ký tự. Tham số này cũng có thể gây ả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ã khu vực, thì mã quốc gia sẽ bị bỏ qua khỏi địa chỉ.

    Hầu hết mã CLDR đều giống với mã ISO 3166-1, với một số 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 của mã này là "gb" (về mặt kỹ thuật là "Vương quốc Anh" và Bắc Ireland). Tuỳ theo luật hiện hành, thông số này có thể ảnh hưởng đến kết quả.

    Để đặ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 sử dụng với tham số loại bao gồm. Khi bạn đặt thành true, chỉ những vị trí khớp với kiểu đã chỉ định do loại dữ liệu bao gồm chỉ định mới được trả về. Khi là false, giá trị 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.

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