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 gợi ý địa điểm theo yêu cầu bao gồm 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 hoàn thành có thể so khớp các từ đầy đủ và chuỗi con của thông tin đầu vào, phân giải tên địa điểm, địa chỉ và mã cộng. Ứng dụng của bạn có thể gửi truy vấn dưới dạng người dùng nhập để cung cấp địa điểm và dự đoán truy vấn một cách nhanh chóng.

Ví dụ: bạn gọi tính năng Tự động hoàn thành bằng cách nhập một chuỗi có chứa một phần thông tin người dùng nhập là "Sicilian piz", với khu vực tìm kiếm chỉ bao gồm San Francisco, CA. Sau đó, phản hồi sẽ chứa một danh sách các đề xuất 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 là "Sicilian Pizza Kitchen".

Các thông tin dự đoán về địa điểm được trả về được thiết kế để hiển thị với người dùng nhằm hỗ trợ họ lựa chọn địa điểm mong muốn. Bạn có thể đưa ra yêu cầu Chi tiết địa điểm (Mới) để biết thêm thông tin về mọi thông tin dự đoán về địa điểm đượ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 và/hoặc địa chỉ địa điểm đượ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 này trả về một FindAutocompletePredictionsResponse trong một 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 này có thể trống, nếu không có địa điểm đã biết tương ứng với truy vấn và tiêu chí bộ lọc.

Đối với mỗi địa điểm 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ề văn bản đầy đủ 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, France". Ngoài ra, phương thức này cho phép bạn làm nổi bật những phần trong nội dung mô tả khớp với nội dung tìm kiếm theo một kiểu mà bạn chọn bằng cách sử dụng CharacterStyle. Tham số CharacterStyle là không bắt buộc. Hãy thiết lập giá trị này thành rỗng nếu bạn không cần đánh dấu.
  • 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 con của nội dung mô tả địa điểm. Ví dụ: thuộc tính này hữu ích khi làm dòng thứ hai khi hiển thị các cụm từ gợi ý của tính năng tự động hoàn thành. Ví dụ: "Alocations 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 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 bài viết 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 mà bạn muốn tìm kiếm. Chỉ định từ đầy đủ và chuỗi con, tên địa điểm, địa chỉ và mã cộng. Dịch vụ Tự động hoàn thành (Mới) trả về kết quả khớp đề xuất dựa trên chuỗi này và kết quả của các đơn đặt hàng dựa trên mức độ liên quan mà người dùng 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ừ các loại Bảng A hoặc Bảng B dùng để lọc các vị trí được trả về trong phản hồi. Đị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 câu trả lời.

    Một địa điểm chỉ có thể có một loại chính duy nhất trong 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:

    • Có hơn 5 loại được chỉ định.
    • Mọi loại không nhận dạng được đều đượ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ỉ cung cấp kết quả ở danh sách các quốc gia đã chỉ định, được chỉ định dưới dạng danh sách gồm tối đa 15 ccTLD ("miền cấp cao nhất") với giá trị hai ký tự. Nếu bỏ qua, không có hạn chế nào được áp dụng cho câu trả lờ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, thì kết quả sẽ nằm trong khu vực giao nhau của hai chế độ cài đặt này.

    Để đặ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

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

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

  • Thiên vị về vị trí hoặc hạn chế về vị trí

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

    • Xu hướng vị trí

      Chỉ định một vùng để tìm kiếm. Vị trí này là một thiên kiến, không phải là một hạn chế, vì vậy, kết quả nằm ngoài khu vực đã chỉ định vẫn có thể được trả về.

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

    • Hạn chế vị trí

      Chỉ định một vùng để tìm kiếm. Kết quả nằm ngoài khu vực đã chỉ định sẽ không được trả về.

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

    Hãy chỉ định độ lệch vị trí hoặc khu vực hạn chế vị trí dưới dạng Khung nhìn hình chữ nhật hoặc hình tròn.

    • Một đường tròn được xác định bởi 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,0 đến 50000,0. Giá trị mặc định là 0,0. Đối với việc 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. Nếu không, yêu cầu này sẽ không trả về kết quả nào.

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

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

      Cả low và high đều phải được điền và không được để trống hộp được đại diện. Khung nhìn trống 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, ứng dụng sẽ không trả về khoảng cách theo đường thẳng. Phải được chỉ định là toạ độ theo 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ị 2 ký tự là ccTLD ("miền cấp cao nhất"). Hầu hết mã ccTLD (miền cấp cao nhất theo mã quốc gia) đều giống với mã ISO 3166-1, trừ 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 của mã này là "gb" (về mặt kỹ thuật là "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. Tuỳ theo luật hiện hành, thông số này có thể ảnh hưởng đến kết quả.

    Để đặ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 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 trong cụm 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 hoạt động này bắt đầu khi người dùng bắt đầu nhập cụm từ tìm kiếm và kết thúc khi họ chọn một địa điểm. Mỗi phiên có thể có nhiều truy vấn, 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 không còn hợp lệ; ứng dụng của bạn phải tạo 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 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 hoàn thành sử dụng AutocompleteSessionToken để xác định từng phiên. Ứng dụng phải truyền một mã thông báo phiên mới khi bắt đầu mỗi phiên mới, sau đó truyền chính mã đó cùng với một 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 giới hạn vị trí và thiên vị vị trí

Tính năng Tự động hoàn thành (Mới) sử dụng xu hướng IP theo mặc định để kiểm soát khu vực tìm kiếm. Với xu hướng IP, API sử dụng địa chỉ IP của thiết bị để xu hướng kết quả. Bạn có thể tuỳ ý sử dụng tính năng hạn chế vị trí hoặc 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.

Giới hạn vị trí chỉ định khu vực cần tìm kiếm. Kết quả nằm ngoài vùng đã chỉ định sẽ không được trả về. Ví dụ sau đây sử dụng quy tắc hạn chế về vị trí để giới hạn yêu cầu cho một quy định hạn chế về vị trí hình tròn có bán kính 5.000 mét ở giữ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")
            .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ó thể trả về kết quả xung quanh vị trí đã chỉ định, bao gồm cả kết quả bên ngoài khu vực đã chỉ định. Ví dụ tiếp theo thay đổi yêu cầu trước đó để sử dụng tính năng sai 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 loại chính

Sử dụng tham số loại chính để hạn chế kết quả từ một yêu cầu thuộc một loại nhất định như 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ỏ qua, hàm sẽ trả về tất cả các loại.

Ví dụ sau đây chỉ định một chuỗi truy vấn "Bóng đá" và sử dụng tham số kiểu chính để giới hạn kết quả cho các 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 có thể không muốn, chẳng hạn như "athletic_field".

Sử dụng nguồn gốc

Khi bạn đưa tham số origin (được chỉ định dưới dạng vĩ độ và kinh độ) vào yêu cầu, API sẽ bao gồm khoảng cách theo đường thẳng từ điểm gốc đến đích đến trong phản hồi (truy cập bằng getDistanceMeters()). Ví dụ sau đặt điểm khởi hành là trung tâm 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ị một bản đồ, đó phải là bản đồ của Google. Khi hiển thị cụm từ gợi ý của 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 của Google xuất hiện 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 bài viết Hiển thị biểu trưng và các mô hình phân bổ của Google.