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 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 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 cho một địa điểm cụ thể, bạn có thể sử dụng mã địa điểm. Đây là giá trị nhận dạng ổn định giúp nhận dạng 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ể 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 dữ liệu về đị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 yếu tố quan trọng cần cân nhắc vì ả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ỉ kết quả địa điểm có dữ liệu đượ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 để 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 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 này 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 pháp 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 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. Khô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 địa chỉ đã định dạng đã được 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ạ độ theo 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ở cửa và đóng 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.

    Đố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 tiếp theo và getSecondaryOpeningHours() trả về giờ hoạt động phụ của đị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 thì thời gian sẽ chọn mặc định. isOpen 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 địa điểm ban đầu của bạn. Nếu bạn không yêu cầu, hệ thống sẽ xem như doanh nghiệp đó đang hoạt động. Hãy xem video này để biết cách sử dụng isOpen 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();

      

Dữ liệu địa điểm truy cập được thêm vào phiên bản 3.3.0

SDK Địa điểm dành cho Android phiên bản 3.3.0 thêm dữ liệu mới vào Place:

  • Loại địa điểm: Giá trị loại mới liên kết với một địa điểm.
  • Bài đánh giá: Tối đa 5 bài đánh giá cho một địa điểm.
  • Mã ngôn ngữ tên: Mã ngôn ngữ cho tên của một địa điểm.

Các phần sau đây mô tả cách truy cập dữ liệu mới này.

Truy cập các loại địa điểm mới

Mỗi địa điểm có thể có một hoặc nhiều giá trị type được liên kết với địa điểm đó. SDK Địa điểm dành cho Android phiên bản 3.3.0 bổ sung nhiều giá trị loại mới. Để xem danh sách đầy đủ, hãy xem bài viết Các loại địa điểm mở rộng.

Trong SDK Địa điểm dành cho Android phiên bản 3.2.0 trở xuống, bạn đã sử dụng phương thức Place.getTypes() để truy cập vào các giá trị loại liên kết với một địa điểm. Place.getTypes() trả về danh sách các loại dưới dạng giá trị enum được Place.Types xác định.

Phương thức Place.getPlaceTypes() trả về các giá trị loại dưới dạng danh sách giá trị chuỗi. Các giá trị được trả về tuỳ thuộc vào phiên bản SDK Địa điểm dành cho Android của bạn:

  • SDK Địa điểm dành cho Android (Mới): Trả về các chuỗi được xác định theo Bảng A và Bảng B hiển thị trên Loại địa điểm (Mới), bao gồm tất cả các loại địa điểm đã thêm vào phiên bản 3.3.0.
  • Địa điểm SDK dành cho Android: Trả về các enum do Place.Types xác định, không bao gồm các loại mới được thêm vào phiên bản 3.3.0.

Để tìm hiểu những điểm khác biệt chính giữa hai phiên bản SDK, hãy xem bài viết Chọn phiên bản SDK.

Truy cập vào các bài đánh giá về địa điểm

SDK Địa điểm dành cho Android (Mới) thêm lớp Review, chứa bài đánh giá về một địa điểm. Đối tượng Place có thể bao gồm tối đa 5 bài đánh giá.

Lớp Review cũng có thể chứa thuộc tính ghi công và tác giả. Nếu cho thấy bài đánh giá trong ứng dụng của mình, thì bạn cũng phải cho thấy mọi thông tin ghi nhận tác giả hoặc tác giả. Để biết thêm thông tin, hãy xem phần Hiển thị bài đánh giá.

Để điền bài đánh giá vào đối tượng Place, bạn phải:

  1. Bật SDK mới khi bạn Thiết lập dự án trên Google Cloud.
  2. Khởi chạy SDK mới trong một hoạt động hoặc mảnh.
  3. Thêm Place.Field.REVIEWS vào danh sách trường của yêu cầu xem thông tin chi tiết về địa điểm.
  4. Gọi PlacesClient.fetchPlace(). PlacesClient.findCurrentPlace() không hỗ trợ trường bài đánh giá.
  5. Sử dụng phương thức Place.getReviews() để truy cập vào trường dữ liệu bài đánh giá trong đối tượng Place.

Truy cập vào mã ngôn ngữ của tên địa điểm

Phương thức Place.getName() hiện có sẽ trả về một chuỗi văn bản chứa tên của một địa điểm. Để điền tên địa điểm cho đối tượng Place, bạn phải thêm Place.Field.NAME vào danh sách trường của yêu cầu thông tin chi tiết về địa điểm.

Đối tượng Place hiện chứa mã ngôn ngữ cho chuỗi tên. Để điền mã ngôn ngữ vào đối tượng Place, bạn phải:

  1. Bật SDK mới khi bạn Thiết lập dự án trên Google Cloud.
  2. Khởi chạy SDK mới trong một hoạt động hoặc mảnh.
  3. Thêm Place.Field.NAME vào danh sách trường của yêu cầu. Giá trị này định cấu hình phản hồi để đưa cả tên địa điểm và mã ngôn ngữ vào đối tượng Place.
  4. Gọi PlacesClient.fetchPlace(). PlacesClient.findCurrentPlace() không hỗ trợ trường mã ngôn ngữ.
  5. Sử dụng phương thức Place.getNameLanguageCode() để truy cập vào trường mã ngôn ngữ trong đối tượng Place.

Đặt mã vùng trong phiên bản 3.3.0

SDK Địa điểm dành cho Android (Mới) sẽ thêm tham số yêu cầu mã vùng vào Thông tin chi tiết về địa điểm. Mã vùng được dùng để định dạng phản hồi, được chỉ định dưới dạng giá trị mã CLDR gồm hai ký tự. Tham số này cũng có thể ảnh hưởng không tốt đến kết quả tìm kiếm. Không có giá trị mặc định. Bạn phải bật SDK mới để đặt mã vùng.

Nếu tên quốc gia của trường địa chỉ trong phản hồi khớp với mã vùng, thì mã quốc gia sẽ bị loại khỏi địa chỉ.

Hầu hết các mã CLDR đều giống với mã ISO 3166-1, với một số ngoại lệ đáng chú ý. Ví dụ: ccTLD (miền cấp cao nhất theo mã quốc gia) của Vương quốc Anh là "uk" (.co.uk) trong khi mã ISO 3166-1 là "gb" (về mặt kỹ thuật cho pháp nhân "Vương quốc Anh và Bắc Ireland"). Thông số này có thể ảnh hưởng đến kết quả dựa trên luật hiện hành.

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 nhận dạng 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ụ Địa điểm tự động hoàn thành cũng trả về một mã địa điểm cho từng địa điểm khớp với cụm từ tìm kiếm và bộ lọc mà bạn 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.

Để 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 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.

Ví dụ về mã sau đây cho thấy việc gọi fetchPlace() để biết 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 chưa xử lý

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ó đang 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 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.
  • 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 thì thời gian sẽ chọn mặc định.

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, 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 liệu 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 đố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 ứng dụng của bạn hiển thị thông tin về địa điểm, bao gồm cả các bài đánh giá về địa điểm, ứng dụng cũng phải cho thấy mọi thuộc tính. Để biết thêm thông tin, hãy xem phần phân bổ.

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

Mã địa điểm sử dụng trong SDK Địa điểm dành cho Android giống với mã nhận dạng sử dụng trong API Địa điểm. Mỗi mã địa điểm chỉ có thể đề cập đến một địa điểm, nhưng một địa điểm có thể có nhiều mã địa điểm. Một số 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 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 tồn tại). Tuy nhiên, xin 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 tổng quan về mã địa điểm.