Tự động hoàn thành địa điểm

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

Giới thiệu

Tự động hoàn thành là một tính năng của thư viện Địa điểm trong API JavaScript của Maps. Bạn có thể sử dụng tính năng tự động hoàn thành để giúp các ứng dụng của bạn có hành vi tìm kiếm trước khi nhập trong trường tìm kiếm trên Google Maps. Dịch vụ tự động hoàn thành có thể so khớp các từ và chuỗi con đầy đủ, phân giải tên địa điểm, địa chỉ và mã cộng. Do đó, các ứng dụng có thể gửi truy vấn khi người dùng nhập để cung cấp thông tin dự đoán địa điểm một cách nhanh chóng.

Bắt đầu

Trước khi sử dụng thư viện Địa điểm trong API Maps JavaScript, trước tiên, hãy đảm bảo rằng bạn đã bật Places API trong Google Cloud Console, đúng dự án bạn thiết lập cho Maps JavaScript API.

Cách xem danh sách API đã bật:

  1. Chuyển đến Google Cloud Console.
  2. Nhấp vào nút Select a project (Chọn dự án), sau đó chọn chính dự án mà bạn đã thiết lập cho Maps JavaScript API và nhấp vào Open (Mở).
  3. Trong danh sách API trên Trang tổng quan, hãy tìm API Địa điểm.
  4. Nếu thấy API trong danh sách thì bạn đã hoàn tất. Nếu API không có trong danh sách, hãy bật API đó:
    1. Ở đầu trang, hãy chọn ENABLE API (Bật API) để hiển thị thẻ Library (Thư viện). Ngoài ra, trên trình đơn bên trái, hãy chọn Thư viện.
    2. Tìm kiếm API Địa điểm, sau đó chọn API đó trong danh sách kết quả.
    3. Chọn BẬT. Khi quá trình này kết thúc, API Địa điểm sẽ xuất hiện trong danh sách API trên Trang tổng quan.

Đang tải thư viện

Dịch vụ Địa điểm là một thư viện độc lập, tách biệt với mã API JavaScript chính của Maps. Để sử dụng chức năng có trong thư viện này, trước tiên, bạn phải tải thư viện bằng cách sử dụng tham số libraries trong URL khởi động của API Maps:

<script async
    src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&loading=async&libraries=places&callback=initMap">
</script>

Hãy xem phần Tổng quan về thư viện để biết thêm thông tin.

Thông tin tóm tắt về các lớp

API này cung cấp 2 loại tiện ích tự động hoàn thành mà bạn có thể thêm lần lượt thông qua các lớp AutocompleteSearchBox. Ngoài ra, bạn có thể sử dụng lớp AutocompleteService để truy xuất kết quả tự động hoàn thành theo phương thức lập trình (xem Tài liệu tham khảo API JavaScript của Maps: lớp Tự động hoàn thành).

Dưới đây là thông tin tóm tắt về các lớp học hiện có:

  • Autocomplete thêm một trường nhập văn bản vào trang web của bạn và theo dõi trường đó để xem có các mục nhập ký tự hay không. Khi người dùng nhập văn bản, tính năng tự động hoàn thành sẽ trả về các cụm từ gợi ý địa điểm dưới dạng danh sách chọn thả xuống. Khi người dùng chọn một địa điểm trong danh sách, thông tin về địa điểm đó sẽ được trả về đối tượng tự động hoàn thành và ứng dụng của bạn có thể truy xuất thông tin này. Xem thông tin chi tiết bên dưới.
    Một trường văn bản tự động hoàn thành và danh sách lựa chọn của các gợi ý về địa điểm được cung cấp khi người dùng nhập cụm từ tìm kiếm.
    Hình 1: Trường văn bản Tự động hoàn thành và danh sách chọn
    Một biểu mẫu địa chỉ hoàn chỉnh.
    Hình 2: Biểu mẫu địa chỉ đã hoàn tất
  • SearchBox thêm trường nhập văn bản vào trang web của bạn, theo cách tương tự như Autocomplete. Sau đây là những điểm khác biệt:
    • Điểm khác biệt chính nằm ở kết quả xuất hiện trong danh sách chọn. SearchBox cung cấp một danh sách mở rộng gồm các cụm từ gợi ý, có thể bao gồm các địa điểm (theo xác định của Places API) cùng với các cụm từ tìm kiếm đề xuất. Ví dụ: nếu người dùng nhập 'pizza ở mới', danh sách lựa chọn có thể bao gồm cụm từ 'pizza ở New York, NY' cũng như tên của các cửa hàng pizza khác nhau.
    • SearchBox cung cấp ít tuỳ chọn hơn Autocomplete để hạn chế tìm kiếm. Trong trường hợp trước, bạn có thể thiên về tìm kiếm theo một LatLngBounds nhất định. Sau đó, bạn có thể giới hạn phạm vi tìm kiếm ở một quốc gia và các loại địa điểm cụ thể, cũng như đặt các giới hạn. Để biết thêm thông tin, hãy xem phần bên dưới.
    Một biểu mẫu địa chỉ hoàn chỉnh.
    Hình 3: Một SearchBox trình bày các cụm từ tìm kiếm và các cụm từ gợi ý về địa điểm.
    Xem thông tin chi tiết bên dưới.
  • Bạn có thể tạo một đối tượng AutocompleteService để truy xuất các cụm từ gợi ý theo phương thức lập trình. Hãy gọi getPlacePredictions() để truy xuất các địa điểm phù hợp hoặc gọi getQueryPredictions() để truy xuất các địa điểm phù hợp cùng với cụm từ tìm kiếm đề xuất. Lưu ý: AutocompleteService không thêm chế độ điều khiển giao diện người dùng nào. Thay vào đó, các phương thức trên sẽ trả về một mảng các đối tượng dự đoán. Mỗi đối tượng gợi ý chứa văn bản của cụm từ gợi ý, cũng như thông tin tham chiếu và thông tin chi tiết về cách kết quả khớp với hoạt động đầu vào của người dùng. Hãy xem thông tin chi tiết bên dưới.

Thêm tiện ích Tự động hoàn thành

Tiện ích Autocomplete tạo một trường nhập văn bản trên trang web của bạn, cung cấp thông tin dự đoán về các địa điểm trong danh sách chọn trên giao diện người dùng và trả về thông tin chi tiết về địa điểm để phản hồi một yêu cầu getPlace(). Mỗi mục trong danh sách chọn tương ứng với một địa điểm (do API Địa điểm xác định).

