Thông tin về địa điểm

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.

Places SDK for Android cung cấp cho ứng dụng của bạn thông tin phong phú về các địa điểm, bao gồm tên và địa chỉ của địa điểm, vị trí địa lý được chỉ định dưới dạng toạ độ vĩ độ/kinh độ, loại địa điểm (chẳng hạn như câu lạc bộ đêm, cửa hàng thú cưng, bảo tàng) và nhiều thông tin khác. Để truy cập vào thông tin này cho một địa điểm cụ thể, bạn có thể sử dụng mã địa điểm, một giá trị nhận dạng ổn định giúp xác định duy nhất một địa điểm.

Thông tin chi tiết về địa điểm

Đối tượng Place cung cấp thông tin về một địa điểm cụ thể. Bạn có thể lấy đối tượng Place bằng cách gọi PlacesClient.fetchPlace() – Xem hướng dẫn về cách lấy địa điểm theo mã nhận dạng.

Khi yêu cầu một địa điểm, bạn phải chỉ định dữ liệu địa điểm cần trả về. Để thực hiện việc này, hãy truyền một danh sách các giá trị Place.Field chỉ định dữ liệu cần trả về. Bạn cần cân nhắc danh sách này vì nó ảnh hưởng đến chi phí cho mỗi yêu cầu.

Vì kết quả dữ liệu về địa điểm không được để trống, nên chỉ những kết quả về địa điểm có dữ liệu mới được trả về. Ví dụ: nếu một địa điểm được yêu cầu không có ảnh, thì trường photos sẽ không xuất hiện trong kết quả.

Ví dụ sau đây truyền một danh sách gồm 3 giá trị Place.Field để chỉ định dữ liệu do một yêu cầu trả về:

Kotlin

// Specify the fields to return.
val placeFields = listOf(Place.Field.DISPLAY_NAME, Place.Field.RATING)

Java

// Specify the fields to return.
final List<Place.Field> placeFields = Arrays.asList(Place.Field.DISPLAY_NAME, Place.Field.RATING);
  

Truy cập vào các trường dữ liệu đối tượng Địa điểm

Sau khi bạn nhận được đối tượng Place, hãy sử dụng các phương thức của đối tượng để truy cập vào các trường dữ liệu được chỉ định trong yêu cầu. Nếu đối tượng Place thiếu trường này, thì phương thức liên quan sẽ trả về giá trị rỗng. Dưới đây là ví dụ về một số phương thức có sẵn.

Để xem danh sách đầy đủ tất cả các phương thức, hãy xem tài liệu tham khảo về API Place.

• getAddress() – Địa chỉ của địa điểm ở định dạng mà người dùng có thể đọc được.
• getAddressComponents() – Một List gồm các thành phần địa chỉ của địa điểm này. Các thành phần này được cung cấp cho mục đích trích xuất thông tin có cấu trúc về địa chỉ của một địa điểm, ví dụ: tìm thành phố nơi một địa điểm toạ lạc. Đừng dùng các thành phần này để định dạng địa chỉ; thay vào đó, hãy gọi getAddress(), cung cấp một địa chỉ được định dạng theo ngôn ngữ địa phương.
• getId() – Giá trị nhận dạng dạng văn bản cho địa điểm. Đọc thêm về mã địa điểm ở phần còn lại của trang này.
• getLatLng() – Vị trí địa lý của địa điểm, được chỉ định dưới dạng toạ độ vĩ độ và kinh độ.
• getName() – Tên của địa điểm.

