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ề địa điểm, bao gồm cả tên và địa chỉ của địa điểm, thông tin địa lý vị trí được chỉ định là toạ độ vĩ độ/kinh độ, kiểu địa điểm (như như hộp đêm, cửa hàng thú cưng, bảo tàng) và nhiều địa điểm 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 xác định một địa điểm.

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

Chiến lược phát hành đĩa đơn Place đối tượng cung cấp thông tin về một địa điểm cụ thể. Bạn có thể nắm được Place đối tượng theo các cách sau:

• Gọi điện PlacesClient.fetchPlace() – Xem hướng dẫn về nhận địa điểm theo mã nhận dạng.
• Gọi điện PlacesClient.findCurrentPlace() – Xem hướng dẫn về nhận địa điểm hiện tại.
  Trong khi PlacesClient.fetchPlace() hỗ trợ tất cả các trường dữ liệu địa điểm PlacesClient.findCurrentPlace() chỉ hỗ trợ một số trường dữ liệu địa điểm. Đối với danh sách các trường KHÔNG được hỗ trợ bởi findCurrentPlace(), hãy xem Hỗ trợ SDK địa điểm 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ề. Để thực hiện việc này, hãy chuyển danh sách Place.Field các giá trị 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í cho mỗi yêu cầu.

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

Ví dụ sau truyền danh sách ba Các giá trị Place.Field để chỉ định dữ liệu được 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 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 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 hiện có. Để biết danh sách đầy đủ tất cả các phương thức, hãy xem Place Tài liệu tham khảo API.

• getAddress() – Địa chỉ của địa điểm, ở dạng dễ đọc .
• getAddressComponents() – List của thành phần địa chỉ cho địa điểm này. Những 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ụ về cách tìm thành phố có một địa điểm. Không sử dụng thành phần để định dạng địa chỉ; thay vào đó, hãy gọi getAddress(), cung cấp đị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. Đã đọc tìm hiểu 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 là vĩ độ và kinh độ.
• getName() – Tên của địa điểm.

• getOpeningHours() – OpeningHours về địa điểm đó. Gọi OpeningHours.getWeekdayText() để trả về một danh sách các chuỗi thể hiệ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 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ẽ là được biểu thị là Chủ Nhật vào lúc nửa đêm và closeEvent là rỗng.

  Đối tượng Place cũng chứa getCurrentOpeningHours() phương thức trả về giờ hoạt động của một địa điểm trong bảy ngày tiếp theo và getSecondaryOpeningHours() 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 đó có hiện đang mở. 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ả Place.Field.UTC_OFFSET và Bạn có thể dùng Place.Field.OPENING_HOURS. Để đảm bảo tính chính xác kết quả, yêu cầu Place.Field.BUSINESS_STATUS và Place.Field.UTC_OFFSET trường 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 có Thông tin 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 đó PlacesClient.isOpen(IsOpenRequest request). Để biết thêm thông tin, hãy xem Xem trạng thái mở.

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();

      

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 ID của một địa điểm bằng cách gọi Place.getId(). Chiến lược phát hành đĩa đơn 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 phù hợp với truy vấn tìm kiếm được cung cấp và lọc. Bạn có thể lưu trữ mã địa điểm và sử dụng mã này để truy xuất Place đối tượng một lần nữa sau đó.

Để nhận 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 theo phong cách Task. Chiến lược phát hành đĩa đơn FetchPlaceResponse chứa một Place đối tượng khớp với ID địa điểm đã cung cấp.

Ví dụ về mã sau đây cho thấy cách gọi fetchPlace() tới lấy thông tin chi tiết cho đị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 Khởi chạy ứng dụng Places API.

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

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

PlacesClient.isOpen(IsOpenRequest request) phương thức này trả về một đối tượng IsOpenResponse cho biết liệu địa điểm đó có hiện đang mở dựa trên thời gian được chỉ định trong cuộc gọi.

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

• Place hoặc một chuỗi xác định một mã địa điểm.
  Lưu ý: Đối tượng Place phải chứa tệp hợp lệ 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 truyền mã địa điểm, phương thức 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 với các trường cần thiết, xem Chi tiết địa điểm.

Lưu ý: SKU dữ liệu cơ bản của Địa điểm sẽ bị 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() trong Place.Field.CURRENT_OPENING_HOURS và Place.Field.OPENING_HOURS.

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ỉ chuyển mã địa điểm vào 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 đố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ị thuộc tính trong ứng dụng của bạn

Khi ứng dụng của bạn hiện 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 bất kỳ thông tin ghi nhận sự đóng góp nào. Để biết thêm thông tin, hãy xem phân bổ.

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

ID địa điểm được sử dụng trong SDK Địa điểm dành cho Android giống với giá trị nhận dạng như đượ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 địa điểm 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 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 sang một vị trí.

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

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