Hàm khởi tạo Autocomplete nhận hai đối số:

  • Một phần tử HTML input thuộc loại text. Đây là trường nhập dữ liệu mà dịch vụ tự động hoàn thành sẽ theo dõi và đính kèm kết quả.
  • Một đối số AutocompleteOptions không bắt buộc, đối số này có thể chứa các thuộc tính sau:
    • Một mảng dữ liệu fields sẽ được đưa vào phản hồi Place Details cho PlaceResult mà người dùng chọn. Nếu bạn không đặt thuộc tính hoặc nếu ['ALL'] được truyền vào, thì mọi trường có sẵn sẽ được trả về và lập hoá đơn (bạn không nên sử dụng phương pháp này cho quá trình triển khai chính thức). Để xem danh sách trường, hãy xem PlaceResult.
    • Một mảng types chỉ định một kiểu tường minh hoặc một tập hợp kiểu, như liệt kê trong các kiểu được hỗ trợ. Nếu bạn không chỉ định loại nào, thì tất cả các loại sẽ được trả về.
    • bounds là một đối tượng google.maps.LatLngBounds chỉ định khu vực cần tìm kiếm địa điểm. Kết quả bị thiên lệch đối với những vị trí nằm trong các giới hạn này.
    • strictBounds là một boolean chỉ định liệu API có phải chỉ trả về các địa điểm hoàn toàn trong khu vực được bounds nhất định xác định hay không. API không trả về kết quả bên ngoài khu vực này ngay cả khi kết quả khớp với hoạt động đầu vào của người dùng.
    • Bạn có thể sử dụng componentRestrictions để giới hạn kết quả cho các nhóm cụ thể. Hiện tại, bạn có thể sử dụng componentRestrictions để lọc theo tối đa 5 quốc gia. Quốc gia phải được truyền dưới dạng mã quốc gia tương thích với ISO 3166-1 Alpha-2 gồm 2 ký tự. Phải chuyển nhiều quốc gia dưới dạng danh sách mã quốc gia.

      Lưu ý: Nếu bạn nhận được kết quả không mong muốn với mã quốc gia, hãy xác minh rằng bạn đang sử dụng mã có chứa các quốc gia, vùng lãnh thổ phụ thuộc và các khu vực địa lý đặc biệt mà bạn dự định sử dụng. Bạn có thể xem thông tin về mã trên Wikipedia: Danh sách mã quốc gia theo tiêu chuẩn ISO 3166 hoặc Nền tảng duyệt web trực tuyến ISO.

    • Bạn có thể sử dụng placeIdOnly để hướng dẫn tiện ích Autocomplete chỉ truy xuất Mã địa điểm. Khi gọi getPlace() trên đối tượng Autocomplete, PlaceResult có sẵn sẽ chỉ đặt các thuộc tính place id, typesname. Bạn có thể sử dụng mã địa điểm được trả về bằng các lệnh gọi đến dịch vụ Địa điểm, Mã hoá địa lý, Đường đi hoặc Ma trận khoảng cách.

Đảm bảo các cụm từ gợi ý của tính năng Tự động hoàn thành

Theo mặc định, tính năng Tự động hoàn thành địa điểm hiển thị tất cả các loại địa điểm, thiên về các gợi ý gần vị trí của người dùng và tìm nạp tất cả các trường dữ liệu có sẵn cho địa điểm mà người dùng đã chọn. Đặt các tuỳ chọn Tự động hoàn thành địa điểm để đưa ra các dự đoán phù hợp hơn dựa trên trường hợp sử dụng của bạn.

Đặt tuỳ chọn khi xây dựng

Hàm khởi tạo Autocomplete chấp nhận tham số AutocompleteOptions để đặt các quy tắc ràng buộc khi tạo tiện ích. Ví dụ sau đây đặt các tuỳ chọn bounds, componentRestrictionstypes để yêu cầu các địa điểm loại establishment, ưu tiên những địa điểm trong khu vực địa lý đã chỉ định và chỉ đưa ra cụm từ gợi ý ở những địa điểm ở Hoa Kỳ. Việc đặt tuỳ chọn fields sẽ chỉ định thông tin cần trả về về địa điểm đã chọn của người dùng.

Gọi setOptions() để thay đổi giá trị của một tuỳ chọn cho tiện ích hiện có.

TypeScript

const center = { lat: 50.064192, lng: -130.605469 };
// Create a bounding box with sides ~10km away from the center point
const defaultBounds = {
  north: center.lat + 0.1,
  south: center.lat - 0.1,
  east: center.lng + 0.1,
  west: center.lng - 0.1,
};
const input = document.getElementById("pac-input") as HTMLInputElement;
const options = {
  bounds: defaultBounds,
  componentRestrictions: { country: "us" },
  fields: ["address_components", "geometry", "icon", "name"],
  strictBounds: false,
};

const autocomplete = new google.maps.places.Autocomplete(input, options);

JavaScript

const center = { lat: 50.064192, lng: -130.605469 };
// Create a bounding box with sides ~10km away from the center point
const defaultBounds = {
  north: center.lat + 0.1,
  south: center.lat - 0.1,
  east: center.lng + 0.1,
  west: center.lng - 0.1,
};
const input = document.getElementById("pac-input");
const options = {
  bounds: defaultBounds,
  componentRestrictions: { country: "us" },
  fields: ["address_components", "geometry", "icon", "name"],
  strictBounds: false,
};
const autocomplete = new google.maps.places.Autocomplete(input, options);

Chỉ định các trường dữ liệu

Chỉ định các trường dữ liệu để tránh bị tính phí cho SKU Dữ liệu địa điểm mà bạn không cần đến. Bao gồm thuộc tính fields trong AutocompleteOptions đã được truyền đến hàm khởi tạo tiện ích, như minh hoạ trong ví dụ trước, hoặc gọi setFields() trên đối tượng Autocomplete hiện có.

autocomplete.setFields(["place_id", "geometry", "name"]);

Xác định độ chệch và ranh giới khu vực tìm kiếm cho tính năng Tự động hoàn thành

Bạn có thể khuynh hướng kết quả tự động hoàn thành để ưu tiên một vị trí hoặc khu vực gần đúng theo những cách sau:

  • Đặt giới hạn khi tạo đối tượng Autocomplete.
  • Thay đổi các giới hạn trên một Autocomplete hiện có.
  • Đặt các giới hạn cho khung nhìn của bản đồ.
  • Giới hạn tìm kiếm trong giới hạn.
  • Giới hạn tìm kiếm trong một quốc gia cụ thể.

Ví dụ trước minh hoạ việc đặt giới hạn khi tạo. Các ví dụ sau đây minh hoạ các kỹ thuật xu hướng khác.

Thay đổi ranh giới của tính năng Tự động hoàn thành hiện có

Gọi setBounds() để thay đổi vùng tìm kiếm trên một Autocomplete hiện có thành các ranh giới hình chữ nhật.

TypeScript

const southwest = { lat: 5.6108, lng: 136.589326 };
const northeast = { lat: 61.179287, lng: 2.64325 };
const newBounds = new google.maps.LatLngBounds(southwest, northeast);

autocomplete.setBounds(newBounds);

JavaScript

