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ề các cụm từ gợi ý địa điểm trong phản hồi yêu cầu bao gồm chuỗi tìm kiếm văn bản và 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 dựa trên 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 khi người dùng nhập, để cung cấp các dự đoán truy vấn và địa điểm nhanh chóng.

Ví dụ: bạn gọi tính năng Tự động hoàn thành bằng cách dùng dữ liệu đầu vào là chuỗi chứa một phần thông tin do người dùng nhập, "Sicilian piz", với khu vực tìm kiếm chỉ có ở San Francisco, CA. Sau đó, phản hồi chứa danh sách địa điểm các cụm từ gợi ý 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 gợi ý về địa điểm được trả về được thiết kế để hiển thị cho người dùng nhằm hỗ trợ họ trong việc chọn địa điểm mong muốn. Bạn có thể tạo Thông tin chi tiết về địa điểm (Mới) yêu cầu tải thêm thông tin về bất kỳ cụm từ gợi ý nào về địa điểm được trả về.

Lưu ý: Tính năng Tự động hoàn thành (Mới) có trong SDK Địa điểm dành cho Android phiên bản 3.5.0 trở lên. Để biết thêm thông tin, hãy xem phần Chọn SDK phiên bản.

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

Ứng dụng của bạn có thể tải danh sách tên địa điểm được dự đoán và/hoặc địa chỉ từ API tự động hoàn thành bằng cách gọi PlacesClient.findAutocompletePredictions(), truyền một 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());
        })
    );

Lưu ý: Cuộc gọi được thực hiện bằng tính năng Tự động hoàn thành theo địa điểm tiện ích luôn gọi Địa điểm Tự động hoàn thành, không phải Địa điểm Tự động hoàn thành (Mới); các lệnh gọi tiện ích không bị ảnh hưởng bởi phương thức khởi chạy.

Lưu ý: Để biết thêm thông tin về cách khởi chạy PlacesClient, hãy xem Khởi chạy ứng dụng Places API.

Bạn có thể sử dụng CancellationToken để cố huỷ một yêu cầu tới bất kỳ lớp yêu cầu nào (ví dụ: FetchPlaceRequest). Quá trình huỷ được thực hiện nỗ lực hết sức có thể. Sau khi đưa ra yêu cầu huỷ, sẽ không có phản hồi nào được trả về. Việc cấp mã thông báo huỷ KHÔNG đảm bảo rằng một yêu cầu cụ thể sẽ bị huỷ và bạn vẫn có thể bị tính phí cho yêu cầu đó ngay cả khi không phản hồi được trả về.

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

API trả về một FindAutocompletePredictionsResponse theo phong cách Task. Chiến lược phát hành đĩa đơn FindAutocompletePredictionsResponse chứa một danh sách tối đa năm AutocompletePrediction các đối tượng đại diện cho địa điểm 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í 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 địa điểm chi tiết:

• getFullText(CharacterStyle) sẽ 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à phụ. Ví dụ: "Tháp Eiffel, Đại lộ Anatole France, Paris, Pháp". Ngoài ra, phương pháp này cho phép bạn đánh dấu các phần của mô tả khớp với nội dung tìm kiếm theo kiểu mà bạn chọn, sử dụng CharacterStyle. Tham số CharacterStyle là không bắt buộc. Đặt thành rỗng nếu bạn không cần bất kỳ đánh dấu nào.
• 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) sẽ trả về văn bản thành phần con của một nội dung mô tả địa điểm. Điều này rất hữu ích, đối với chẳng hạn như dòng thứ hai khi hiện 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() sẽ trả về mã địa điểm của địa điểm được dự đoán. Mã địa điểm là dạng văn bản giá trị nhận dạng xác định duy nhất một địa điểm mà bạn có thể sử dụng để truy xuất thời gian Place đối tượng một lần nữa sau đó. Để biết thêm thông tin về mã địa điểm trong Tự động hoàn thành, xem Chi tiết địa điểm (Mới). Dành cho tất cả mọi người thông tin về mã địa điểm, hãy xem Mã địa điểm tổng quan.
• getTypes() trả về danh sách các loại địa điểm được 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ả phù hợp đề xuất dựa trên chuỗi này và kết quả đơn hàng dựa vào mức độ liên quan mà họ cảm nhận được.

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

Thông số tùy chọn

• Loại chính

  Danh sách tối đa 5 giá trị loại trong các loại Bảng A hoặc Bảng B dùng để lọc địa điểm đượ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 nó. 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 setTypesFilter() khi tạo đối tượng FindAutocompletePredictionsRequest.