• getOpeningHours() – OpeningHours của địa điểm. Gọi OpeningHours.getWeekdayText() để trả về danh sách các chuỗi đại diện cho giờ mở cửa và giờ đóng cửa của mỗi ngày trong tuần. Gọi OpeningHours.getPeriods() để trả về danh sách các đối tượng period có thông tin chi tiết hơn tương đương với dữ liệu do getWeekdayText() cung cấp.

  Lưu ý: Nếu một địa điểm luôn mở cửa, khoảng thời gian sẽ được biểu thị là nửa đêm Chủ Nhật và closeEvent là giá trị rỗng.

  Đối tượng Place cũng chứa phương thức getCurrentOpeningHours(). Phương thức này trả về giờ hoạt động của một địa điểm trong 7 ngày tiếp theo và getSecondaryOpeningHours(). Phương thức này trả về giờ hoạt động phụ của một địa điểm trong 7 ngày tiếp theo.

• isOpen() – Giá trị boolean cho biết địa điểm có đang mở cửa hay không. Nếu bạn không chỉ định thời gian, giá trị mặc định sẽ là thời gian hiện tại. isOpen sẽ chỉ được trả về nếu cả Place.Field.UTC_OFFSET và Place.Field.OPENING_HOURS đều có sẵn. Để đảm bảo kết quả chính xác, hãy yêu cầu các trường Place.Field.BUSINESS_STATUS và Place.Field.UTC_OFFSET trong yêu cầu ban đầu về địa điểm. Nếu bạn không yêu cầu, chúng tôi sẽ giả định rằng doanh nghiệp đang hoạt động. Hãy xem video này để biết cách sử dụng isOpen với phần Chi tiết về địa điểm.

  Lưu ý: Phương thức này không được dùng nữa. Thay vào đó, hãy sử dụng PlacesClient.isOpen(IsOpenRequest request). Để biết thêm thông tin, hãy xem phần Nhận trạng thái mở.

Một số ví dụ:

Kotlin

val name = place.name
val address = place.address
val location = place.latLng

      

Java

final CharSequence name = place.getName();
final CharSequence address = place.getAddress();
final LatLng location = place.getLatLng();

      

Lấy một địa điểm theo mã nhận dạng

Mã địa điểm là giá trị nhận dạng dạng văn bản xác định duy nhất một địa điểm. Trong SDK Địa điểm dành cho Android, bạn có thể truy xuất mã nhận dạng của một địa điểm bằng cách gọi Place.getId(). Dịch vụ Tự động hoàn thành địa điểm cũng trả về mã địa điểm cho mỗi địa điểm khớp với cụm từ tìm kiếm và bộ lọc được cung cấp. Bạn có thể lưu trữ mã địa điểm và dùng mã này để truy xuất lại đối tượng Place sau này.

Để lấy một địa điểm theo mã nhận dạng, hãy gọi PlacesClient.fetchPlace(), truyền một FetchPlaceRequest.

API này trả về một FetchPlaceResponse trong Task. FetchPlaceResponse chứa một đối tượng Place khớp với mã địa điểm được cung cấp.

Ví dụ về mã sau đây cho thấy cách gọi fetchPlace() để nhận thông tin chi tiết về địa điểm được chỉ định.

Kotlin

// Define a Place ID.
val placeId = "INSERT_PLACE_ID_HERE"

// Specify the fields to return.
val placeFields = listOf(Place.Field.ID, Place.Field.NAME)

// Construct a request object, passing the place ID and fields array.
val request = FetchPlaceRequest.newInstance(placeId, placeFields)

placesClient.fetchPlace(request)
    .addOnSuccessListener { response: FetchPlaceResponse ->
        val place = response.place
        Log.i(PlaceDetailsActivity.TAG, "Place found: ${place.name}")
    }.addOnFailureListener { exception: Exception ->
        if (exception is ApiException) {
            Log.e(TAG, "Place not found: ${exception.message}")
            val statusCode = exception.statusCode
            TODO("Handle error with given status code")
        }
    }

      

Java

// Define a Place ID.
final String placeId = "INSERT_PLACE_ID_HERE";

// Specify the fields to return.
final List<Place.Field> placeFields = Arrays.asList(Place.Field.ID, Place.Field.NAME);

// Construct a request object, passing the place ID and fields array.
final FetchPlaceRequest request = FetchPlaceRequest.newInstance(placeId, placeFields);