const southwest = { lat: 5.6108, lng: 136.589326 };
const northeast = { lat: 61.179287, lng: 2.64325 };
const newBounds = new google.maps.LatLngBounds(southwest, northeast);

autocomplete.setBounds(newBounds);
Đặt các giới hạn cho khung nhìn của bản đồ

Sử dụng bindTo() để chuyển hướng kết quả tới khung nhìn của bản đồ, ngay cả khi khung nhìn đó thay đổi.

TypeScript

autocomplete.bindTo("bounds", map);

JavaScript

autocomplete.bindTo("bounds", map);

Hãy sử dụng unbind() để huỷ liên kết các cụm từ dự đoán Tự động hoàn thành từ khung nhìn của bản đồ.

TypeScript

autocomplete.unbind("bounds");
autocomplete.setBounds({ east: 180, west: -180, north: 90, south: -90 });

JavaScript

autocomplete.unbind("bounds");
autocomplete.setBounds({ east: 180, west: -180, north: 90, south: -90 });

Xem ví dụ

Giới hạn tìm kiếm trong các giới hạn hiện tại

Đặt tuỳ chọn strictBounds để giới hạn kết quả ở các ranh giới hiện tại, cho dù dựa trên khung nhìn bản đồ hay ranh giới hình chữ nhật.

autocomplete.setOptions({ strictBounds: true });
Hạn chế cụm từ gợi ý ở một quốc gia cụ thể

Sử dụng tuỳ chọn componentRestrictions hoặc gọi setComponentRestrictions() để giới hạn nội dung tìm kiếm tự động hoàn thành ở một nhóm cụ thể, bao gồm tối đa 5 quốc gia.

TypeScript

autocomplete.setComponentRestrictions({
  country: ["us", "pr", "vi", "gu", "mp"],
});

JavaScript

autocomplete.setComponentRestrictions({
  country: ["us", "pr", "vi", "gu", "mp"],
});

Xem ví dụ

Ràng buộc các loại địa điểm

Sử dụng tuỳ chọn types hoặc gọi setTypes() để ràng buộc truy vấn dự đoán đối với một số loại địa điểm nhất định. Quy tắc ràng buộc này chỉ định một loại hoặc một tập hợp kiểu, như liệt kê trong phần Loại địa điểm. Nếu bạn không chỉ định quy tắc ràng buộc nào, thì tất cả các loại sẽ được trả về.

Đối với giá trị của tuỳ chọn types hoặc giá trị được chuyển đến setTypes(), bạn có thể chỉ định:

  • Một mảng chứa tối đa 5 giá trị từ Bảng 1 hoặc Bảng 2 từ Loại địa điểm. Ví dụ:

    types: ['hospital', 'pharmacy', 'bakery', 'country']

    hoặc:

    autocomplete.setTypes(['hospital', 'pharmacy', 'bakery', 'country']);
  • Bất kỳ một bộ lọc nào trong Bảng 3 từ Loại địa điểm. Bạn chỉ có thể chỉ định một giá trị duy nhất trong Bảng 3.

Yêu cầu sẽ bị từ chối nếu:

  • Bạn chỉ định nhiều hơn 5 loại.
  • Bạn chỉ định mọi loại không nhận dạng được.
  • Bạn có thể kết hợp bất kỳ loại nào ở Bảng 1 hoặc Bảng 2 với bất kỳ bộ lọc nào trong Bảng 3.

Bản minh hoạ Tự động hoàn thành theo địa điểm thể hiện sự khác biệt trong dự đoán giữa các loại địa điểm khác nhau.

Truy cập bản minh hoạ

Đang tải thông tin về địa điểm

Khi người dùng chọn một địa điểm trong các cụm từ gợi ý đính kèm với trường văn bản tự động hoàn thành, dịch vụ sẽ kích hoạt sự kiện place_changed. Cách xem thông tin chi tiết về địa điểm:

  1. Tạo một trình xử lý sự kiện cho sự kiện place_changed và gọi addListener() trên đối tượng Autocomplete để thêm trình xử lý.
  2. Gọi Autocomplete.getPlace() trên đối tượng Autocomplete để truy xuất đối tượng PlaceResult. Sau đó, bạn có thể sử dụng đối tượng này để tìm hiểu thêm thông tin về địa điểm đã chọn.

Theo mặc định, khi người dùng chọn một địa điểm, tính năng tự động hoàn thành sẽ trả về tất cả các trường dữ liệu hiện có cho địa điểm đã chọn và bạn sẽ được lập hoá đơn tương ứng. Sử dụng Autocomplete.setFields() để chỉ định trường dữ liệu địa điểm cần trả về. Đọc thêm về đối tượng PlaceResult, bao gồm cả danh sách trường dữ liệu địa điểm mà bạn có thể yêu cầu. Để tránh phải trả tiền cho dữ liệu mà bạn không cần, hãy nhớ sử dụng Autocomplete.setFields() để chỉ chỉ định dữ liệu địa điểm mà bạn sẽ sử dụng.

Thuộc tính name chứa description trong các cụm từ gợi ý Tự động hoàn thành theo địa điểm. Bạn có thể đọc thêm về description trong tài liệu về Tính năng tự động hoàn thành theo địa điểm.

Đối với biểu mẫu địa chỉ, bạn nên lấy địa chỉ ở định dạng có cấu trúc. Để trả về địa chỉ có cấu trúc cho địa điểm đã chọn, hãy gọi Autocomplete.setFields() và chỉ định trường address_components.

Ví dụ sau đây sử dụng tính năng tự động hoàn thành để điền các trường vào biểu mẫu địa chỉ.

TypeScript

function fillInAddress() {
  // Get the place details from the autocomplete object.
  const place = autocomplete.getPlace();
  let address1 = "";
  let postcode = "";

  // Get each component of the address from the place details,
  // and then fill-in the corresponding field on the form.
  // place.address_components are google.maps.GeocoderAddressComponent objects
  // which are documented at http://goo.gle/3l5i5Mr
  for (const component of place.address_components as google.maps.GeocoderAddressComponent[]) {
    // @ts-ignore remove once typings fixed
    const componentType = component.types[0];

    switch (componentType) {
      case "street_number": {
        address1 = `${component.long_name} ${address1}`;
        break;
      }

      case "route": {
        address1 += component.short_name;
        break;
      }

      case "postal_code": {
        postcode = `${component.long_name}${postcode}`;
        break;
      }

      case "postal_code_suffix": {
        postcode = `${postcode}-${component.long_name}`;
        break;
      }

      case "locality":
        (document.querySelector("#locality") as HTMLInputElement).value =
          component.long_name;
        break;

      case "administrative_area_level_1": {
        (document.querySelector("#state") as HTMLInputElement).value =
          component.short_name;
        break;
      }

      case "country":
        (document.querySelector("#country") as HTMLInputElement).value =
          component.long_name;
        break;
    }
  }

  address1Field.value = address1;
  postalField.value = postcode;

  // After filling the form with address components from the Autocomplete
  // prediction, set cursor focus on the second address line to encourage
  // entry of subpremise information such as apartment, unit, or floor number.
  address2Field.focus();
}