• Quốc gia

  Chỉ bao gồm kết quả từ danh sách các quốc gia được chỉ định, được chỉ định dưới dạng danh sách tối đa 15 quốc gia ccTLD ("miền cấp cao nhất") 2 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 khu vực ở Đức và Pháp:

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

  Để đặt thông số quốc gia, hãy gọi 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 thông số chênh lệch đầu vào, hãy gọi setInputOffset() khi tạo đối tượng FindAutocompletePredictionsRequest.

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

  Bạn có thể chỉ định thiên lệch vị trí hoặc hạn chế về vị trí, nhưng không phải cả hai để xác định khu vực tìm kiếm. Hãy coi việc hạn chế vị trí là việc xác định khu vực nơi kết quả phải xuất hiện và độ lệch về vị trí chỉ định khu vực gần đó để tìm kết quả. Điểm khác biệt chính là Nếu có sai lệch về vị trí, thì kết quả nằm 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à thiên kiến, không phải là hạn chế, do đó, kết quả ra ngoài vùng được chỉ định vẫn có thể được trả về.

    Để đặt thông số thiên vị vị trí, hãy gọi 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 được chỉ định không bị trả lại.

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

  Chỉ định khuynh hướng vị trí hoặc vùng hạn chế về vị trí dưới dạng Khung nhìn hình chữ nhật hoặc dưới dạng 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 0.0 và 50000.0. Giá trị mặc định là 0,0. Đối với việc hạn chế 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ẽ được trả về không có kết quả.

  • Hình chữ nhật là một khung nhìn vĩ độ – kinh độ, được biểu thị dưới dạng hai theo đường chéo đối diện low và high điểm. Khung nhìn được xem là khu vực khép kín, nghĩa là khu vực này bao gồm ranh giới của nó. 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 độ, bao gồm cả hai giá trị sau:

    Lưu ý: Các loại xu hướng được hỗ trợ sẽ khác nhau tuỳ thuộc vào phiên bản SDK mà bạn đang dùng. CircularBounds chỉ có trong tính năng Tự động hoàn thành (Mới).
    • Nếu low = high, khung nhìn chỉ bao gồm một điểm duy nhất đó.
    • Nếu low.longitude > high.longitude, phạm vi kinh độ 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 bao gồm tất cả kinh độ.
    • Nếu low.longitude = 180 độ và high.longitude = -180 độ, phạm vi kinh độ trống.

    Cả low và high đều phải được điền và nhập vào hộp được đại diện không được để trống. 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 (được truy cập bằng getDistanceMeters()). Nếu giá trị này là bị bỏ qua, khoảng cách đường thẳng sẽ không được trả về. Phải được chỉ định là vĩ độ và kinh độ:

  Để đặt tham số nguồn gốc, hãy gọi setOrigin() khi tạo đối tượng FindAutocompletePredictionsRequest.

• Mã vùng

  Mã vùng dùng để định dạng câu trả lời, bao gồm cả định dạng địa chỉ, được chỉ định làm ccTLD ("miền cấp cao nhất") 2 ký 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, 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 của trang web là "gb" (về mặt kỹ thuật cho pháp nhân "Vương quốc Anh và Bắc Ireland").

  Lưu ý: Mã vùng là đại diện cho khu vực phát sinh yêu cầu không nhất thiết là vùng mục tiêu cho truy vấn.

  Nếu bạn chỉ định mã vùng không hợp lệ, API sẽ trả về 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 thông số mã khu vực, hãy gọi 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 của tự động hoàn thành tìm kiếm của người dùng thành một phiên riêng biệt cho cho mục đích thanh toán. Phiên hoạt động 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 truy vấn, theo sau là một lựa chọn địa điểm. Khi một phiên hoạt động có 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ột mã thông báo mới cho từng phiên hoạt động. Bạn nên sử dụng mã thông báo phiên cho tất cả quảng cáo có lập trình phiên tự động hoàn thà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 ý định thì 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 của bạn sẽ truyền mã thông báo phiên mới khi bắt đầu mỗi phiên mới, sau đó chuyển cùng mã thông báo đó cùng với ID địa điểm vào lệnh gọi tiếp theo tới fetchPlace() để truy xuất Thông tin chi tiết về địa điểm cho địa điểm đã được người dùng chọn.

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

  Để biết thêm thông tin, hãy xem 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ự động hoàn thành (Mới) sử dụng xu hướng IP theo mặc định là 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 làm sai lệch kết quả. Bạn có thể tuỳ ý sử dụng thuộc tính vị trí hạn chế hoặc thiên vị vị trí, nhưng khô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 phạm vi được 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 ở một hạn chế theo vị trí vòng tròn có bán kính 5.000 mét nằm ở 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")
            .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 thiên vị về vị trí, vị trí được coi là thiên kiến, có nghĩa là các kết quả xung quanh vị trí được chỉ định có thể được trả về, bao gồm cả các kết quả nằm ngoài phạm vi . 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ố primary types (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ư đượ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ỏ qua, hàm sẽ trả về tất cả các loại.

Ví dụ sau đây chỉ định chuỗi truy vấn "Bóng đá" và sử dụng type (loại) để giới hạn kết quả đối với 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 thông số loại chính, kết quả có thể bao gồm các cơ sở thuộc loại mà có thể bạn không muốn, chẳng hạn như "athletic_field".

Sử dụng nguồn gốc

Khi bạn đưa thông số origin vào yêu cầu, được chỉ định là vĩ độ và kinh độ, 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 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 bạn hiển thị cụm từ gợi ý từ dịch vụ Tự động hoàn thành (Mới) không có bản đồ, bạn phải bao gồm biểu trưng của Google được 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 Hiển thị biểu trưng Google và thuộc tính.