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:

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

    Đố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_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ẽ 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.

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

      

Truy cập dữ liệu địa điểm đượ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 bổ sung dữ liệu mới vào Place:

  • Loại địa điểm: Giá trị loại mới được 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 địa điểm.

Bạn phải bật SDK Địa điểm dành cho Android (Mới) để truy cập vào dữ liệu này. Để tìm hiểu những điểm khác biệt chính giữa 2 phiên bản SDK, hãy xem phần Chọn phiên bản SDK.

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

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

Mỗi địa điểm có thể được liên kết với một hoặc nhiều giá trị type. 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. Để biết danh sách đầy đủ, hãy xem phần 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ở về trước, bạn đã sử dụng phương thức Place.getTypes() để truy cập 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 các 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 và xuất hiện trên Loại địa điểm (Mới), bao gồm mọi loại địa điểm đã thêm vào phiên bản 3.3.0.
  • SDK Địa điểm 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 các điểm khác biệt chính giữa 2 phiên bản SDK, hãy xem bài viết Chọn phiên bản SDK.

Xem 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ể chứa tối đa 5 bài đánh giá.

Lớp Review cũng có thể chứa một thuộc tính 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 hiển thị thông tin ghi công 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 nội dung đá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. Đưa Place.Field.REVIEWS vào danh sách trường của yêu cầu 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 địa điểm. Để điền tên địa điểm vào đối tượng Place, bạn phải đưa 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 sẵ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. Đưa 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 thông số yêu cầu mã khu vực vào Thông tin chi tiết về địa điểm. Mã vùng dùng để định dạng phản hồi, được chỉ định dưới dạng giá trị mã CLDR hai ký tự. Tham số này cũng có thể ảnh hưởng đế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 giống hệt 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 là mã của pháp nhân "Vương quốc Anh và Bắc Ireland"). Tham 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 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.