JavaScript

function fillInAddress() {
  // Get the place details from the autocomplete object.
  const place = autocomplete.getPlace();
  let address1 = "";
  let postcode = "";

  // Get each component of the address from the place details,
  // and then fill-in the corresponding field on the form.
  // place.address_components are google.maps.GeocoderAddressComponent objects
  // which are documented at http://goo.gle/3l5i5Mr
  for (const component of place.address_components) {
    // @ts-ignore remove once typings fixed
    const componentType = component.types[0];

    switch (componentType) {
      case "street_number": {
        address1 = `${component.long_name} ${address1}`;
        break;
      }

      case "route": {
        address1 += component.short_name;
        break;
      }

      case "postal_code": {
        postcode = `${component.long_name}${postcode}`;
        break;
      }

      case "postal_code_suffix": {
        postcode = `${postcode}-${component.long_name}`;
        break;
      }
      case "locality":
        document.querySelector("#locality").value = component.long_name;
        break;
      case "administrative_area_level_1": {
        document.querySelector("#state").value = component.short_name;
        break;
      }
      case "country":
        document.querySelector("#country").value = component.long_name;
        break;
    }
  }

  address1Field.value = address1;
  postalField.value = postcode;
  // After filling the form with address components from the Autocomplete
  // prediction, set cursor focus on the second address line to encourage
  // entry of subpremise information such as apartment, unit, or floor number.
  address2Field.focus();
}

window.initAutocomplete = initAutocomplete;

Xem ví dụ

Tuỳ chỉnh văn bản giữ chỗ

Theo mặc định, trường văn bản do dịch vụ tự động hoàn thành tạo sẽ chứa văn bản phần giữ chỗ tiêu chuẩn. Để sửa đổi văn bản, hãy đặt thuộc tính placeholder trên phần tử input:

<input id="searchTextField" type="text" size="50" placeholder="Anything you want!">

Lưu ý: Văn bản giữ chỗ mặc định sẽ được bản địa hoá tự động. Nếu chỉ định giá trị phần giữ chỗ của riêng mình, bạn phải xử lý quá trình bản địa hoá giá trị đó trong ứng dụng. Để biết thông tin về cách API JavaScript của Google Maps chọn ngôn ngữ để sử dụng, vui lòng đọc tài liệu về bản địa hoá.

Xem phần Tạo kiểu cho tiện ích Tự động hoàn thành và SearchBox để tuỳ chỉnh giao diện của tiện ích.

SearchBox cho phép người dùng tìm kiếm thông tin địa lý bằng văn bản, chẳng hạn như "pizza ở New York" hoặc "cửa hàng giày gần đường robson". Bạn có thể đính kèm SearchBox vào trường văn bản và khi nhập văn bản, dịch vụ sẽ trả về nội dung gợi ý dưới dạng danh sách chọn thả xuống.

SearchBox cung cấp một danh sách mở rộng các cụm từ gợi ý, có thể bao gồm các địa điểm (do API Địa điểm xác định) cùng với các cụm từ tìm kiếm đề xuất. Ví dụ: nếu người dùng nhập 'pizza ở mới', danh sách lựa chọn có thể bao gồm cụm từ 'pizza ở New York, NY' cũng như tên của các cửa hàng pizza khác nhau. Khi người dùng chọn một địa điểm trong danh sách, thông tin về địa điểm đó sẽ được trả về đối tượng SearchBox và có thể được ứng dụng của bạn truy xuất.

Hàm khởi tạo SearchBox nhận hai đối số:

  • Một phần tử HTML input thuộc loại text. Đây là trường nhập dữ liệu mà dịch vụ SearchBox sẽ theo dõi và đính kèm kết quả.
  • Đối số options có thể chứa thuộc tính bounds: bounds là đối tượng google.maps.LatLngBounds chỉ định khu vực để tìm kiếm địa điểm. Kết quả thiên kiến (nhưng không chỉ gồm) những địa điểm nằm trong những giới hạn này.

Mã sau đây sử dụng tham số giới hạn để thiên vị kết quả đối với các địa điểm trong một khu vực địa lý cụ thể, được xác định thông qua toạ độ laitude/kinh độ.

var defaultBounds = new google.maps.LatLngBounds(
  new google.maps.LatLng(-33.8902, 151.1759),
  new google.maps.LatLng(-33.8474, 151.2631));

var input = document.getElementById('searchTextField');

var searchBox = new google.maps.places.SearchBox(input, {
  bounds: defaultBounds
});

Thay đổi khu vực tìm kiếm cho SearchBox

Để thay đổi khu vực tìm kiếm cho một SearchBox hiện có, hãy gọi setBounds() trên đối tượng SearchBox và truyền đối tượng LatLngBounds có liên quan.

Xem ví dụ

Đang tải thông tin về địa điểm

Khi người dùng chọn một mục trong các cụm từ gợi ý đính kèm với hộp tìm kiếm, dịch vụ sẽ kích hoạt một sự kiện places_changed. Bạn có thể gọi getPlaces() trên đối tượng SearchBox để truy xuất một mảng chứa nhiều dự đoán, mỗi dự đoán là một đối tượng PlaceResult.

Để biết thêm thông tin về đối tượng PlaceResult, hãy tham khảo tài liệu về kết quả thông tin chi tiết về địa điểm.

TypeScript

// Listen for the event fired when the user selects a prediction and retrieve
// more details for that place.
searchBox.addListener("places_changed", () => {
  const places = searchBox.getPlaces();

  if (places.length == 0) {
    return;
  }

  // Clear out the old markers.
  markers.forEach((marker) => {
    marker.setMap(null);
  });
  markers = [];

  // For each place, get the icon, name and location.
  const bounds = new google.maps.LatLngBounds();

  places.forEach((place) => {
    if (!place.geometry || !place.geometry.location) {
      console.log("Returned place contains no geometry");
      return;
    }

    const icon = {
      url: place.icon as string,
      size: new google.maps.Size(71, 71),
      origin: new google.maps.Point(0, 0),
      anchor: new google.maps.Point(17, 34),
      scaledSize: new google.maps.Size(25, 25),
    };

    // Create a marker for each place.
    markers.push(
      new google.maps.Marker({
        map,
        icon,
        title: place.name,
        position: place.geometry.location,
      })
    );

    if (place.geometry.viewport) {
      // Only geocodes have viewport.
      bounds.union(place.geometry.viewport);
    } else {
      bounds.extend(place.geometry.location);
    }
  });
  map.fitBounds(bounds);
});

JavaScript

