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.
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ộtList
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ọigetAddress()
để 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ọiOpeningHours.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ọiOpeningHours.getPeriods()
để trả về danh sách các đối tượngperiod
có thông tin chi tiết hơn tương đương với dữ liệu dogetWeekdayText()
cung cấp.Đối tượng
Place
cũng chứa phương thứcgetCurrentOpeningHours()
. 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ườngPlace.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ụngisOpen
với Thông tin chi tiết về địa đ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();
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. } });
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. - 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.
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.