Tự động hoàn thành (Mới)

Chọn nền tảng: Android iOS JavaScript Dịch vụ web

Tính năng Tự động hoàn thành (Mới) trả về thông tin dự đoán về địa điểm để phản hồi một yêu cầu bao gồm một chuỗi tìm kiếm văn bản và các giới hạn địa lý kiểm soát khu vực tìm kiếm. Tính năng tự động điền có thể so khớp dựa trên từ đầy đủ và chuỗi con của dữ liệu đầu vào, phân giải tên địa điểm, địa chỉ và mã địa lý. Ứng dụng của bạn có thể gửi truy vấn khi người dùng nhập để cung cấp thông tin dự đoán về vị trí và truy vấn ngay lập tức.

Ví dụ: bạn gọi tính năng Tự động hoàn thành bằng cách sử dụng một chuỗi chứa một phần dữ liệu đầu vào của người dùng, "Sicilian piz", với khu vực tìm kiếm giới hạn ở San Francisco, California. Sau đó, phản hồi sẽ chứa danh sách các dự đoán về địa điểm khớp với chuỗi tìm kiếm và khu vực tìm kiếm, chẳng hạn như nhà hàng có tên "Sicilian Pizza Kitchen".

Thông tin dự đoán về địa điểm được trả về được thiết kế để hiển thị cho người dùng nhằm hỗ trợ họ chọn địa điểm mong muốn. Bạn có thể tạo yêu cầu Thông tin chi tiết về địa điểm (Mới) để biết thêm thông tin về bất kỳ kết quả dự đoán địa điểm nào được trả về.

Yêu cầu tự động hoàn thành (Mới)

Ứng dụng của bạn có thể nhận danh sách tên địa điểm và/hoặc địa chỉ được dự đoán từ API tự động hoàn thành bằng cách gọi PlacesClient.findAutocompletePredictions(), truyền đối tượng FindAutocompletePredictionsRequest. Ví dụ bên dưới cho thấy một lệnh gọi hoàn chỉnh đến PlacesClient.findAutocompletePredictions().

Places.initializeWithNewPlacesApiEnabled(context, apiKey);
final List<Field> placeFields = getPlaceFields();
LatLng center = new LatLng(37.7749, -122.4194);
CircularBounds circle = CircularBounds.newInstance(center, /* radius = */ 5000);
final FindAutocompletePredictionsRequest autocompletePlacesRequest =
    FindAutocompletePredictionsRequest.builder()
            .setQuery("Sicilian piz")
            .setRegionCode("ES")
            .setLocationRestriction(circle)
            .build());
placesClient.findAutocompletePredictions(autoCompletePlacesRequest)
    .addOnSuccessListener(
        (response) -> {
            List<AutocompletePrediction> predictions = response.getResult().getAutocompletePredictions();
          }
    ).addOnFailureListener(
        exception -> {
            Log.e(TAG, "some exception happened" + exception.getMessage());
        })
    );

Câu trả lời tự động hoàn thành (Mới)

API trả về một FindAutocompletePredictionsResponse trong Task. FindAutocompletePredictionsResponse chứa danh sách tối đa 5 đối tượng AutocompletePrediction đại diện cho các địa điểm được dự đoán. Danh sách có thể trống nếu không có địa điểm nào được biết tương ứng với truy vấn và tiêu chí lọc.

