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

Tính năng 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ụ phản hồi bằng một danh sách các địa điểm phù hợp với chuỗi văn bản và mọi sai lệch vị trí đã đặt.

Dịch vụ này đặc biệt hữu ích khi tạo các truy vấn địa chỉ không rõ ràng trong 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 doanh nghiệp cũng như địa chỉ. Ví dụ về truy vấn địa chỉ không rõ ràng là địa chỉ hoặc yêu cầu có định dạng kém, chẳng hạn như tên doanh nghiệp. Các yêu cầu như 2 ví dụ đầu tiên có thể trả về 0 kết quả trừ phi 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í) được đặt.

Tính năng Tìm kiếm văn bản (Mới) tương tự như Tìm kiếm lân cận (Mới). Điểm khác biệt chính giữa 2 công cụ 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 Tìm kiếm lân cận (Mới) yêu cầu một khu vực cụ thể để tìm kiếm.

"10 High Street, UK" hoặc "123 Main Street, Hoa Kỳ"	Nhiều đường "High Street" ở Vương quốc Anh; nhiều đường "Main Street" ở 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í.
"ChainNhà hàng New York"	Nhiều địa điểm "ChainNhà hàng" ở New York; không có địa chỉ đường phố hay thậm chí không có tên đường phố.
"10 High Street, Escher UK" hoặc "123 Main Street, Pleasanton US"	Chỉ một "Đường cao tốc" ở thành phố Escher của Vương quốc Anh; chỉ một "đường Main" ở thành phố Pleasanton CA của Hoa Kỳ.
"UniqueCustomerName New York"	Chỉ 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"	Truy vấn này chứa giới hạn vị trí và "nhà hàng pizza" là loại địa điểm được xác định rõ ràng. Phương thức này trả về nhiều kết quả.
"[phone]"	Truy vấn này chứa một số điện thoại. Phương thứ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 đó. Lưu ý: Để có kết quả tốt nhất khi tìm kiếm bằng số điện thoại, hãy thêm mã quốc gia theo sau là một dấu cách và đặt tham số region code tương ứng với mã quốc gia.

Lưu ý: Tính năng Tìm kiếm văn bản (Mới) có trong SDK Địa điểm dành cho Android phiên bản 3.3.0 trở lên. Để biết thêm thông tin, hãy xem phần Chọn phiên bản SDK.

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

Lưu ý: Tính năng Tìm kiếm văn bản thuộc SDK Địa điểm dành cho Android (Mới) và không có trong SDK Địa điểm dành cho Android.

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

// 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 "Đồ ăn chay cay".

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

  • Giới hạn khu vực tìm kiếm trong khu vực tìm kiếm trong hình chữ nhật được xác định theo vĩ độ và kinh độ. Không có kết quả phù hợ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.

Bạn có thể sử dụng CancellationToken để thử huỷ một yêu cầu tới bất kỳ lớp yêu cầu nào (ví dụ: FetchPlaceRequest). Thao tác huỷ được thực hiện trên cơ sở nỗ lực tối đa. Sau khi đưa ra yêu cầu huỷ, sẽ không có phản hồi nào được trả về. Việc cung cấp mã thông báo huỷ KHÔNG đảm bảo rằng một yêu cầu cụ thể sẽ bị huỷ và bạn vẫn có thể bị tính phí cho yêu cầu ngay cả khi không có phản hồi nào được trả về.

Phản hồi cho Tìm kiếm văn bản