placesClient.fetchPlace(request).addOnSuccessListener((response) -> {
    Place place = response.getPlace();
    Log.i(TAG, "Place found: " + place.getName());
}).addOnFailureListener((exception) -> {
    if (exception instanceof ApiException) {
        final ApiException apiException = (ApiException) exception;
        Log.e(TAG, "Place not found: " + exception.getMessage());
        final int statusCode = apiException.getStatusCode();
        // TODO: Handle error with given status code.
    }
});

      

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

Lấy trạng thái mở

Phương thức PlacesClient.isOpen(IsOpenRequest request) trả về một đối tượng IsOpenResponse cho biết địa điểm hiện có mở cửa hay không dựa trên thời gian được chỉ định trong lệnh gọi.

Phương thức này nhận một đối số duy nhất thuộc loại IsOpenRequest chứa:

• Một đối tượng Place hoặc một chuỗi chỉ định mã địa điểm.
  Lưu ý: Đối tượng Place phải chứa một mã địa điểm hợp lệ.
• Giá trị thời gian không bắt buộc, chỉ định thời gian tính bằng mili giây kể từ 1970-01-01T00:00:00Z. Nếu bạn không chỉ định thời gian, giá trị mặc định sẽ là thời gian hiện tại.

Phương thức này yêu cầu phải có các trường sau trong đối tượng Place:

• Place.Field.BUSINESS_STATUS
• Place.Field.CURRENT_OPENING_HOURS
• Place.Field.OPENING_HOURS
• Place.Field.UTC_OFFSET

Nếu các trường này không được cung cấp trong đối tượng Place hoặc nếu bạn truyền một mã địa điểm, thì phương thức này sẽ dùng PlacesClient.fetchPlace() để tìm nạp các trường đó. Để biết thêm thông tin về cách tạo đối tượng Place bằng các trường cần thiết, hãy xem phần Thông tin chi tiết về địa điểm.

Lưu ý: Bạn phải trả phí cho SKU Dữ liệu cơ bản của Places khi gọi đến fetchPlace() cho Place.Field.UTC_OFFSET và Place.Field.BUSINESS_STATUS. SKU Dữ liệu liên hệ của Địa điểm được tính phí cho các lệnh gọi đến fetchPlace() cho Place.Field.CURRENT_OPENING_HOURS và Place.Field.OPENING_HOURS.

Ví dụ sau đây xác định xem một địa điểm có đang mở cửa hay không. Trong ví dụ này, bạn chỉ truyền mã địa điểm đến isOpen():

Kotlin

val isOpenCalendar: Calendar = Calendar.getInstance()
val placeId = "ChIJD3uTd9hx5kcR1IQvGfr8dbk"

val request: IsOpenRequest = try {
    IsOpenRequest.newInstance(placeId, isOpenCalendar.timeInMillis)
} catch (e: IllegalArgumentException) {
    e.printStackTrace()
    return
}
val isOpenTask: Task<IsOpenResponse> = placesClient.isOpen(request)
isOpenTask.addOnSuccessListener { response ->
    val isOpen = response.isOpen
}
// ...

      

Java

@NonNull
Calendar isOpenCalendar = Calendar.getInstance();
String placeId = "ChIJD3uTd9hx5kcR1IQvGfr8dbk";
IsOpenRequest isOpenRequest;

try {
    isOpenRequest = IsOpenRequest.newInstance(placeId, isOpenCalendar.getTimeInMillis());
} catch (IllegalArgumentException e) {
    e.printStackTrace();
    return;
}

Task<IsOpenResponse> placeTask = placesClient.isOpen(isOpenRequest);

placeTask.addOnSuccessListener(
        (response) ->
                isOpen = response.isOpen());
// ...

      

Ví dụ tiếp theo cho thấy cách gọi isOpen() khi bạn truyền một đối tượng Place. Đối tượng Place phải chứa mã địa điểm hợp lệ:

Kotlin