Đối với mỗi địa điểm được dự đoán, bạn có thể gọi các phương thức sau để truy xuất thông tin chi tiết về địa điểm:

  • getFullText(CharacterStyle) trả về toàn bộ văn bản của nội dung mô tả địa điểm. Đây là sự kết hợp giữa văn bản chính và văn bản phụ. Ví dụ: "Tháp Eiffel, Đại lộ Anatole France, Paris, Pháp". Ngoài ra, phương thức này cho phép bạn làm nổi bật các phần mô tả khớp với nội dung tìm kiếm bằng một kiểu mà bạn chọn, sử dụng CharacterStyle. Bạn không bắt buộc phải sử dụng tham số CharacterStyle. Đặt giá trị này thành rỗng nếu bạn không cần làm nổi bật.
  • getPrimaryText(CharacterStyle) trả về văn bản chính mô tả một địa điểm. Đây thường là tên của địa điểm. Ví dụ: "Tháp Eiffel" và "123 Pitt Street".
  • getSecondaryText(CharacterStyle) trả về văn bản phụ của nội dung mô tả địa điểm. Ví dụ: điều này sẽ hữu ích khi hiển thị dòng thứ hai khi hiển thị nội dung dự đoán tự động hoàn thành. Ví dụ: "Avenue Anatole France, Paris, France" và "Sydney, New South Wales".
  • getPlaceId() trả về mã địa điểm của địa điểm được dự đoán. Mã địa điểm là giá trị nhận dạng văn bản giúp xác định duy nhất một địa điểm. Bạn có thể sử dụng mã này để truy xuất lại đối tượng Place sau này. Để biết thêm thông tin về mã địa điểm trong tính năng Tự động hoàn thành, hãy xem phần Thông tin chi tiết về địa điểm (Mới). Để biết thông tin chung về mã địa điểm, hãy xem phần Tổng quan về mã địa điểm.
  • getTypes() trả về danh sách các loại địa điểm liên kết với địa điểm này.
  • getDistanceMeters() trả về khoảng cách theo đường thẳng tính bằng mét giữa địa điểm này và điểm gốc được chỉ định trong yêu cầu.

Thông số bắt buộc

  • Truy vấn

    Chuỗi văn bản cần tìm kiếm. Chỉ định từ đầy đủ và chuỗi con, tên địa điểm, địa chỉ và mã địa điểm. Dịch vụ Tự động hoàn thành (Mới) sẽ trả về các kết quả trùng khớp dựa trên chuỗi này và sắp xếp kết quả dựa trên mức độ liên quan được nhận thấy.

    Để đặt tham số truy vấn, hãy gọi phương thức setQuery() khi tạo đối tượng FindAutocompletePredictionsRequest.

