Trang này được dịch bởi Cloud Translation API.

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 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 một danh sách các địa điểm khớp với chuỗi văn bản và mọi thông tin thiên vị về vị trí đã đượ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 phải địa chỉ của chuỗi cũng có thể khớp với doanh nghiệp cũng như địa chỉ. Ví dụ về cụm từ tìm kiếm địa chỉ không rõ ràng là địa chỉ có định dạng không chính xác hoặc yêu cầu có các thành phần không phải địa chỉ, chẳng hạn như tên doanh nghiệp. Các yêu cầu như hai ví dụ đầu tiên có thể không trả về kết quả nào, 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 thiên kiến về vị trí).

Tìm kiếm bằng 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 tính năng này là tính năng 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í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" (10 High Street, Vương quốc Anh) hoặc "123 Main Street, US" (123 Main Street, Hoa Kỳ)	Nhiều "High Street" ở Vương quốc Anh; nhiều "Main Street" ở Hoa Kỳ. Cụm từ tìm kiếm không trả về kết quả mong muốn trừ phi bạn đặt một chế độ hạn chế về vị trí.
"ChainRestaurant New York"	Nhiều vị trí "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" ở thành phố Escher của Vương quốc Anh; chỉ có một "Main Street" ở 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ố để phân biệt.
"nhà hàng pizza ở New York"	Cụm từ tìm kiếm này có 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õ. Hàm này trả về nhiều kết quả.
"+1 514-670-8700"	Cụm từ tìm kiếm này có chứa số điện thoại. Hàm này trả về nhiều kết quả cho những địa điểm được 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 trên số điện thoại, hãy thêm mã quốc gia, sau đó là một khoảng trắng và đặt tham số `regionCode` tương ứng với mã quốc gia. Định dạng số điện thoại khác nhau tuỳ theo quốc gia và API sẽ cố gắng trả về kết quả cho những định dạng này.

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

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 từng địa điểm trùng khớp chỉ chứa 2 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 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 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 một OnSuccessListener và nhận 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.

Phản hồi của tính năng Tìm kiếm bằng 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. Một đối tượng SearchByTextResponse chứa:

Một danh sách các đối tượng Place đại diện cho tất cả những đị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 vào 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 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 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 kích hoạt Text Search Essentials ID Only SKU:
  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 vào tên văn bản của địa điểm.
- Các trường sau đây kích hoạt SKU Tìm kiếm văn bản chuyên nghiệp:
  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
- Các trường sau đây kích hoạt SKU Tìm kiếm văn bản dành 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 (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 (không còn được dùng nữa).
  Place.Field.WEBSITE_URI
- Các trường sau đây kích hoạt SKU Text Search 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
Lưu ý: Phiên bản 4.0 của Places SDK for 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 Places SDK for 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.
Câu hỏi 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 tham quan đẹp nhất ở San Francisco". API này trả về các kết quả khớp có thể 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 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 được đưa vào

Giới hạn 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.
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 thiên kiến, tức 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 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 độ lệch 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 độ lệch vị trí, kết quả vẫn có thể nằm ngoài khu vực được chỉ định.

Lưu ý: Nếu bạn bỏ qua cả độ lệch vị trí và hạn chế về 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ả.

Lưu ý: Bạn có thể ghi đè tham số locationBias nếu textQuery chứa một vị trí rõ ràng, chẳng hạn 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.
- Một 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,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 hiển thị 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, còn đ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 vùng khép kín, tức là bao gồm cả ranh giới của vùng đó. Phạm vi vĩ độ phải nằm trong khoảng từ -90 đến 90 độ (bao gồm cả hai giá trị này), còn phạm vi 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, 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ả 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, đồng thời hộp được biểu thị không được trống. Khung hiển thị trống sẽ gây ra lỗi.
  
  Ví dụ: về khung hiển thị hình chữ nhật, hãy xem 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 hiển thị hình chữ nhật. Xem phần mô tả về Độ lệch vị trí để biết thông tin về cách xác định Khung hiển thị.

Bạn có thể chỉ đị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 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 kiến về vị trí là việc chỉ định khu vực mà 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ả độ lệch vị trí và hạn chế về 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ố lượng kết quả tối đa

Chỉ định số lượng kết quả về đị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 kết quả 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,0 đến 5,0 (tính toàn bộ) theo mức tăng 0,5. Ví dụ: 0, 0,5, 1,0, ..., 5,0 (bao gồm). 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 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 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 tham số này thành false.

Để đặt tham số mở cửa 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á. Để hạn chế kết quả chỉ bao gồm những địa điểm ở 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ụ với giá cả phải chăng.
- 2 – Địa điểm cung cấp dịch vụ với 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 tiền.
Lưu ý: Giá trị số nguyên của 0 (cho biết rằng đị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.

Để đặt tham số cấp 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 một 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 cụm từ 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 cụm từ tìm kiếm không theo danh mục, chẳng hạn như "Mountain View, CA", bạn nên để trống 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.
Mã vùng

Mã khu vực dùng để định dạng phản hồi, được chỉ định là giá trị mã CLDR gồm 2 ký tự. Tham số này cũng có thể có 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 trong địa chỉ.

Hầu hết mã CLDR đều giống với mã ISO 3166-1, 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 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 theo loại nghiêm ngặt

Được dùng với tham số loại include. Khi được đặt thành true, chỉ những địa điểm khớp với các 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 những địa điểm không khớp với các loại được 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.

Tìm kiếm văn bản (Mới) Sử dụng bộ sưu tập để sắp xếp ngăn nắp các trang Lưu và phân loại nội dung dựa trên lựa chọn ưu tiên của bạn.

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

Phản hồi của tính năng Tìm kiếm bằng văn bản

Thông số bắt buộc

Danh sách trường

Câu hỏi dạng văn bản

Thông số tùy chọn

Loại được đưa vào

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

Hạn chế về vị trí

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

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

Đang mở

Mức giá

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

Mã vùng

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

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