Tìm kiếm lân cận (Mới)

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

Yêu cầu Tìm kiếm lân cận (Mới) nhập khu vực để tìm kiếm được chỉ định dưới dạng một vòng tròn, được xác định theo vĩ độ và kinh độ toạ độ của tâm điểm giữa đường tròn và bán kính tính bằng mét. Chiến lược phát hành đĩa đơn yêu cầu trả về danh sách các địa điểm phù hợp, mỗi địa điểm được thể hiện bằng một Place trong khu vực tìm kiếm được chỉ định.

Theo mặc định, câu trả lời sẽ chứa mọi loại địa điểm thuộc khu vực tìm kiếm. Bạn có thể lọc câu trả lời nếu muốn bằng cách chỉ định một danh sách loại địa điểm cho thêm vào hoặc loại trừ một cách rõ ràng khỏi câu trả lời. Ví dụ: bạn có thể chỉ định để chỉ bao gồm những địa điểm đó trong câu trả lời thuộc loại "nhà hàng", "tiệm bánh" và "quán cà phê" hoặc loại trừ tất cả địa điểm thuộc loại "trường học".

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

Yêu cầu Tìm kiếm lân cận (Mới)

Thực hiện yêu cầu Tìm kiếm lân cận (Mới) bằng cách gọi PlacesClient.searchNearby, truyền một SearchNearbyRequest xác định các tham số yêu cầu.

Đối tượng SearchNearbyRequest chỉ định tất cả các thuộc tính bắt buộc và không bắt buộc cho yêu cầu. Các tham số bắt buộc bao gồm:

• Danh sách trường cần trả về trong đối tượng Place, còn được gọi là mặt nạ trường. Nếu bạn không chỉ định ít nhất một trường trong danh sách trường hoặc nếu bạn bỏ qua danh sách trường, thì lệnh gọi sẽ trả về lỗi.
• Hạn chế vị trí đối với khu vực tìm kiếm, được định nghĩa là cặp vĩ độ/kinh độ và giá trị bán kính tính bằng mét.

Ví dụ về yêu cầu tìm kiếm lân cận này chỉ định rằng các đối tượng Place phản hồi chứa các trường địa điểm Place.Field.ID và Place.Field.NAME cho mỗi trường Place đối tượng trong kết quả tìm kiếm. Thao tác này cũng lọc câu trả lời để chỉ trả lại địa điểm thuộc loại "nhà hàng" và "quán cà phê", nhưng loại trừ các địa điểm thuộc loại "pizza_nhà hàng" và "american_Nhà hàng".

// Define a list of fields to include in the response for each returned place.
final List<Place.Field> placeFields = Arrays.asList(Place.Field.ID, Place.Field.NAME);

// Define the search area as a 1000 meter diameter circle in New York, NY.
LatLng center = new LatLng(40.7580, -73.9855);
CircularBounds circle = CircularBounds.newInstance(center, /* radius = */ 1000);

// Define a list of types to include.
final List<String> includedTypes = Arrays.asList("restaurant", "cafe");
// Define a list of types to exclude.
final List<String> excludedTypes = Arrays.asList("pizza_restaurant", "american_restaurant");

// Use the builder to create a SearchNearbyRequest object.
final SearchNearbyRequest searchNearbyRequest =
SearchNearbyRequest.builder(/* location restriction = */ circle, placeFields)
    .setIncludedTypes(includedTypes)
    .setExcludedTypes(excludedTypes)
    .setMaxResultCount(10)
    .build());

// Call placesClient.searchNearby() to perform the search.
// Define a response handler to process the returned List of Place objects.
placesClient.searchNearby(searchNearbyRequest)
    .addOnSuccessListener(response -> {
      List<Place> places = response.getPlaces();
    });

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

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

Câu trả lời cho tính năng Tìm kiếm lân cận (Mới)

Chiến lược phát hành đĩa đơn SearchNearbyResponse thể hiện phản hồi từ một yêu cầu tìm kiếm. Một SearchNearbyResponse đối tượng chứa:

• Danh sách đối tượng Place đại diện cho tất cả địa điểm trùng khớp, trong đó có một địa điểm Place đối tượng cho mỗi địa điểm phù hợ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à:

// Define a list of fields to include in the response for each returned place.
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 phù hợp. Sau đó, bạn có thể dùng Place.getId() và phương thức 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 bài viết Truy cập địa điểm trường dữ liệu đối tượng.

Thông số bắt buộc

Sử dụng SearchNearbyRequest để chỉ định các tham số bắt buộc cho tìm kiếm.

• Danh sách trường

  Khi bạn yêu cầu thông tin chi tiết về địa điểm, bạn phải chỉ định dữ liệu cần trả về trong Đối tượng Place cho địa điểm làm mặt nạ trường. Để xác định mặt nạ trường, hãy truyền một mảng giá trị từ Place.Field cho đối tượng SearchNearbyRequest. Tạo mặt nạ cho 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, điều này giúp tránh thời gian xử lý và các khoản 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 tính năng Tìm kiếm lân cận (Cơ bản) SKU:

    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.ID, Place.Field.NAME, 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 tính năng Tìm kiếm lân cận (Nâng cao) SKU:

    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 tính năng Tìm kiếm lân cận (Được ưu tiên) SKU:

    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 SearchNearbyRequest.

  Ví dụ sau đây xác định danh sách hai giá trị của trường để chỉ định rằng Đối tượng Place được yêu cầu trả về chứa Place.Field.ID và Trường Place.Field.NAME:

// Define a list of fields to include in the response for each returned place.
final List<Place.Field> placeFields = Arrays.asList(Place.Field.ID, Place.Field.NAME);

• Hạn chế vị trí

  Đáp LocationRestriction đối tượng xác định vùng cần tìm kiếm được chỉ định dưới dạng một vòng tròn, được xác định bởi tâm và bán kính tính bằng mét. Bán kính phải nằm trong khoảng lớn hơn 0,0 và nhỏ hơn hoặc bằng 50000.0, xin lưu ý rằng việc chỉ định bán kính quá nhỏ sẽ trả về ZERO_RESULTS làm phản hồi.

  Để đặt thông số hạn chế vị trí, hãy thực hiện lệnh gọi setLocationRestriction() khi tạo đối tượng SearchNearbyRequest.

Thông số tùy chọn

Sử dụng SearchNearbyRequest để chỉ định các tham số không bắt buộc cho nội dung tìm kiếm.