Thông số tùy chọn

  • Loại chính

    Danh sách gồm tối đa 5 giá trị loại từ loại Bảng A hoặc Bảng B dùng để lọc các địa điểm được trả về trong phản hồi. Một địa điểm phải khớp với một trong các giá trị loại chính được chỉ định để được đưa vào phản hồi.

    Một địa điểm chỉ có thể có một loại chính trong số các loại Bảng A hoặc Bảng B được liên kết với địa điểm đó. Ví dụ: loại chính có thể là "mexican_restaurant" hoặc "steak_house".

    Yêu cầu sẽ bị từ chối kèm theo lỗi INVALID_REQUEST nếu:

    • Chỉ định nhiều hơn 5 loại.
    • Mọi loại không được nhận dạng sẽ được chỉ định.

    Để đặt tham số loại chính, hãy gọi phương thức setTypesFilter() khi tạo đối tượng FindAutocompletePredictionsRequest.

  • Quốc gia

    Chỉ bao gồm kết quả từ danh sách quốc gia được chỉ định, được chỉ định dưới dạng danh sách gồm tối đa 15 giá trị gồm hai ký tự ccTLD ("miền cấp cao nhất"). Nếu bạn bỏ qua, hệ thống sẽ không áp dụng quy định hạn chế nào cho phản hồi. Ví dụ: để giới hạn các khu vực ở Đức và Pháp:

    Nếu bạn chỉ định cả locationRestriction và includedRegionCodes, kết quả sẽ nằm trong vùng giao nhau của hai chế độ cài đặt.

    Để đặt tham số quốc gia, hãy gọi phương thức setCountries() khi tạo đối tượng FindAutocompletePredictionsRequest.

  • Độ lệch đầu vào

    Độ dời ký tự Unicode dựa trên 0 cho biết vị trí con trỏ trong truy vấn. Vị trí con trỏ có thể ảnh hưởng đến kết quả dự đoán được trả về. Nếu để trống, giá trị này sẽ mặc định là độ dài của truy vấn.

    Để đặt tham số độ dời đầu vào, hãy gọi phương thức setInputOffset() khi tạo đối tượng FindAutocompletePredictionsRequest.

  • Sự thiên vị về vị trí hoặc hạn chế về vị trí

    Bạn có thể chỉ định một độ lệch vị trí hoặc hạn chế vị trí, nhưng không được chỉ định cả hai để xác định khu vực tìm kiếm. Hãy coi quy tắc hạn chế vị trí là việc chỉ định khu vực mà kết quả phải nằm trong đó và thiên vị vị trí là việc chỉ định khu vực mà kết quả phải nằm gần đó. Điểm khác biệt chính là với độ lệch vị trí, kết quả nằm ngoài khu vực được chỉ định vẫn có thể được trả về.

    • Sự thiên vị về vị trí

      Chỉ định một khu vực để tìm kiếm. Vị trí này đóng vai trò là một độ lệch, chứ không phải là một quy định hạn chế, vì vậy, hệ thống vẫn có thể trả về kết quả bên ngoài khu vực đã chỉ định.

      Để đặt tham số độ lệch vị trí, hãy gọi phương thức setLocationBias() khi tạo đối tượng FindAutocompletePredictionsRequest.

    • Hạn chế về vị trí

      Chỉ định một khu vực để tìm kiếm. Hệ thống sẽ không trả về kết quả nằm ngoài khu vực đã chỉ định.

      Để đặt thông số hạn chế vị trí, hãy gọi phương thức setLocationRestriction() khi tạo đối tượng FindAutocompletePredictionsRequest.

    Chỉ định khu vực hạn chế vị trí hoặc khu vực thiên vị vị trí dưới dạng Chế độ xem hình chữ nhật hoặc hình tròn.

    • Đường tròn được xác định bằng tâm điểm và bán kính tính bằng mét. Bán kính phải nằm trong khoảng từ 0 đến 50000. Giá trị mặc định là 0.0. Đối với quy định hạn chế về vị trí, bạn phải đặt bán kính thành một giá trị lớn hơn 0.0. Nếu không, yêu cầu sẽ không trả về kết quả nào.

    • Hình chữ nhật là khung nhìn vĩ độ-kinh độ, được biểu thị dưới dạng hai điểm low và high đối diện nhau theo đường chéo. Khung nhìn được coi là một vùng kín, nghĩa là bao gồm cả ranh giới của vùng đó. Giới hạn vĩ độ phải nằm trong khoảng từ -90 đến 90 độ và giới hạn kinh độ phải nằm trong khoảng từ -180 đến 180 độ:

      • Nếu low = high, khung nhìn sẽ bao gồm một điểm duy nhất đó.
      • Nếu low.longitude > high.longitude, thì dải kinh độ sẽ bị đảo ngược (khung nhìn cắt ngang đường kinh độ 180 độ).
      • Nếu low.longitude = -180 độ và high.longitude = 180 độ, thì khung nhìn sẽ bao gồm tất cả kinh độ.
      • Nếu low.longitude = 180 độ và high.longitude = -180 độ, thì phạm vi kinh độ sẽ trống.

      Bạn phải điền cả low và high và hộp được biểu thị không được để trống. Khung nhìn trống sẽ dẫn đến lỗi.

  • Điểm gốc

    Điểm gốc để tính khoảng cách theo đường thẳng đến đích (truy cập bằng getDistanceMeters()). Nếu bạn bỏ qua giá trị này, thì khoảng cách theo đường thẳng sẽ không được trả về. Phải được chỉ định dưới dạng tọa độ vĩ độ và kinh độ:

    Để đặt tham số gốc, hãy gọi phương thức setOrigin() khi tạo đối tượng FindAutocompletePredictionsRequest.

  • Mã vùng

    Mã khu vực dùng để định dạng phản hồi, bao gồm cả định dạng địa chỉ, được chỉ định dưới dạng giá trị hai ký tự ccTLD ("miền cấp cao nhất"). Hầu hết mã ccTLD giống với mã ISO 3166-1, ngoại trừ một số trường hợp ngoại lệ đáng chú ý. Ví dụ: ccTLD 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à cho thực thể "Vương quốc Anh và Bắc Ireland").

    Nếu bạn chỉ định mã vùng không hợp lệ, API sẽ trả về lỗi INVALID_ARGUMENT. Thông số này có thể ảnh hưởng đến kết quả dựa trên luật hiện hành.

    Để đặt tham số mã khu vực, hãy gọi phương thức setRegionCode() khi tạo đối tượng FindAutocompletePredictionsRequest.

  • Mã thông báo phiên

    Mã thông báo phiên là các chuỗi do người dùng tạo, theo dõi các lệnh gọi Tự động hoàn thành (Mới) dưới dạng "phiên". Tính năng tự động hoàn thành sử dụng mã thông báo phiên để nhóm các giai đoạn truy vấn và lựa chọn của một lượt tìm kiếm tự động hoàn thành của người dùng thành một phiên riêng biệt cho mục đích thanh toán. Phiên bắt đầu khi người dùng bắt đầu nhập truy vấn và kết thúc khi họ chọn một địa điểm. Mỗi phiên có thể có nhiều cụm từ tìm kiếm, theo sau là một lựa chọn địa điểm. Sau khi một phiên kết thúc, mã thông báo sẽ không còn hợp lệ nữa; ứng dụng của bạn phải tạo một mã thông báo mới cho mỗi phiên. Bạn nên sử dụng mã thông báo phiên cho tất cả các phiên tự động hoàn thành theo phương thức lập trình (khi bạn nhúng một mảnh hoặc khởi chạy tính năng tự động hoàn thành bằng một ý định, API sẽ tự động xử lý việc này).

    Tính năng Tự động điền sử dụng AutocompleteSessionToken để xác định từng phiên. Ứng dụng của bạn phải truyền mã thông báo phiên mới khi bắt đầu mỗi phiên mới, sau đó truyền cùng một mã thông báo đó cùng với Mã địa điểm trong lệnh gọi tiếp theo đến fetchPlace() để truy xuất Thông tin chi tiết về địa điểm cho địa điểm mà người dùng đã chọn.

    Để đặt tham số mã thông báo phiên, hãy gọi phương thức setSessionToken() khi tạo đối tượng FindAutocompletePredictionsRequest.

    Để biết thêm thông tin, hãy xem phần Mã thông báo phiên.

