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

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

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 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.v. Để 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 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 theo các cách sau:

• Gọi PlacesClient.fetchPlace() – Xem hướng dẫn lấy địa điểm theo mã nhận dạng.
• Gọi PlacesClient.findCurrentPlace() – Xem hướng dẫn lấy địa điểm hiện tại.
  Mặc dù PlacesClient.fetchPlace() hỗ trợ tất cả các trường dữ liệu địa điểm, nhưng PlacesClient.findCurrentPlace() chỉ hỗ trợ một số trường dữ liệu địa điểm. Để biết danh sách các trường KHÔNG được findCurrentPlace() hỗ trợ, hãy xem phần Hỗ trợ các trường trong SDK Địa điểm dành cho Android.

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ề. Để làm việc này, hãy truyền danh sách 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ân nhắc vì nó ả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ỉ những kết quả đị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 danh sách gồm 3 giá trị Place.Field để chỉ định dữ liệu mà một yêu cầu trả về:

Kotlin

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

Java

// 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 lấy đố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 này bị thiếu trong đối tượng Place, 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.

Để 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() – List 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 nhằm 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ố nơi một địa điểm tọa lạc. Đừ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 địa chỉ được định dạng đã 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 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ề một 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, thì khoảng thời gian sẽ được biểu thị là Chủ Nhật lúc nửa đêm và closeEvent sẽ rỗng.

  Đố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 tới và getSecondaryOpeningHours() trả về giờ hoạt động phụ của một địa điểm trong 7 ngày tới.

• isOpen() – Một 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, thời gian mặc định sẽ là hiện tại. isOpen 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. Xem video này để biết cách sử dụng isOpen với Thông tin chi tiết về địa điểm.

  Lưu ý: Phương thức này không còn đượ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();

      

Xem địa điểm theo mã

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ã đị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.

Để 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 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 cách gọi fetchPlace() để lấy thông tin chi tiết về địa điểm đã 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ỷ một 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 theo cách tốt nhất có thể. Sau khi bạn gửi yêu cầu huỷ, hệ thống sẽ không trả về phản hồi nào. 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 đang 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 từ 1970-01-01T00:00:00Z. Nếu bạn không chỉ định thời gian, thời gian mặc định sẽ là hiện tại.

Phương thức này yêu cầu các trường sau đây phải tồn tại 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ã đị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 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 ý: SKU Dữ liệu cơ bản của Places sẽ bị tính phí cho các lệnh 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 sẽ 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(), trong đó 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 phân bổ 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ủa bạn cũng phải hiển thị mọi thông tin ghi công. Để biết thêm thông tin, hãy xem phần thuộc tính phân bổ.

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

Mã địa điểm dùng trong SDK Địa điểm dành cho Android giống với giá trị nhận dạng dùng trong API Địa điểm. 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 vị trí 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 mình 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 nội dung tổng quan về mã địa điểm.