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.IDvàPlace.Field.DISPLAY_NAME. Điều đó có nghĩa là các đối tượngPlacetrong 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ượngSearchByTextRequestxá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
OnSuccessListenervà lấy các địa điểm phù hợp từ đối tượngSearchByTextResponse.
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ượngPlacecho mỗi địa điểm phù hợp.Mỗi đối tượng
Placechỉ 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.Fieldchỉ đị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 choPlace.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ụngDISPLAY_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 choPlace.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 choPlace.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 choPlace.Field.ICON_URL(không dùng nữa).
Place.Field.LOCATION*
Sử dụng thay choPlace.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 choPlace.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 choPlace.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ượngSearchByTextRequest. -
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ượngSearchByTextRequest.
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ượngSearchByTextRequest.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ượngSearchByTextRequest.- Nếu
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ượngSearchByTextRequest.-
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ượngSearchByTextRequest. 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ượngSearchByTextRequest.Đ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ếufalse, 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ànhfalse.Để đặt tham số đang mở, hãy gọi phương thức
setOpenNow()khi tạo đối tượngSearchByTextRequest.-
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ượngSearchByTextRequest. 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ànhSearchByTextRequest.RankPreference.RELEVANCEhoặcSearchByTextRequest.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ượngSearchByTextRequest.- Đối với cụm từ tìm kiếm theo danh mục như "Nhà hàng ở Thành phố New York",
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ượngSearchByTextRequest.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ề. Khifalse(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ượngSearchByTextRequest.