Ví dụ về tính năng Tự động hoàn thành (Mới)

Sử dụng tính năng hạn chế vị trí và thiên vị vị trí

Tính năng Tự động hoàn thành (Mới) sử dụng tính năng thiên vị IP theo mặc định để kiểm soát khu vực tìm kiếm. Với độ lệch IP, API sử dụng địa chỉ IP của thiết bị để tạo độ lệch cho kết quả. Bạn có thể tuỳ ý sử dụng hạn chế vị trí hoặc tính năng thiên vị vị trí, nhưng không được sử dụng cả hai để chỉ định một khu vực cần tìm kiếm.

Quy định hạn chế về vị trí chỉ định khu vực cần tìm kiếm. Hệ thống sẽ không trả về kết quả nằm ngoài khu vực được chỉ định. Ví dụ sau đây sử dụng quy tắc hạn chế vị trí để giới hạn yêu cầu ở quy tắc hạn chế vị trí hình tròn có bán kính 5.000 mét, tâm là San Francisco:

Places.initializeWithNewPlacesApiEnabled(context, apiKey);
final List<Field> placeFields = getPlaceFields();

LatLng center = new LatLng(37.7749, -122.4194);
CircularBounds circle = CircularBounds.newInstance(center, /* radius = */ 5000);

final FindAutocompletePredictionsRequest autocompletePlacesRequest =
    FindAutocompletePredictionsRequest.builder()
            .setQuery("Amoeba")
            .setLocationRestriction(circle)
            .build());
placesClient.findAutocompletePredictions(autoCompletePlacesRequest)
    .addOnSuccessListener(
        (response) -> {
            List<AutocompletePrediction> predictions = response.getResult().getAutocompletePredictions();
          }
    ).addOnFailureListener(
        exception -> {
            Log.e(TAG, "some exception happened" + exception.getMessage());
        })
    );

Với độ lệch vị trí, vị trí đóng vai trò là độ lệch, tức là các kết quả xung quanh vị trí được chỉ định có thể được trả về, bao gồm cả kết quả bên ngoài khu vực được chỉ định. Ví dụ tiếp theo thay đổi yêu cầu trước đó để sử dụng độ lệch vị trí:

Places.initializeWithNewPlacesApiEnabled(context, apiKey);
final List<Field> placeFields = getPlaceFields();

LatLng center = new LatLng(37.7749, -122.4194);
CircularBounds circle = CircularBounds.newInstance(center, /* radius = */ 5000);