Lớp SearchByTextResponse biểu thị 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ả các địa điểm phù hợp, với một đối tượng Place cho mỗi nơi 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 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ể 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 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 Các trường dữ liệu của đố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 các trường dữ liệu địa điểm cần trả về. Truyền một 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 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ế hiệu quả để đảm bảo 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à chi 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 SKU của Tìm kiếm văn bản (chỉ nhận dạng):

    Place.Field.ID, Place.Field.NAME

  • Các trường sau đây kích hoạt SKU của 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 của công cụ 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 công cụ 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.

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

  Chuỗi văn bản để tìm kiếm, ví dụ: "nhà hàng", "123 Main Street" hoặc "địa điểm tốt nhất nên ghé thăm ở San Francisco". API trả về các kết quả phù hợp 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 cảm nhận được.

  Để đặ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 tệp đã bao gồm

  Giới hạn kết quả ở các vị trí khớp với loại đã chỉ định được xác định trong Bảng A. Bạn chỉ có thể chỉ định một loại. Ví dụ:

  • setIncludedType("bar")
  • setIncludedType("pharmacy")
  Lưu ý: Các giá trị trong Bảng B chỉ được trả về trong phản hồi. Bạn không thể dùng các giá trị trong Bảng B làm bộ lọc.

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

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

  Chỉ định một khu vực để tìm kiếm. Vị trí này đóng vai trò là một độ chệch nghĩa là có thể trả về các kết quả xung quanh vị trí đã chỉ định, bao gồm cả những kết quả nằm ngoài khu vực cụ thể đó.

  Bạn có thể chỉ định giới hạn vị trí hoặc thiên kiến về vị trí, nhưng không thể chỉ định cả hai. Hãy coi quy định hạn chế về vị trí là việc chỉ định khu vực chứa kết quả, còn thiên vị về vị trí là việc chỉ định khu vực nơi kết quả phải ở gần nhưng có thể nằm ngoài khu vực đó.

  Lưu ý: Nếu bạn bỏ qua cả xu hướng vị trí và hạn chế vị trí, thì API sẽ sử dụng xu hướng IP theo mặc định. Với xu hướng IP, API sẽ sử dụng địa chỉ IP của thiết bị để thiên về kết quả.
  Lưu ý: Bạn có thể ghi đè tham số locationBias nếu textQuery chứa một vị trí rõ ràng như Market in Barcelona. Trong trường hợp này, locationBias sẽ bị bỏ qua.

  Hãy chỉ định khu vực dưới dạng Khung nhìn hình chữ nhật hoặc dưới dạng vòng tròn.

  • Một đường tròn được xác định bởi đ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 đến 50000. 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 theo vĩ độ, được thể hiện dưới dạng hai điểm thấp và cao theo đường chéo đối diện. Điểm thấp đánh dấu góc phía Tây Nam của hình chữ nhật, còn điểm cao biểu thị góc phía đô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, có nghĩa là khung nhìn bao gồm ranh giới của khu vực đó. Giới hạn vĩ độ phải nằm trong khoảng từ -90 đến 90 độ và 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 điểm duy nhất đó.
    • Nếu low.longitude > high.longitude, 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.

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

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

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

• Quy định hạn chế về vị trí

  Chỉ định một khu vực để 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 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 chi tiết về cách xác định Khung nhìn.

  Bạn có thể chỉ định giới hạn vị trí hoặc thiên kiến về vị trí, nhưng không thể chỉ định cả hai. Hãy coi quy định hạn chế về vị trí là việc chỉ định khu vực chứa kết quả; còn thiên vị về vị trí là việc chỉ định khu vực nơi kết quả phải ở gần nhưng có thể nằm ngoài khu vực đó.

  Lưu ý: Nếu bạn bỏ qua cả xu hướng vị trí và hạn chế vị trí, thì API sẽ sử dụng xu hướng IP theo mặc định. Với xu hướng IP, API sẽ sử dụng địa chỉ IP của thiết bị để thiên về kết quả.

  Để đặt thông số hạn chế 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ề. Giá trị 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ỉ hiển thị kết quả cho những người có điểm xếp hạng trung bình từ 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 cả 0,5). Ví dụ: 0, 0,5, 1,0, ..., 5.0. Các giá trị được làm tròn lên đến số 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 thấp hơn 1.

  Để đặt tham 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, 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 giá trị là false, hãy trả về tất cả các doanh nghiệp, bất kể trạng thái đang mở cửa. Các đị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ố 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ả sẽ 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 ở 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 đị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ụ có giá cả vừa phải.
  • 3 – Địa điểm cung cấp các dịch vụ đắt đỏ.
  • 4 – Địa điểm cung cấp các dịch vụ rất đắt đỏ.
  Lưu ý: Giá trị số nguyên của 0 (cho biết địa điểm cung cấp dịch vụ miễn phí) có thể được đưa vào phản hồi nhưng không thể dùng làm giá trị bộ lọc trong yêu cầu.

  Để thiết lập thông số 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 truy vấn:

  • Đối với cụm từ tìm kiếm phân loại, chẳng hạn như "Nhà hàng ở thành phố New York", SearchByTextRequest.RankPreference.RELEVANCE (kết quả xếp hạng theo mức độ liên quan với nội dung tìm kiếm) là giá trị mặc định. Bạn có thể đặt lựa chọn ưu tiên xếp 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 truy vấn không phân loại, chẳng hạn như " Mountain View, CA", bạn nên không đặt thông số tùy chọ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ể ả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ã vùng, thì mã quốc gia sẽ bị loại khỏi địa chỉ.

  Hầu hết các mã CLDR đều giống hệt với mã ISO 3166-1, trừ một số trường hợp 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 là "gb" (về mặt kỹ thuật, là pháp nhân của "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.

  Để đặt tham số mã vùng, 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 đặt thành true, chỉ các vị trí khớp với loại được chỉ định do loại bao gồm (include) chỉ định mới được trả về. Khi false, theo 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 thông 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.