// Listen for the event fired when the user selects a prediction and retrieve
// more details for that place.
searchBox.addListener("places_changed", () => {
  const places = searchBox.getPlaces();

  if (places.length == 0) {
    return;
  }

  // Clear out the old markers.
  markers.forEach((marker) => {
    marker.setMap(null);
  });
  markers = [];

  // For each place, get the icon, name and location.
  const bounds = new google.maps.LatLngBounds();

  places.forEach((place) => {
    if (!place.geometry || !place.geometry.location) {
      console.log("Returned place contains no geometry");
      return;
    }

    const icon = {
      url: place.icon,
      size: new google.maps.Size(71, 71),
      origin: new google.maps.Point(0, 0),
      anchor: new google.maps.Point(17, 34),
      scaledSize: new google.maps.Size(25, 25),
    };

    // Create a marker for each place.
    markers.push(
      new google.maps.Marker({
        map,
        icon,
        title: place.name,
        position: place.geometry.location,
      }),
    );
    if (place.geometry.viewport) {
      // Only geocodes have viewport.
      bounds.union(place.geometry.viewport);
    } else {
      bounds.extend(place.geometry.location);
    }
  });
  map.fitBounds(bounds);
});

Xem ví dụ

Xem phần Tạo kiểu cho tiện ích Tự động hoàn thành và SearchBox để tuỳ chỉnh giao diện của tiện ích.

Truy xuất các dự đoán Dịch vụ tự động hoàn thành địa điểm theo phương thức lập trình

Để truy xuất thông tin dự đoán theo phương thức lập trình, hãy sử dụng lớp AutocompleteService. AutocompleteService không thêm chế độ điều khiển giao diện người dùng nào. Thay vào đó, phương thức này sẽ trả về một mảng các đối tượng dự đoán, mỗi đối tượng chứa văn bản dự đoán, thông tin tham chiếu và thông tin chi tiết về cách kết quả khớp với hoạt động đầu vào của người dùng. Điều này sẽ hữu ích nếu bạn muốn có nhiều quyền kiểm soát giao diện người dùng hơn so với khả năng mà AutocompleteSearchBox cung cấp như mô tả ở trên.

AutocompleteService hiển thị các phương thức sau:

  • getPlacePredictions() trả về các thông tin gợi ý về địa điểm. Lưu ý: "Địa điểm" có thể là một cơ sở, vị trí địa lý hoặc địa điểm yêu thích nổi bật, theo xác định của Places API.
  • getQueryPredictions() trả về một danh sách mở rộng gồm các cụm từ gợi ý, có thể bao gồm các địa điểm (do API Places xác định) cùng với các cụm từ tìm kiếm đề xuất. Ví dụ: nếu người dùng nhập 'pizza ở mới', danh sách lựa chọn có thể bao gồm cụm từ 'pizza ở New York, NY' cũng như tên của các cửa hàng pizza khác nhau.

Cả hai phương thức ở trên đều trả về một mảng đối tượng dự đoán có dạng sau:

  • description là cụm từ gợi ý trùng khớp.
  • distance_meters là khoảng cách tính bằng mét của địa điểm từ AutocompletionRequest.origin được chỉ định.
  • matched_substrings chứa một tập hợp chuỗi con trong phần mô tả khớp với các phần tử trong dữ liệu đầu vào của người dùng. Thao tác này rất hữu ích khi bạn làm nổi bật các chuỗi con đó trong ứng dụng. Trong nhiều trường hợp, cụm từ tìm kiếm sẽ xuất hiện dưới dạng chuỗi con của trường mô tả.
    • length là độ dài của chuỗi con.
    • offset là độ lệch ký tự, được đo từ đầu chuỗi mô tả, tại đó chuỗi con trùng khớp xuất hiện.
  • place_id 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. Để truy xuất thông tin về địa điểm, hãy chuyển giá trị nhận dạng này vào trường placeId của yêu cầu Thông tin chi tiết về địa điểm. Tìm hiểu thêm về cách tham chiếu đến một địa điểm bằng mã địa điểm.
  • terms là một mảng chứa các phần tử của truy vấn. Đối với một địa điểm, mỗi phần tử thường sẽ tạo nên một phần của địa chỉ.
    • offset là độ lệch ký tự, được đo từ đầu chuỗi mô tả, tại đó chuỗi con trùng khớp xuất hiện.
    • value là cụm từ phù hợp.

Ví dụ dưới đây thực thi một yêu cầu dự đoán truy vấn cho cụm từ "pizza gần" và hiển thị kết quả trong một danh sách.

TypeScript

// This example retrieves autocomplete predictions programmatically from the
// autocomplete service, and displays them as an HTML list.
// This example requires the Places library. Include the libraries=places
// parameter when you first load the API. For example:
// <script src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&libraries=places">
function initService(): void {
  const displaySuggestions = function (
    predictions: google.maps.places.QueryAutocompletePrediction[] | null,
    status: google.maps.places.PlacesServiceStatus
  ) {
    if (status != google.maps.places.PlacesServiceStatus.OK || !predictions) {
      alert(status);
      return;
    }

    predictions.forEach((prediction) => {
      const li = document.createElement("li");

      li.appendChild(document.createTextNode(prediction.description));
      (document.getElementById("results") as HTMLUListElement).appendChild(li);
    });
  };

  const service = new google.maps.places.AutocompleteService();

  service.getQueryPredictions({ input: "pizza near Syd" }, displaySuggestions);
}

declare global {
  interface Window {
    initService: () => void;
  }
}
window.initService = initService;

JavaScript

// This example retrieves autocomplete predictions programmatically from the
// autocomplete service, and displays them as an HTML list.
// This example requires the Places library. Include the libraries=places
// parameter when you first load the API. For example:
// <script src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&libraries=places">
function initService() {
  const displaySuggestions = function (predictions, status) {
    if (status != google.maps.places.PlacesServiceStatus.OK || !predictions) {
      alert(status);
      return;
    }

    predictions.forEach((prediction) => {
      const li = document.createElement("li");

      li.appendChild(document.createTextNode(prediction.description));
      document.getElementById("results").appendChild(li);
    });
  };

  const service = new google.maps.places.AutocompleteService();

  service.getQueryPredictions({ input: "pizza near Syd" }, displaySuggestions);
}

window.initService = initService;

CSS

HTML

<html>
  <head>
    <title>Retrieving Autocomplete Predictions</title>
    <script src="https://polyfill.io/v3/polyfill.min.js?features=default"></script>

    <link rel="stylesheet" type="text/css" href="./style.css" />
    <script type="module" src="./index.js"></script>
  </head>
  <body>
    <p>Query suggestions for 'pizza near Syd':</p>
    <ul id="results"></ul>
    <!-- Replace Powered By Google image src with self hosted image. https://developers.google.com/maps/documentation/places/web-service/policies#other_attribution_requirements -->
    <img
      class="powered-by-google"
      src="https://storage.googleapis.com/geo-devrel-public-buckets/powered_by_google_on_white.png"
      alt="Powered by Google"
    />

    <!-- 
      The `defer` attribute causes the callback to execute after the full HTML
      document has been parsed. For non-blocking uses, avoiding race conditions,
      and consistent behavior across browsers, consider loading using Promises.
      See https://developers.google.com/maps/documentation/javascript/load-maps-js-api
      for more information.
      -->
    <script
      src="https://maps.googleapis.com/maps/api/js?key=AIzaSyB41DRUbKWJHPxaFjMAwdrzWzbVKartNGg&callback=initService&libraries=places&v=weekly"
      defer
    ></script>
  </body>