• Loại và loại chính

  Cho phép bạn chỉ định danh sách các loại trong các loại Bảng A dùng để lọc kết quả tìm kiếm. Bạn có thể chỉ định tối đa 50 loại trong mỗi danh mục hạn chế loại.

  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.

  Một địa điểm chỉ có thể có một loại chính duy nhất trong các loại Bảng A được liên kết với nó. Ví dụ: loại chính có thể là "mexican_restaurant" hoặc "steak_house". Sử dụng includedPrimaryTypes và excludedPrimaryTypes để lọc kết quả loại hình chính của một địa điểm.

  Một địa điểm cũng có thể có nhiều giá trị loại từ các loại Bảng A liên kết với cuộc trò chuyện đó. Ví dụ: một nhà hàng có thể có các loại sau: "seafood_restaurant", "restaurant", "food" "establishment", "point_of_interest". Sử dụng includedTypes và excludedTypes để lọc kết quả trên danh sách các loại được liên kết với một địa điểm.

  Nếu nội dung tìm kiếm được chỉ định với hạn chế nhiều loại, thì chỉ địa điểm đáp ứng tất cả các hạn chế sẽ được trả về. Ví dụ: nếu bạn chỉ định includedTypes = Arrays.asList("restaurant") và excludedPrimaryTypes = Arrays.asList("steak_house"), địa điểm được trả lại cung cấp "restaurant" dịch vụ liên quan nhưng không hoạt động chủ yếu dưới dạng "steak_house".

  Nếu bạn bỏ qua includedTypes, excludedTypes, includedPrimaryTypes và excludedPrimaryTypes trong yêu cầu, thao tác tìm kiếm sẽ trả về địa điểm cho tất cả các loại trong giới hạn hạn chế về vị trí.

  Để biết ví dụ về cách sử dụng includedTypes và excludedTypes, hãy xem Yêu cầu Tìm kiếm lân cận (Mới).

  Các loại được bao gồm

  Danh sách các loại địa điểm từ Bảng A để tìm kiếm. Nếu tham số này bị bỏ qua, hàm sẽ trả về tất cả các loại địa điểm.

  Để đặt tham số các loại được đưa vào, hãy gọi phương thức setIncludedTypes() khi tạo đối tượng SearchNearbyRequest.

  Các loại bị loại trừ

  Danh sách các loại địa điểm từ Bảng A để loại trừ khỏi tìm kiếm.

  Nếu bạn chỉ định cả includedTypes (chẳng hạn như "school") và excludedTypes (chẳng hạn như "primary_school") trong yêu cầu thì hàm này câu trả lời bao gồm các địa điểm được phân loại là "school" nhưng không phải là "primary_school". Câu trả lời bao gồm các địa điểm khớp với ít nhất một của includedTypes và không có mục nào trong số excludedTypes.

  Nếu có bất kỳ loại xung đột nào, chẳng hạn như một loại xuất hiện trong cả includedTypes và excludedTypes thì hệ thống sẽ trả về lỗi INVALID_REQUEST.

  Để đặt tham số các loại bị loại trừ, hãy gọi phương thức setExcludedTypes() khi tạo đối tượng SearchNearbyRequest.

  Loại hình chính được bao gồm

  Danh sách các loại địa điểm chính từ Bảng A cần bao gồm trong một tìm kiếm.

  Để đặt tham số loại chính đi kèm, hãy gọi phương thức setIncludedPrimaryTypes() khi tạo đối tượng SearchNearbyRequest.

  Loại chính bị loại trừ

  Danh sách các loại địa điểm chính từ Bảng A để loại trừ khỏi một lượt tìm kiếm.

  Nếu có bất kỳ loại chính nào xung đột với nhau, chẳng hạn như một loại xuất hiện trong cả hai includedPrimaryTypes và excludedPrimaryTypes, một thuộc tính Trả về lỗi INVALID_ARGUMENT.

  Để đặt tham số kiểu chính bị loại trừ, hãy gọi phương thức setExcludedPrimaryTypes() khi tạo đối tượng SearchNearbyRequest.

• 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 1 và 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 SearchNearbyRequest.

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

  Loại thứ hạng sẽ sử dụng. Nếu tham số này bị bỏ qua, các kết quả được xếp hạng theo mức độ phổ biến. Có thể là một trong những trạng thái sau:

  • POPULARITY (mặc định) Sắp xếp kết quả dựa trên mức độ phổ biến.
  • DISTANCE Sắp xếp các kết quả theo thứ tự tăng dần theo khoảng cách từ vị trí được chỉ định.

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

• Mã vùng

  Mã vùng dùng để định dạng phản hồi, được chỉ định làm mã CLDR gồm hai ký tự. Không có giá trị mặc định.

  Nếu tên quốc gia của trường formattedAddress trong phản hồi khớp với regionCode, mã quốc gia bị bỏ khỏi formattedAddress.

  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 trang web là "gb" (về mặt kỹ thuật cho pháp nhân "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 SearchNearbyRequest.

Hiển thị thuộc tính trong ứng dụng của bạn

Khi ứng dụng của bạn hiển thị thông tin thu được từ PlacesClient, chẳng hạn như ảnh và bài đánh giá, thì ứng dụng cũng phải cho thấy các thông tin ghi nhận sự đóng góp cần thiết.

Để biết thêm thông tin, hãy xem Chính sách dành cho SDK địa điểm dành cho Android.