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 bằng 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 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.

Dịch vụ này đặc biệt hữu ích khi tạo 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 phải đị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ỉ có định dạng không chuẩn hoặc yêu cầu có các thành phần không phải địa chỉ như tên doanh nghiệp. Các yêu cầu như hai ví dụ đầu tiên có thể trả về kết quả rỗng trừ phi bạn đặt một vị trí (chẳng hạn như khu vực, quy định hạn chế về vị trí hoặc độ lệch vị trí).

Tìm kiếm bằng văn bản (Mới) tương tự như Tìm kiếm ở gần (Mới). Điểm khác biệt chính giữa hai loại này là Tìm kiếm bằng 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ì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, US"	Nhiều "High Street" ở Vương quốc Anh; nhiều "Main Street" ở Hoa Kỳ. Truy vấn không trả về kết quả mong muốn trừ khi bạn đặt giới hạn 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.
"10 High Street, Escher UK" hoặc "123 Main Street, Pleasanton US"	Chỉ có một "High Street" (Đường chính) ở thành phố Escher, Vương quốc Anh; chỉ có một "Main Street" (Đường chính) ở thành phố Pleasanton, California, Hoa Kỳ.
"UniqueRestaurantName New York"	Chỉ có một cơ sở có tên này ở New York; không cần địa chỉ đường để phân biệt.
"nhà hàng pizza ở New York"	Truy vấn này chứa quy định hạn chế về vị trí và "nhà hàng pizza" là một loại địa điểm được xác định rõ ràng. Hàm này trả về nhiều kết quả.
"[phone]"	Truy vấn này chứa số điện thoại. Hàm 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 số điện thoại, hãy thêm mã quốc gia, theo sau là dấu cách, rồi đặt tham số region code tương ứng với mã quốc gia.

Lưu ý: Tính năng Tìm kiếm bằng văn bản (Mới) có trong SDK Địa điểm 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. Để biết thêm thông tin về cách sử dụng các API Kotlin được thêm vào phiên bản 4.0.0, hãy xem phần Tổng quan về tài liệu tham khảo.

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

Lưu ý: Tìm kiếm văn bản là một phần của 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.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 mỗi địa điểm trùng khớ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 thành 10. Giá trị mặc định và tối đa là 20.

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

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

Lưu ý: Để biết thêm thông tin về cách khởi chạy PlacesClient, hãy xem phần Khởi chạy ứng dụng Places API.

Bạn có thể sử dụng CancellationToken để cố gắng huỷ một yêu cầu đối với bất kỳ lớp yêu cầu nào (ví dụ: FetchPlaceRequest). Việc huỷ được thực hiện theo cách tốt nhất có thể. Sau khi bạn gửi yêu cầu huỷ, hệ thống sẽ không trả về phản hồi nào. Việc phát hành mã 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ề.