</html>

Thử mẫu

Xem ví dụ

Mã thông báo phiên

AutocompleteService.getPlacePredictions() có thể sử dụng mã thông báo phiên (nếu được triển khai) để nhóm các yêu cầu tự động hoàn thành lại với nhau cho mục đích thanh toán. Mã thông báo phiên sẽ nhóm các giai đoạn truy vấn và lựa chọn của hoạt động 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 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 vị trí. 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 phiên kết thúc, mã thông báo này 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 mỗi phiên. Bạn nên sử dụng mã phiên cho tất cả các phiên tự động hoàn thành. Nếu tham số sessionToken bị bỏ qua hoặc nếu bạn sử dụng lại mã phiên, thì phiên sẽ bị tính phí như thể không có mã thông báo phiên nào được cung cấp (mỗi yêu cầu được tính phí riêng).

Bạn có thể sử dụng cùng một mã thông báo phiên để thực hiện một yêu cầu Thông tin chi tiết về địa điểm duy nhất tại địa điểm phát sinh từ lệnh gọi đến AutocompleteService.getPlacePredictions(). Trong trường hợp này, yêu cầu tự động hoàn thành được kết hợp với yêu cầu Thông tin chi tiết về địa điểm và cuộc gọi sẽ được tính phí như một yêu cầu Thông tin chi tiết về địa điểm thông thường. Yêu cầu tự động hoàn tất không mất phí.

Hãy nhớ truyền một mã thông báo phiên duy nhất cho mỗi phiên mới. Việc sử dụng cùng một mã thông báo cho nhiều phiên Tự động hoàn thành sẽ vô hiệu hoá các phiên Tự động hoàn thành đó và tất cả yêu cầu Tự động hoàn thành trong các phiên không hợp lệ đó sẽ được tính phí riêng lẻ bằng cách sử dụng SKU Tự động hoàn thành cho mỗi yêu cầu. Đọc thêm về mã phiên.

Ví dụ sau đây cho thấy việc tạo mã thông báo phiên, sau đó truyền mã đó vào một AutocompleteService (vì vậy, bạn đã bỏ qua hàm displaySuggestions() vì lý do ngắn gọn):

// Create a new session token.
var sessionToken = new google.maps.places.AutocompleteSessionToken();

// Pass the token to the autocomplete service.
var autocompleteService = new google.maps.places.AutocompleteService();
autocompleteService.getPlacePredictions({
  input: 'pizza near Syd',
  sessionToken: sessionToken
},
displaySuggestions);

Hãy nhớ truyền một mã thông báo phiên duy nhất cho mỗi phiên mới. Việc sử dụng cùng một mã thông báo cho nhiều phiên sẽ khiến mỗi yêu cầu được tính phí riêng.

Đọc thêm về mã phiên.

Định kiểu cho tiện ích Tự động hoàn thành và SearchBox

Theo mặc định, các thành phần trên giao diện người dùng do AutocompleteSearchBox cung cấp sẽ được tạo kiểu để đưa vào bản đồ của Google. Bạn nên điều chỉnh kiểu cho phù hợp với trang web của mình. Hiện có các lớp CSS sau. Tất cả các lớp được liệt kê dưới đây đều áp dụng cho cả tiện ích AutocompleteSearchBox.

Hình minh hoạ dạng đồ hoạ về các lớp CSS cho các tiện ích Tự động hoàn thành và
      SearchBox
Các lớp CSS cho các tiện ích Tự động hoàn thành và SearchBox
lớp CSS Nội dung mô tả
pac-container Phần tử hình ảnh chứa danh sách các cụm từ gợi ý do dịch vụ Tự động hoàn thành theo địa điểm trả về. Danh sách này xuất hiện dưới dạng một danh sách thả xuống bên dưới tiện ích Autocomplete hoặc SearchBox.
pac-icon Biểu tượng hiển thị ở bên trái của từng mục trong danh sách dự đoán.
pac-item Một mục trong danh sách dự đoán do tiện ích Autocomplete hoặc SearchBox cung cấp.
pac-item:hover Mục khi người dùng di con trỏ chuột lên mục đó.
pac-item-selected Mục khi người dùng chọn qua bàn phím. Lưu ý: Các mục đã chọn sẽ là thành phần của lớp này và của lớp pac-item.
pac-item-query Một span bên trong pac-item là phần chính của nội dung dự đoán. Đối với vị trí địa lý, thuộc tính này chứa tên địa điểm, như "Sydney" hoặc tên đường phố và số nhà, chẳng hạn như "10 King Street". Đối với các lượt tìm kiếm bằng văn bản, chẳng hạn như "pizza ở New York", kết quả tìm kiếm sẽ chứa toàn bộ văn bản của cụm từ tìm kiếm. Theo mặc định, pac-item-query có màu đen. Nếu có bất kỳ văn bản bổ sung nào trong pac-item, thì văn bản đó nằm ngoài pac-item-query và kế thừa kiểu từ pac-item. Theo mặc định, thẻ này có màu xám. Văn bản bổ sung thường là một địa chỉ.
pac-matched Phần của cụm từ gợi ý được trả về khớp với thông tin mà người dùng nhập. Theo mặc định, văn bản trùng khớp này sẽ được làm nổi bật bằng văn bản in đậm. Xin lưu ý rằng văn bản trùng khớp có thể nằm ở vị trí bất kỳ trong pac-item. Thuộc tính này không nhất thiết thuộc pac-item-query, có thể một phần trong pac-item-query cũng như một phần trong văn bản còn lại trong pac-item.

Sử dụng thành phần Bộ chọn địa điểm

Lưu ý: Mẫu này sử dụng thư viện nguồn mở. Hãy xem phần README để được hỗ trợ và phản hồi về thư viện này.

Dùng thử các thành phần web. Sử dụng thành phần web của Bộ chọn địa điểm để bật tính năng nhập văn bản cho phép người dùng cuối tìm kiếm một địa chỉ hoặc địa điểm cụ thể bằng tính năng tự động hoàn thành.

Ảnh GIF bằng hộp tìm kiếm. Người dùng bắt đầu nhập địa chỉ làm mục nhập và một trình đơn thả xuống chứa các địa chỉ liên quan sẽ xuất hiện. Người dùng nhấp vào một địa chỉ từ trình đơn thả xuống và hộp tìm kiếm sẽ điền phần còn lại của địa chỉ.
Hình 1: Nhập văn bản để tìm kiếm một địa chỉ hoặc địa điểm cụ thể bằng tính năng tự động hoàn thành