val isOpenCalendar: Calendar = Calendar.getInstance()
var place: Place
val placeId = "ChIJD3uTd9hx5kcR1IQvGfr8dbk"
// Specify the required fields for an isOpen request.
val placeFields: List<Place.Field> = listOf(
    Place.Field.BUSINESS_STATUS,
    Place.Field.CURRENT_OPENING_HOURS,
    Place.Field.ID,
    Place.Field.OPENING_HOURS,
    Place.Field.UTC_OFFSET
)

val placeRequest: FetchPlaceRequest =
    FetchPlaceRequest.newInstance(placeId, placeFields)
val placeTask: Task<FetchPlaceResponse> = placesClient.fetchPlace(placeRequest)
placeTask.addOnSuccessListener { placeResponse ->
    place = placeResponse.place

    val isOpenRequest: IsOpenRequest = try {
        IsOpenRequest.newInstance(place, isOpenCalendar.timeInMillis)
    } catch (e: IllegalArgumentException) {
        e.printStackTrace()
        return@addOnSuccessListener
    }
    val isOpenTask: Task<IsOpenResponse> = placesClient.isOpen(isOpenRequest)
    isOpenTask.addOnSuccessListener { isOpenResponse ->
        val isOpen = isOpenResponse.isOpen
    }
    // ...
}
// ...

      

Java

@NonNull
Calendar isOpenCalendar = Calendar.getInstance();
String placeId = "ChIJD3uTd9hx5kcR1IQvGfr8dbk";
// Specify the required fields for an isOpen request.
List<Place.Field> placeFields = new ArrayList<>(Arrays.asList(
        Place.Field.BUSINESS_STATUS,
        Place.Field.CURRENT_OPENING_HOURS,
        Place.Field.ID,
        Place.Field.OPENING_HOURS,
        Place.Field.UTC_OFFSET
));

FetchPlaceRequest request = FetchPlaceRequest.newInstance(placeId, placeFields);
Task<FetchPlaceResponse> placeTask = placesClient.fetchPlace(request);

placeTask.addOnSuccessListener(
        (placeResponse) -> {
            Place place = placeResponse.getPlace();
            IsOpenRequest isOpenRequest;

            try {
                isOpenRequest = IsOpenRequest.newInstance(place, isOpenCalendar.getTimeInMillis());
            } catch (IllegalArgumentException e) {
                e.printStackTrace();
                return;
            }
            Task<IsOpenResponse> isOpenTask = placesClient.isOpen(isOpenRequest);

            isOpenTask.addOnSuccessListener(
                    (isOpenResponse) -> isOpen = isOpenResponse.isOpen());
            // ...
        });
// ...

      

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 về địa điểm (bao gồm cả bài đánh giá về địa điểm), ứng dụng cũng phải hiển thị mọi thông tin ghi nhận quyền tác giả. Để biết thêm thông tin, hãy xem phần thông tin ghi nhận quyền tác giả.

Tìm hiểu thêm về mã địa điểm

Mã địa điểm được dùng trong Places SDK for Android cũng là giá trị nhận dạng được dùng trong Places API. Mỗi mã địa điểm chỉ có thể tham chiếu đến một địa điểm, nhưng một địa điểm có thể có nhiều mã địa điểm. Có những trường hợp khác có thể khiến một địa điểm nhận được mã địa điểm mới. Ví dụ: điều này có thể xảy ra nếu một doanh nghiệp chuyển đến một địa điểm mới.

Khi yêu cầu một địa điểm bằng cách chỉ định mã địa điểm, bạn có thể yên tâm rằng bạn sẽ luôn nhận được cùng một địa điểm trong phản hồi (nếu địa điểm đó vẫn tồn tại). Tuy nhiên, hãy lưu ý rằng phản hồi có thể chứa một mã địa điểm khác với mã địa điểm trong yêu cầu của bạn.

Để biết thêm thông tin, hãy xem thông tin tổng quan về mã địa điểm.