final FindAutocompletePredictionsRequest autocompletePlacesRequest =
    FindAutocompletePredictionsRequest.builder()
            .setQuery("Amoeba")
            .setLocationBias(circle)
            .build());
placesClient.findAutocompletePredictions(autoCompletePlacesRequest)
    .addOnSuccessListener(
        (response) -> {
            List<AutocompletePrediction> predictions = response.getResult().getAutocompletePredictions();
          }
    ).addOnFailureListener(
        exception -> {
            Log.e(TAG, "some exception happened" + exception.getMessage());
        })
    );

Sử dụng các loại chính

Sử dụng tham số loại chính để hạn chế kết quả của một yêu cầu thuộc một loại nhất định như được liệt kê trong Bảng A và Bảng B. Bạn có thể chỉ định một mảng gồm tối đa 5 giá trị. Nếu bạn bỏ qua, tất cả các loại đều được trả về.

Ví dụ sau đây chỉ định một chuỗi truy vấn là "Soccer" (Bóng đá) và sử dụng tham số loại chính để hạn chế kết quả ở những cơ sở thuộc loại "sporting_goods_store":

Places.initializeWithNewPlacesApiEnabled(context, apiKey);
final List<Field> placeFields = getPlaceFields();

final List<Place.Field> primaryTypes = Arrays.asList("sporting_goods_store");

LatLng center = new LatLng(37.7749, -122.4194);
CircularBounds circle = CircularBounds.newInstance(center, /* radius = */ 5000);

final FindAutocompletePredictionsRequest autocompletePlacesRequest =
    FindAutocompletePredictionsRequest.builder()
            .setQuery("Soccer")
            .setIncludedPrimaryTypes(primaryTypes)
            .setLocationBias(circle)
            .build());
placesClient.findAutocompletePredictions(autoCompletePlacesRequest)
    .addOnSuccessListener(
        (response) -> {
            List<AutocompletePrediction> predictions = response.getResult().getAutocompletePredictions();
          }
    ).addOnFailureListener(
        exception -> {
            Log.e(TAG, "some exception happened" + exception.getMessage());
        })
    );

Nếu bạn bỏ qua tham số loại chính, kết quả có thể bao gồm các cơ sở thuộc loại mà bạn không muốn, chẳng hạn như "athletic_field".

Sử dụng nguồn gốc

Khi bạn thêm tham số origin (điểm xuất phát) vào yêu cầu, được chỉ định dưới dạng toạ độ vĩ độ và kinh độ, API sẽ bao gồm khoảng cách theo đường thẳng từ điểm xuất phát đến đích đến trong phản hồi (truy cập bằng getDistanceMeters()). Ví dụ này đặt điểm xuất phát là trung tâm của San Francisco:

Places.initializeWithNewPlacesApiEnabled(context, apiKey);
final List<Field> placeFields = getPlaceFields();

LatLng center = new LatLng(37.7749, -122.4194);
CircularBounds circle = CircularBounds.newInstance(center, /* radius = */ 5000);

final FindAutocompletePredictionsRequest autocompletePlacesRequest =
    FindAutocompletePredictionsRequest.builder()
            .setQuery("Amoeba")
            .setOrigin(center)
            .setLocationRestriction(circle)
            .build());
placesClient.findAutocompletePredictions(autoCompletePlacesRequest)
    .addOnSuccessListener(
        (response) -> {
            List<AutocompletePrediction> predictions = response.getResult().getAutocompletePredictions();
          }
    ).addOnFailureListener(
        exception -> {
            Log.e(TAG, "some exception happened" + exception.getMessage());
        })
    );

Phân bổ

Bạn có thể sử dụng tính năng Tự động hoàn thành (Mới) ngay cả khi không có bản đồ. Nếu bạn hiển thị bản đồ, thì đó phải là bản đồ của Google. Khi hiển thị nội dung gợi ý từ dịch vụ Tự động hoàn thành (Mới) mà không có bản đồ, bạn phải thêm biểu trưng Google hiển thị cùng dòng với trường/kết quả tìm kiếm. Để biết thêm thông tin, hãy xem phần Hiển thị biểu trưng Google và thông tin ghi công.