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

SDK địa điểm dành cho 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 là 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 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 để nhận dạng 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ể giữ đối tượng Place theo các cách sau:

• Gọi PlacesClient.findCurrentPlace() – Xem hướng dẫn để nhận địa điểm hiện tại.
• Gọi PlacesClient.fetchPlace() – Xem hướng dẫn để nhận địa điểm theo mã nhận dạng.

Khi yêu cầu cung cấp 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 chuyển danh sách giá trị Place.Field chỉ định dữ liệu cần trả về. Danh sách này cần được xem xét quan trọng vì ảnh hưởng đến chi phí cho mỗi yêu cầu.

Vì kết quả dữ liệu địa điểm không được để trống, nên chỉ trả về kết quả địa điểm có dữ liệu (ví dụ: nếu một địa điểm đã 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 sẽ truyền danh sách ba giá trị Place.Field để chỉ định dữ liệu mà một yêu cầu trả về:

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

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

Sau khi bạn có đượ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 trường bị thiếu trong đối tượng Place, phương thức liên quan sẽ trả về giá trị rỗng. Bên dưới là ví dụ về một vài phương pháp có sẵn. Để biết danh sách đầy đủ tất cả các phương thức, hãy xem tài liệu tham khảo API Place.

• getAddress() – Địa chỉ của địa điểm, ở định dạng mà con người có thể đọc được.
• getAddressComponents() – Một List thành phần địa chỉ cho địa điểm này. Những thành phần này được cung cấp để trích xuất thông tin có cấu trúc về địa chỉ của một địa điểm, ví dụ như tìm thành phố có địa điểm đó. Đừng sử 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 đã được định dạng.
• getId() – Giá trị nhận dạng dạng văn bản của địa điểm. Đọc thêm về ID địa điểm trong 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 tọa độ theo vĩ độ và kinh độ.
• getName() – Tên địa điểm.

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

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

• isOpen() – Giá trị boolean cho biết địa điểm hiện có mở cửa hay không. Nếu bạn không chỉ định thời gian thì chế độ mặc định là bây giờ. isOpen sẽ chỉ được trả về nếu có cả Place.Field.UTC_OFFSET và Place.Field.OPENING_HOURS. Để đảm bảo bạn sẽ nhận được 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 không được yêu cầu, doanh nghiệp được xem là đang hoạt động. Xem video này để biết cách sử dụng isOpen với Thông tin chi tiết về địa điểm.

Một số ví dụ đơn giản:

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

      

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

      

Nhận một địa điểm theo ID

Mã địa điểm là giá trị nhận dạng dạng văn bản giúp nhận dạng 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 đị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ột 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 tìm kiếm đượ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.

Để biết một địa điểm theo mã, hãy gọi PlacesClient.fetchPlace() rồi truyền FetchPlaceRequest.

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

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

// 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.
    }
});

      

// 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")
        }
    }

      

Nhận trạng thái mở

Phương thức PlacesClient.isOpen(IsOpenRequest request) sẽ 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 chỉ định trong lệnh gọi.

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

• Đối tượng Place hoặc một chuỗi chỉ định mã địa điểm.
• Giá trị thời gian tùy chọn chỉ định thời gian bằng mili giây từ 1970-01-01T00:00:00Z. Nếu bạn không chỉ định thời gian thì chế độ mặc định là bây giờ.

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 chuyển mã địa điểm, thì phương thức này sẽ sử dụng PlacesClient.fetchPlace() để tìm nạp chúng. Để biết thêm thông tin về cách tạo đối tượng Địa điểm 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.

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

@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());
// ...

      

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
}
// ...

      

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

@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());
            // ...
        });
// ...

      

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
    }
    // ...
}
// ...

      

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

Khi hiển thị thông tin địa điểm, ứng dụng của bạn cũng phải hiển thị thông tin ghi nhận tác giả. Hãy xem tài liệu về mô hình phân bổ.

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

ID địa điểm được sử dụng trong SDK địa điểm dành cho Android là cùng một số nhận dạng như được sử dụng trong API địa điểm. Mỗi mã địa điểm chỉ có thể đề cập đến một địa điểm, nhưng một địa điểm có thể chứa nhiều mã địa điểm. Trong một số trường hợp khác, địa điểm này có thể 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 vị trí mới.

Khi yêu cầu một địa điểm bằng cách chỉ định một mã địa điểm, bạn có thể tin tưởng 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, xin lưu ý rằng phản hồi đó có thể chứa 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 bài viết Tổng quan về mã địa điểm.