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 nhiều thông tin 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 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.v. Để 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à một giá trị nhận dạng cố đị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ể nắm giữ đối tượng Place theo những cách sau:

• Gọi PlacesClient.fetchPlace() – Xem hướng dẫn về cách tìm địa điểm theo mã nhận dạng.
• Gọi PlacesClient.findCurrentPlace() – Xem hướng dẫn để tải đị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 của 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 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 điểm quan trọng bạn cần cân nhắc vì nó ảnh hưởng đến chi phí cho mỗi yêu cầu.

Vì không thể để trống kết quả dữ liệu địa điểm, nên chỉ kết quả đị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 chuyển danh sách ba giá trị Place.Field (Địa điểm) để 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 đố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 thiếu trường đó trong đối tượng Place, 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ó thể sử dụng. Để 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 có thể đọc được.
• getAddressComponents() – Một List 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 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 có một địa điểm. Đừ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 đã bản địa hoá.
• getId() – Giá trị nhận dạng dạng văn bản cho đị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 theo 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 thể hiện giờ mở 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 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 vào lúc nửa đêm 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() trả về giờ hoạt động phụ của một địa điểm trong 7 ngày tiếp theo.

• isOpen() – Một 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à 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 bạn không yêu cầu, hệ thống 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 Xem trạng thái đang mở cửa.

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

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ã địa điể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ộ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 vào lúc khác.

Để biết 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 sẽ 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.

Mã ví dụ sau đây cho thấy việc 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.
    }
});

      

Bạn có thể sử dụng CancellationToken để thử huỷ một yêu cầu tới bất kỳ lớp yêu cầu nào (ví dụ: FetchPlaceRequest). Thao tác huỷ được thực hiện trên cơ sở nỗ lực tối đa. Sau khi đưa ra yêu cầu huỷ, sẽ không có phản hồi nào được trả về. Việc cung cấp mã thông báo 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ề.

Xem trạng thái đang 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 có đang mở cửa dựa trên thời gian được chỉ định trong lệnh gọi hay không.

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.
  Lưu ý: Đối tượng Place phải chứa một mã địa điểm hợp lệ.
• Một 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, giá trị mặc định sẽ là bây giờ.

Phương thức này yêu cầu các trường sau đây 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ột 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.

Lưu ý: SKU dữ liệu cơ bản của Địa điểm sẽ được tính phí cho các cuộc gọi đến fetchPlace() trong 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 cuộc 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 hiện có đang mở cửa hay không. Trong ví dụ này, bạn chỉ chuyể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 việc gọi isOpen() trong đó bạn truyền một đối tượng Place. Đối tượng Place phải chứa một 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ị thuộc tính trong ứng dụng của bạn

Khi cho thấy 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 cho thấy mọi thông tin thuộc tính. Để biết thêm thông tin, hãy xem nội dung phân bổ.

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

Mã địa điểm được sử dụng trong SDK Địa điểm dành cho Android giống với mã nhận dạng được sử 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ụ: tình trạng này có thể xảy ra nếu một doanh nghiệp chuyển đến đị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 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, 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ã 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.