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 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.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. Đây là 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

Đối tượng Place cung cấp thông tin về một địa điểm cụ thể. Bạn có thể yêu cầu lưu giữ đối tượng Place theo các cách sau:

Khi yêu cầu một địa điểm, bạn phải chỉ định những loại dữ liệu địa điểm cần trả về. Để làm việc này, hãy truyền List<Place.Field>, chỉ định loại dữ liệu cần trả về. Đây là một cân nhắc quan trọng, vì điều này sẽ ảnh hưởng đến chi phí cho mỗi yêu cầu. Do không được để trống kết quả dữ liệu địa điểm, nên chỉ những kết quả địa điểm có dữ liệu đượ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ả. Bạn có thể chỉ định một hoặc nhiều trường sau:

  • Place.Field.ADDRESS
  • Place.Field.ADDRESS_COMPONENTS
  • Place.Field.BUSINESS_STATUS
  • Place.Field.ID
  • Place.Field.LAT_LNG
  • Place.Field.NAME
  • Place.Field.OPENING_HOURS
  • Place.Field.PHONE_NUMBER
  • Place.Field.PHOTO_METADATAS
  • Place.Field.PLUS_CODE
  • Place.Field.PRICE_LEVEL
  • Place.Field.RATING
  • Place.Field.TYPES
  • Place.Field.USER_RATINGS_TOTAL
  • Place.Field.ICON_URL
  • Place.Field.ICON_BACKGROUND_COLOR
  • Place.Field.VIEWPORT
  • Place.Field.UTC_OFFSET
  • Place.Field.WEBSITE_URI

Tìm hiểu thêm về các trường địa điểm. Để biết thêm thông tin về cách tính phí các yêu cầu dữ liệu về Địa điểm, hãy xem phần Mức sử dụng và thanh toán.

Hãy sử dụng các phương thức sau để truy xuất dữ liệu từ 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ỉ cho địa điểm này. Những 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 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 đã bản địa hoá.
  • getBusinessStatus() – Trạng thái hoạt động của địa điểm, nếu đó là một doanh nghiệp. Thuộc tính này có thể chứa một trong những giá trị sau: OPERATIONAL, CLOSED_TEMPORARILY, CLOSED PERMANENTLY.
  • getAttributions() – Các thuộc tính phải hiển thị cho người dùng nếu dữ liệu của địa điểm được sử dụng.
  • 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 là vĩ độ và kinh độ.
  • getName() – Tên địa điểm.
  • getOpeningHours()OpeningHours của địa điểm. Gọi OpeningHours.getWeekdayText() để trả về danh sách các chuỗi đại diện cho 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, thì khoảng thời gian được biểu thị là Chủ Nhật vào lúc nửa đêm và closeEvent là rỗng.
  • getPhoneNumber() – Số điện thoại của địa điểm.
  • getPhotoMetadatas() – Siêu dữ liệu liên kết với một ảnh liên kết với địa điểm, bao gồm cả hình ảnh bitmap.
  • getPlusCode() – Vị trí PlusCode của Địa điểm này.
  • getPriceLevel() – Cấp giá cho địa điểm này, được trả về dưới dạng số nguyên có các giá trị từ 0 (thấp nhất) đến 4 (đắt nhất).
  • getRating() – Điểm xếp hạng tổng hợp về địa điểm, được trả về dưới dạng số thực có giá trị từ 1.0 đến 5.0, dựa trên bài đánh giá tổng hợp của người dùng.
  • getTypes() – Danh sách các loại địa điểm đặc trưng của địa điểm này. Để nắm được danh sách các loại địa điểm có sẵn, hãy xem tài liệu về giao diện Place.
  • getUserRatingsTotal() – Tổng số lượt xếp hạng của người dùng về Địa điểm này.
  • getIconUrl() – URL của mặt nạ biểu tượng màu đen đại diện cho loại địa điểm.
  • getIconBackgroundColor – Màu nền biểu tượng cho loại địa điểm.
  • getUtcOffsetMinutes() – Chênh lệch UTC, tính bằng phút.
  • getViewport() – Một khung nhìn, được trả về dưới dạng đối tượng LatLngBounds, hữu ích khi hiển thị địa điểm này trên bản đồ. Có thể trả về giá trị rỗng nếu không xác định được kích thước của địa điểm.
  • getWebsiteUri() – URI của trang web của địa điểm, nếu được biết. Đây là trang web do doanh nghiệp hoặc pháp nhân khác liên kết với địa điểm duy trì. Trả về giá trị rỗng nếu không biết trang web nào.
  • isOpen() – Boolean cho biết địa điểm này hiện đang mở cửa hay không. Nếu bạn không chỉ định thời gian, thì giá trị mặc định hiện là. isOpen sẽ chỉ được trả về nếu có cả Place.Field.UTC_OFFSETPlace.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_STATUSPlace.Field.UTC_OFFSET trong yêu cầu ban đầu về địa điểm. Nếu không yêu cầu, Google sẽ cho rằng doanh nghiệp đang hoạt động. Xem video này để biết cách sử dụng isOpen kèm thông tin chi tiết về địa điểm.

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

Java


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

      

Kotlin


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

      

Nhận địa điểm theo mã

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

Để nhận địa điểm theo mã nhận dạng, hãy gọi PlacesClient.fetchPlace(), truyền 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.

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.

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

      

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

      

Hiển thị mô hình phân bổ trong ứng dụng của bạn

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

Thông tin khác về mã địa điểm

Mã địa điểm dùng trong SDK Địa điểm dành cho Android là cùng một mã nhận dạng như đã 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 hơn một mã địa điểm. Có những trường hợp khác có thể khiến địa điểm lấy mã địa điểm mới. Chẳng hạn như khi doanh nghiệp của bạn 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 cò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ã đị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.