Tối ưu hoá tính năng Tự động hoàn thành địa điểm

Phần này mô tả các phương pháp hay nhất để giúp bạn khai thác tối đa dịch vụ Tự động hoàn thành của địa điểm.

Dưới đây là một số nguyên tắc chung:

  • Cách nhanh nhất để phát triển một giao diện người dùng hoạt động hiệu quả là sử dụng tiện ích Tự động hoàn thành của API JavaScript Maps, Tiện ích Tự động hoàn thành của SDK Địa điểm dành cho Android hoặc SDK Địa điểm dành cho Kiểm soát giao diện người dùng Tự động hoàn thành dành cho iOS
  • Nâng cao sự hiểu biết về các trường dữ liệu thiết yếu của tính năng Tự động hoàn thành địa điểm ngay từ đầu.
  • Các trường xu hướng vị trí và giới hạn vị trí là không bắt buộc nhưng có thể có tác động đáng kể đến hiệu suất của tính năng tự động hoàn thành.
  • Xử lý lỗi để đảm bảo ứng dụng của bạn sẽ xuống cấp nhẹ nếu API trả về lỗi.
  • Hãy đảm bảo ứng dụng của bạn xử lý khi không có lựa chọn và cung cấp cho người dùng cách tiếp tục.

Các phương pháp hay nhất để tối ưu hoá chi phí

Tối ưu hoá chi phí cơ bản

Để tối ưu hoá chi phí sử dụng dịch vụ Tự động hoàn thành địa điểm, hãy sử dụng mặt nạ trường trong tiện ích Thông tin chi tiết về địa điểm và tiện ích Tự động hoàn thành địa điểm để chỉ trả về các trường dữ liệu địa điểm mà bạn cần.

Tối ưu hoá chi phí nâng cao

Hãy cân nhắc việc triển khai tính năng Tự động hoàn thành địa điểm theo phương thức lập trình để truy cập vào tính năng Mức giá theo yêu cầu và yêu cầu kết quả API mã hóa địa lý về địa điểm đã chọn thay vì Thông tin chi tiết về địa điểm. Đặt giá theo mỗi yêu cầu được kết hợp với API mã hóa địa lý sẽ tiết kiệm chi phí hơn so với đặt giá Theo mỗi phiên (dựa trên phiên) nếu đáp ứng cả hai điều kiện sau:

  • Nếu bạn chỉ cần vĩ độ/kinh độ hoặc địa chỉ của địa điểm người dùng đã chọn, API mã hoá địa lý sẽ cung cấp thông tin này cho ít hơn một cuộc gọi Chi tiết địa điểm.
  • Nếu người dùng chọn một cụm từ gợi ý tự động hoàn thành trong khoảng trung bình 4 yêu cầu cụm từ gợi ý Tự động hoàn thành trở xuống, thì tính năng đặt giá theo Mỗi yêu cầu có thể tiết kiệm chi phí hơn so với đặt giá theo mỗi phiên.
Để được hỗ trợ lựa chọn cách triển khai tính năng Tự động hoàn thành theo địa điểm phù hợp với nhu cầu của bạn, hãy chọn thẻ tương ứng với câu trả lời của bạn cho câu hỏi sau.

Ứng dụng của bạn có yêu cầu thông tin nào khác ngoài địa chỉ và vĩ độ/kinh độ của thông tin dự đoán đã chọn không?

Có, cần thêm thông tin

Sử dụng tính năng Tự động hoàn thành địa điểm dựa trên phiên với Thông tin chi tiết về địa điểm.
Vì ứng dụng của bạn yêu cầu Thông tin chi tiết về địa điểm như tên địa điểm, trạng thái doanh nghiệp hoặc giờ mở cửa, nên việc triển khai tính năng Tự động hoàn thành về địa điểm phải sử dụng mã phiên (theo chương trình hoặc tích hợp trong tiện ích JavaScript, Android hoặc iOS) với tổng chi phí là 0,017 đô la mỗi phiên cộng với SKU dữ liệu địa điểm áp dụng tuỳ thuộc vào trường dữ liệu địa điểm mà bạn yêu cầu

Triển khai tiện ích
Tính năng quản lý phiên được tự động tích hợp vào các tiện ích JavaScript, Android hoặc iOS. Dữ liệu này bao gồm cả yêu cầu Tự động hoàn thành về địa điểm và yêu cầu Chi tiết địa điểm đối với cụm từ gợi ý đã chọn. Nhớ chỉ định tham số fields để đảm bảo rằng bạn chỉ yêu cầu các trường dữ liệu vị trí mà bạn cần.

Triển khai có lập trình
Sử dụng mã thông báo của phiên với các yêu cầu Tự động hoàn thành địa điểm của bạn. Khi yêu cầu Thông tin chi tiết về địa điểm cho cụm từ gợi ý đã chọn, hãy cung cấp các thông số sau:

  1. Mã địa điểm từ phản hồi Tự động hoàn thành địa điểm
  2. Mã thông báo phiên được dùng trong yêu cầu Tự động hoàn thành địa điểm
  3. Tham số fields chỉ định các trường dữ liệu địa điểm mà bạn cần

Không, chỉ cần địa chỉ và vị trí

API mã hoá địa lý có thể là một lựa chọn tiết kiệm chi phí hơn so với Thông tin chi tiết về địa điểm cho ứng dụng của bạn, tuỳ thuộc vào hiệu suất sử dụng tính năng Tự động hoàn thành địa điểm của bạn. Hiệu quả của tính năng Tự động hoàn thành của mỗi ứng dụng sẽ khác nhau tuỳ thuộc vào nội dung mà người dùng đang nhập, nơi ứng dụng đang được sử dụng và việc liệu các phương pháp hay nhất về tối ưu hoá hiệu suất đã được triển khai hay chưa.

Để trả lời câu hỏi sau, hãy phân tích số lượng ký tự mà người dùng nhập trung bình trước khi chọn một dự đoán Tự động hoàn thành địa điểm trong ứng dụng của bạn.

Trung bình, người dùng của bạn có chọn một cụm từ gợi ý Tự động hoàn thành địa điểm trong tối đa 4 yêu cầu không?

Triển khai tính năng Tự động hoàn thành địa điểm theo phương thức lập trình mà không cần mã phiên và gọi API Mã hoá địa lý trên thông tin dự đoán địa điểm đã chọn.
API mã hoá địa lý cung cấp địa chỉ và vĩ độ/kinh độ với giá 0,005 USD cho mỗi yêu cầu. Việc thực hiện bốn yêu cầu Tự động hoàn thành địa điểm – Mỗi yêu cầu có chi phí là 0,01132 đô la Mỹ, do đó, tổng chi phí của 4 yêu cầu cộng với lệnh gọi API mã hoá địa lý về thông tin dự đoán địa điểm đã chọn sẽ là 0,01632 đô la, thấp hơn giá của tính năng Tự động hoàn thành cho mỗi phiên là 0,017 đô la Mỹ/phiên.1