Nội dung phản hồi của tính năng Tìm kiếm bằng 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ả các địa điểm trùng khớ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 do danh sách trường xác định đượ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.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 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 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 đố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 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à các khoản phí 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 Tìm kiếm bằng văn bản (chỉ mã):

    Place.Field.DISPLAY_NAME, Place.Field.ID, Place.Field.RESOURCE_NAME
    
    Lưu ý:

    • Trường Place.Field.NAME không còn được dùng nữa trong phiên bản 4.0 của SDK Địa điểm dành cho Android. Thay vào đó, hãy sử dụng Place.Field.DISPLAY_NAME.
    • Trường 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.

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

    Place.Field.ACCESSIBILITY_OPTIONS, Place.Field.ADDRESS_COMPONENTS, Place.Field.ADR_FORMAT_ADDRESS, Place.Field.BUSINESS_STATUS, Place.Field.FORMATTED_ADDRESS, Place.Field.GOOGLE_MAPS_URI, Place.Field.ICON_BACKGROUND_COLOR, Place.Field.ICON_MASK_URL, Place.Field.LOCATION, 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
    
    Lưu ý:Các trường Place.Field.ADDRESS, Place.Field.ICON_URL, Place.Field.LAT_LNG và Place.Field.WHEELCHAIR_ACCESSIBLE_ENTRANCE không còn được dùng trong phiên bản 4.0 của SDK Địa điểm dành cho Android. Thay vào đó, hãy sử dụng Place.Field.FORMATTED_ADDRESS, Place.Field.ICON_MASK_URL, Place.Field.LOCATION và Place.ACCESSIBILITY_OPTIONS tương ứng. Place.Field.ACCESSIBILITY_OPTIONS chỉ dùng được cho Thông tin chi tiết về địa điểm (Mới).

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

    Place.Field.CURRENT_OPENING_HOURS, Place.Field.CURRENT_SECONDARY_OPENING_HOURS Place.Field.INTERNATIONAL_PHONE_NUMBER, 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 Place.Field.WEBSITE_URI
    
    Lưu ý:Các trường Place.Field.PHONE_NUMBER và Place.Field.USER_RATINGS_TOTAL không còn được dùng trong phiên bản 4.0 của SDK Địa điểm dành cho Android. Thay vào đó, hãy sử dụng Place.Field.INTERNATIONAL_PHONE_NUMBER và Place.USER_RATING_COUNT tương ứng.

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

    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
  Lưu ý: Phiên bản 4.0 của SDK Địa điểm dành cho Android đã ngừng sử dụng một số trường dữ liệu Địa điểm và thêm các trường mới. Để biết thêm thông tin, hãy xem bài viết Di chuyển sang các trường dữ liệu Địa điểm mới trong SDK Địa điểm dành cho Android 4.0 .

  Để đặ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 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 tham quan tốt nhất ở San Francisco". API này trả về các kết quả trùng khớ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 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 đưa vào

  Hạn chế kết quả ở những đị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ụ:

  • 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ể sử dụng các giá trị trong Bảng B làm bộ lọc.

  Để đặ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.

• Sự 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à độ lệch, nghĩa là kết quả xung quanh vị trí đã chỉ định có thể được trả về, bao gồm cả kết quả bên ngoài khu vực đã chỉ định.

  Bạn có thể chỉ định giới hạn vị trí hoặc thiên vị 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 đó và thiên vị vị trí là việc chỉ định khu vực mà kết quả có thể 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 đã chỉ định.

  Lưu ý: Nếu bạn bỏ qua cả độ lệch vị trí và hạn chế vị trí, thì theo mặc định, API sẽ sử dụng độ lệch IP. Với tính năng thiên vị IP, API 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.

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

  • Đường 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 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à 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 kín, nghĩa là bao gồm cả ranh giới của vùng đó. 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 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 sẽ 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ì dải 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, đồng thời hộp được biểu thị không được để trống. Khung nhìn trống sẽ 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 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. Hệ thống sẽ không trả về kết quả nằm ngoài khu vực đã chỉ định. Chỉ định vùng này dưới dạng Khung nhìn hình chữ nhật. Hãy xem phần mô tả về Thiên vị vị trí để biết thông tin 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 vị vị trí, nhưng không được chỉ định cả hai. Hãy coi quy tắc hạn chế về vị trí là việc chỉ định khu vực mà kết quả phải nằm trong đó và thiên vị về vị trí là việc chỉ định khu vực mà kết quả phải nằm gần nhưng có thể nằm ngoài khu vực đó.

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

  Để đặ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ố 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ỉ giới hạn kết quả ở những người dùng có điểm xếp hạng trung bình từ người dùng lớn hơn hoặc bằng hạn mức này. Giá trị phải nằm trong khoảng từ 0 đến 5 (tính cả hai giá trị này) với mức tăng 0,5. Ví dụ: 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ỏ 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 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, 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 Google Places sẽ được trả về nếu bạn đặt thông số này thành false.

  Để đặt thông số mở ngay, 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á. Để chỉ cho phép kết quả bao gồm những địa điểm ở một số 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 các mức giá của những đị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ó mức giá vừa phải.
  • 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 đỏ.
  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 được dùng làm giá trị bộ lọc trong yêu cầu.

  Để đặ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à 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 truy vấn không theo danh mục như "Mountain View, CA", bạn nên không đặt thông số ưu tiên thứ hạng.

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

• Mã vùng

  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ể gây ra hiệu ứng thiên vị đố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 mã CLDR giống hệt 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 là "gb" (về mặt kỹ thuật là cho thực thể "Vương quốc Anh và Bắc Ireland"). Thông 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 được đặt thành true, chỉ những địa điểm khớp với loại được chỉ định theo loại bao gồm mới được trả về. Khi false, mặc định, phản hồi có thể chứa các địa điểm không khớp với các loại được 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.