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 theo vĩ độ/kinh độ, loại địa điểm (chẳng hạn như hộp đê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 về một địa điểm cụ thể, bạn có thể sử dụng mã địa điểm. Đây là giá trị nhận dạng ổn định giúp xác định chính xác 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.fetchPlace() – Xem hướng dẫn về cách nhận địa điểm theo mã nhận dạng.
• Gọi PlacesClient.findCurrentPlace() – Xem hướng dẫn để nhận địa điểm hiện tại.

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 chuyển danh sách các giá trị Place.Field chỉ định dữ liệu cần trả về. Danh sách này là một yếu tố quan trọng cần được cân nhắc vì ảnh hưởng đến chi phí của mỗi yêu cầu.

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

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

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

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

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 đối tượng Place bị 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 hiện có. Để biết danh sách đầy đủ tất 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() – List của các thành phần địa chỉ cho đị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, chẳng hạn như tìm thành phố có địa điểm đó. Khô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 bản địa hoá.
• getId() – Giá trị nhận dạng dạng văn bản của địa điểm. Hãy đọc thêm về mã đị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 xác định bằng toạ độ theo vĩ độ và kinh độ.
• getName() – Tên của địa điểm.

• getOpeningHours() – OpeningHours của địa điểm. Gọi OpeningHours.getWeekdayText() để trả về một danh sách các chuỗi đại diện cho giờ mở cửa và đóng cửa mỗi ngày trong tuần. Gọi OpeningHours.getPeriods() để trả về danh sách đố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.

  Đối tượng Place cũng chứa phương thức getCurrentOpeningHours() (trả về giờ hoạt động của một địa điểm trong 7 ngày tiếp theo) và getSecondaryOpeningHours() (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 hiện 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à ngay 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 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 địa điểm ban đầu của bạn. Nếu người dùng không yêu cầu, trang web sẽ xem như doanh nghiệp đ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:

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

      

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

      

Tìm 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 giúp 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ộ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 đã cung cấp. Bạn có thể lưu trữ mã địa điểm và sử dụng mã này để truy xuất lại đối tượng Place sau này.

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

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

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

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

      

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

      

Xem trạng thái mở cửa

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 được chỉ định trong lệnh gọi.

Phương thức này 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 tuỳ chọn chỉ định thời gian tính bằng mili giây từ 1970-01-01T00:00:00Z. Nếu bạn không chỉ định thời gian, giá trị mặc định sẽ là ngay bây giờ.

Phương thức này yêu cầu phải có các trường sau đây 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 các trường đó. Để biết thêm thông tin về cách tạo đối tượng Địa điểm với 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 đây xác định liệu 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():

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

      

@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(), trong đó bạn truyền đối tượng Place. Đối tượng Place phải chứa mã địa điểm hợp lệ:

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

      

@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ị 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 về địa điểm, bao gồm cả bài đánh giá về địa điểm, thì ứng dụng cũng phải cho thấy mọi thuộc tính. Để biết thêm thông tin, hãy xem phần phân bổ.

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

Mã địa điểm được dùng trong Places SDK dành cho Android giống với mã nhận dạng 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ã địa điểm khác vớ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.