Hãy cân nhắc áp dụng các phương pháp hay nhất về hiệu suất để giúp người dùng nhận được cụm từ gợi ý mà họ muốn chỉ bằng ít ký tự hơn nữa.

Không

Sử dụng tính năng Tự động hoàn thành địa điểm dựa trên phiên với Thông tin chi tiết về địa điểm.
Vì số lượng yêu cầu trung bình mà bạn muốn thực hiện trước khi người dùng chọn dự đoán Tự động hoàn thành địa điểm vượt quá chi phí định giá mỗi phiên, nên việc triển khai tính năng Tự động hoàn thành địa điểm của bạn phải sử dụng mã phiên cho cả yêu cầu Tự động hoàn thành địa điểm và yêu cầu Chi tiết địa điểm được liên kết với tổng chi phí là 0,017 USD mỗi phiên.1

Triển khai tiện ích
Tính năng quản lý phiên được tự động tích hợp vào các tiện ích JavaScript, Android hoặc iOS. Dữ liệu này bao gồm cả yêu cầu Tự động hoàn thành về địa điểm và yêu cầu Chi tiết địa điểm đối với cụm từ gợi ý đã chọn. Hãy nhớ chỉ định tham số fields để đảm bảo bạn chỉ yêu cầu các trường Dữ liệu cơ bản.

Triển khai có lập trình
Sử dụng mã thông báo của phiên với các yêu cầu Tự động hoàn thành địa điểm của bạn. Khi yêu cầu Thông tin chi tiết về địa điểm cho cụm từ gợi ý đã chọn, hãy cung cấp các thông số sau:

  1. Mã địa điểm từ phản hồi Tự động hoàn thành địa điểm
  2. Mã thông báo phiên được dùng trong yêu cầu Tự động hoàn thành địa điểm
  3. Tham số fields chỉ định các trường Dữ liệu cơ bản, chẳng hạn như địa chỉ và hình học

Cân nhắc việc trì hoãn các yêu cầu Tự động hoàn thành của địa điểm
Bạn có thể sử dụng các chiến lược như trì hoãn yêu cầu Tự động hoàn thành của địa điểm cho đến khi người dùng nhập ba hoặc bốn ký tự đầu tiên để ứng dụng của bạn đưa ra ít yêu cầu hơn. Ví dụ: việc thực hiện yêu cầu Tự động hoàn thành địa điểm cho từng ký tự sau khi người dùng nhập ký tự thứ ba có nghĩa là nếu người dùng nhập 7 ký tự rồi chọn một dự đoán mà bạn thực hiện một yêu cầu API mã hóa địa lý, thì tổng chi phí sẽ là 0,01632 đô la (4 * 0,00283 đô la Mỹ cho mỗi yêu cầu + 0,005 đô la Mã hóa địa lý).1

Nếu việc trì hoãn các yêu cầu có thể khiến yêu cầu có lập trình trung bình của bạn dưới 4, bạn có thể làm theo hướng dẫn triển khai Tự động hoàn thành địa điểm thực hiện bằng API mã hóa địa lý. Xin lưu ý rằng người dùng có thể xem các yêu cầu trì hoãn là độ trễ, vì người dùng này có thể sẽ thấy các cụm từ gợi ý mỗi khi nhấn phím mới.

Hãy cân nhắc áp dụng các phương pháp hay nhất về hiệu suất để giúp người dùng nhận được cụm từ gợi ý mà họ đang tìm trong ít ký tự hơn.


  1. Chi phí liệt kê tại đây được tính theo USD. Vui lòng tham khảo trang Thanh toán trên Nền tảng Google Maps để biết thông tin đầy đủ về giá cả.

Các phương pháp hay nhất về hiệu suất

Các nguyên tắc sau đây mô tả các cách tối ưu hóa hiệu suất của tính năng Tự động hoàn thành theo địa điểm:

  • Thêm các hạn chế theo quốc gia, xu hướng vị trí và lựa chọn ưu tiên về ngôn ngữ (đối với các phương thức triển khai có lập trình) vào phương thức triển khai tính năng Tự động hoàn thành theo địa điểm. Không cần thiết lập lựa chọn ưu tiên về ngôn ngữ cho các tiện ích vì chúng chọn lựa chọn ưu tiên về ngôn ngữ trên trình duyệt hoặc thiết bị di động của người dùng.
  • Nếu tính năng Tự động hoàn thành địa điểm đi kèm với một bản đồ, bạn có thể thiên vị vị trí theo khung nhìn bản đồ.
  • Trong trường hợp người dùng không chọn một trong các cụm từ gợi ý Tự động hoàn thành, thường là do không có cụm từ gợi ý nào trong số đó là địa chỉ kết quả mong muốn, thì bạn có thể sử dụng lại thông tin mà người dùng nhập ban đầu để tìm cách nhận được kết quả phù hợp hơn:
    • Nếu bạn muốn người dùng chỉ nhập thông tin địa chỉ, hãy sử dụng lại thông tin đầu vào ban đầu của người dùng trong lệnh gọi đến API mã hoá địa lý.
    • Nếu bạn muốn người dùng nhập cụm từ tìm kiếm cho một địa điểm cụ thể theo tên hoặc địa chỉ, hãy sử dụng yêu cầu Tìm địa điểm. Nếu kết quả chỉ được mong đợi ở một khu vực cụ thể, hãy sử dụng tính năng thiên về vị trí.
    Có một số trường hợp khác mà bạn nên quay lại sử dụng API Mã hoá địa lý:
    • Người dùng nhập địa chỉ cơ sở phụ ở những quốc gia chưa hỗ trợ tính năng Tự động hoàn thành cho địa điểm, ví dụ: Cộng hoà Séc, Estonia và Lithuania. Ví dụ: địa chỉ bằng tiếng Séc "StroupeAccessnického 3191/17, Praha" sẽ đưa ra thông tin dự đoán một phần trong tính năng Tự động hoàn thành địa điểm.
    • Người dùng nhập địa chỉ có tiền tố phân đoạn đường bộ như "23-30 29th St, Queens" ở Thành phố New York hoặc "47-380 Kamehameha Hwy, Kaneohe" trên đảo Kauai ở Hawai'i.

Chính sách và hạn mức sử dụng

Hạn mức

Để biết thông tin về hạn mức và giá, hãy xem Tài liệu về mức sử dụng và thanh toán cho Places API.

Chính sách

Khi sử dụng Thư viện địa điểm, API JavaScript của Maps phải tuân thủ các chính sách được mô tả cho API Địa điểm.