Tìm kiếm lân cậ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)

Nếu địa chỉ thanh toán của bạn ở Khu vực kinh tế Châu Âu, thì kể từ ngày 8 tháng 7 năm 2025, Điều khoản dịch vụ của Nền tảng Google Maps ở EEA sẽ áp dụng cho việc bạn sử dụng Dịch vụ. Chức năng này thay đổi theo khu vực. Tìm hiểu thêm.

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

Theo mặc định, phản hồi chứa các địa điểm thuộc mọi loại trong khu vực tìm kiếm. Bạn có thể lọc phản hồi (không bắt buộc) bằng cách chỉ định danh sách các loại địa điểm để đưa vào hoặc loại trừ một cách rõ ràng khỏi phản hồi. Ví dụ: bạn có thể chỉ định chỉ bao gồm những địa điểm trong phản hồ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 Places SDK for 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 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 Nearby Search (Mới)

Đưa ra 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 đối tượng SearchNearbyRequest xác định các tham số yêu cầu.

Đối tượng SearchNearbyRequest chỉ định tất cả các tham số 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 các 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ề vị trí cho khu vực tìm kiếm, được xác định là một cặp vĩ độ/kinh độ và giá trị bán kính, tính bằng mét.

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

// 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.DISPLAY_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 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ỷ 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 trên cơ sở nỗ lực tối đa. Sau khi yêu cầu huỷ được gửi, hệ thống sẽ không trả về phản hồi. 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ề.

Câu trả lời của Nearby Search (Mới)

Lớp SearchNearbyResponse biểu thị phản hồi từ một yêu cầu tìm kiếm. Một đối tượng SearchNearbyResponse 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à:

// 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 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 của đối tượng Địa điểm.

Thông số bắt buộc

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

• Danh sách trường

  Khi 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 dưới dạng một 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 đến đối tượng SearchNearbyRequest. Che phủ 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 SKU Tìm kiếm lân cận Pro:

    Place.Field.ADDRESS_COMPONENTS
Place.Field.BUSINESS_STATUS
Place.Field.ADDRESS
Place.Field.DISPLAY_NAME >*
        * Sử dụng thay cho Place.Field.NAME (không được dùng nữa).
    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.ID
Place.Field.LAT_LNG
Place.Field.PHOTO_METADATAS
Place.Field.PLUS_CODE
Place.Field.PRIMARY_TYPE
Place.Field.PRIMARY_TYPE_DISPLAY_NAME
Place.Field.RESOURCE_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 SKU Tìm kiếm lân cậ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 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 dùng nữa).
    Place.Field.WEBSITE_URI

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

  Ví dụ sau đây xác định một danh sách gồm 2 giá trị trường để chỉ định rằng đối tượng Place do một yêu cầu trả về chứa các trường Place.Field.ID và Place.Field.DISPLAY_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.DISPLAY_NAME);

• Hạn chế về vị trí

  Một đối tượng LocationRestriction xác định khu vực cần tìm kiếm được chỉ định dưới dạng một vòng tròn, được xác định bằng điểm trung 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 và nhỏ hơn hoặc bằng 50000, 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 tham số hạn chế vị trí, hãy gọi phương thức setLocationRestriction() khi tạo đối tượng SearchNearbyRequest.

Thông số tùy chọn

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

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

  Cho phép bạn chỉ định một danh sách các loại trong bảng 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ế về 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 số các loại thuộc Bảng A được liên kết với địa điểm đó. 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ả theo loại 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 được liên kết với địa điểm đó. Ví dụ: một nhà hàng có thể có các loại sau: "seafood_restaurant", "restaurant", "food", "point_of_interest", "establishment". Sử dụng includedTypes và excludedTypes để lọc kết quả trong danh sách các loại được liên kết với một địa điểm.

  Khi bạn chỉ định một loại chính chung, chẳng hạn như "restaurant" hoặc "hotel", phản hồi có thể chứa những địa điểm có loại chính cụ thể hơn loại bạn chỉ định. Ví dụ: bạn chỉ định bao gồm một loại chính là "restaurant". Sau đó, phản hồi có thể chứa những địa điểm có loại chính là "restaurant", nhưng phản hồi cũng có thể chứa những địa điểm có loại chính cụ thể hơn, chẳng hạn như "chinese_restaurant" hoặc "seafood_restaurant".

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

  Nếu bạn bỏ qua includedTypes, excludedTypes, includedPrimaryTypes và excludedPrimaryTypes trong yêu cầu, thì kết quả tìm kiếm sẽ trả về các địa điểm cho tất cả các loại trong phạm vi giới hạn 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 thêm

  Danh sách các loại địa điểm trong Bảng A để tìm kiếm. Nếu bạn bỏ qua tham số này, thì các địa điểm thuộc mọi loại sẽ được trả về.

  Để đặt tham số 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 trong Bảng A cần loại trừ khỏi một cụm từ 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ì phản hồi sẽ bao gồm những địa điểm được phân loại là "school" nhưng không phải là "primary_school". Phản hồi bao gồm những địa điểm khớp với ít nhất một trong số includedTypes và không có trong số excludedTypes.

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

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

  Các loại chính được thêm

  Danh sách các loại địa điểm chính trong Bảng A để đưa vào một cụm từ tìm kiếm.

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

  Các loại chính bị loại trừ

  Danh sách các loại địa điểm chính trong Bảng A cần 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, chẳng hạn như một loại xuất hiện trong cả includedPrimaryTypes và excludedPrimaryTypes, thì lỗi INVALID_ARGUMENT sẽ được trả về.

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

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

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

  Loại thứ hạng cần sử dụng. Nếu bạn bỏ qua tham số này, kết quả sẽ được xếp hạng theo mức độ phổ biến. Có thể là một trong những giá trị 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 kết quả theo thứ tự tăng dần theo khoảng cách từ vị trí đã 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ã 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ự. Không có giá trị mặc định.

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

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

Hiển thị thông tin ghi nhận quyền tác giả trong ứng dụng

Khi hiển thị thông tin lấy từ PlacesClient, chẳng hạn như ảnh và bài đánh giá, ứng dụng của bạn cũng phải hiển thị thông tin ghi nhận bắt buộc.

Để biết thêm thông tin, hãy xem Chính sách đối với Places SDK cho Android.