Thông báo: Kiểu bản đồ cơ sở mới sắp ra mắt trên Nền tảng Google Maps. Bản cập nhật này về kiểu bản đồ bao gồm bảng màu mặc định mới, ghim hiện đại và các điểm cải tiến về trải nghiệm và khả năng sử dụng bản đồ. Tất cả kiểu bản đồ sẽ được tự động cập nhật vào tháng 3 năm 2025. Để biết thêm thông tin về phạm vi cung cấp và cách chọn sử dụng sớm hơn, hãy xem bài viết Kiểu bản đồ mới cho Nền tảng Google Maps.

Trang này được dịch bởi Cloud Translation API.

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

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

Lưu ý: Thư viện phía máy chủ

Trang này mô tả thư viện phía máy khách có sẵn với API Maps JavaScript. Nếu bạn muốn làm việc với dịch vụ web API Địa điểm trên máy chủ, hãy xem Ứng dụng Node.js cho Dịch vụ Google Maps. Trang tại đường liên kết đó cũng giới thiệu Ứng dụng Java, Ứng dụng Python và Ứng dụng Go cho Dịch vụ Google Maps.

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 Maps JavaScript API. Bạn có thể sử dụng tính năng tự động hoàn thành để cung cấp cho ứng dụng của mình hành vi tìm kiếm nhập trước của trường tìm kiếm trên Google Maps. Dịch vụ tự động điền có thể so khớp theo từ đầy đủ và chuỗi con, phân giải tên địa điểm, địa chỉ và mã plus. 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 về địa điểm ngay lập tức. Theo định nghĩa của API Địa điểm, "địa điểm" có thể là một cơ sở, vị trí địa lý hoặc một điểm yêu thích nổi bật.

Bắt đầu

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

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

Chuyển đến Google Cloud Console.
Nhấp vào nút Chọn dự án, sau đó chọn chính dự án mà bạn đã thiết lập cho API JavaScript của Maps rồi nhấp vào Mở.
Trong danh sách API trên Trang tổng quan, hãy tìm API Địa điểm.
Nếu thấy API trong danh sách, tức là 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 BẬT API để hiển thị thẻ 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 Places API, sau đó chọn API đó trong danh sách kết quả.
3. Chọn BẬT. Khi quá trình này hoàn tất, API Địa điểm sẽ xuất hiện trong danh sách API trên Trang tổng quan.

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 Maps JavaScript chính. Để sử dụng chức năng có trong thư viện này, trước tiên, bạn phải tải chức năng đó bằ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.

Tóm tắt các lớp

API này cung cấp hai loại tiện ích tự động hoàn thành mà bạn có thể thêm thông qua các lớp Autocomplete và SearchBox tương ứng. 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 về API JavaScript của Maps: Lớp AutocompleteService).

Dưới đây là bản tóm tắt về các lớp có sẵn:

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 đó để nhập ký tự. Khi người dùng nhập văn bản, tính năng tự động hoàn thành sẽ trả về nội dung dự đoán về địa điểm ở 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 đó. Xem thông tin chi tiết bên dưới.

Hình 1: Trường văn bản tự động hoàn thành và danh sách chọn

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, 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 các cụm từ gợi ý, trong đó 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 được đề xuất. Ví dụ: nếu người dùng nhập "pizza ở new", danh sách chọn có thể bao gồm cụm từ "pizza ở New York, NY" cũng như tên của nhiều cửa hàng pizza.
- SearchBox cung cấp ít tuỳ chọn hơn Autocomplete để hạn chế nội dung tìm kiếm. Trong trường hợp trước, bạn có thể nghiêng về việc tìm kiếm một LatLngBounds nhất định. Trong trường hợp thứ hai, bạn có thể hạn chế tìm kiếm ở một quốc gia cụ thể và một số loại địa điểm cụ thể, cũng như đặt giới hạn. Để biết thêm thông tin, hãy xem bên dưới.
Hình 3: SearchBox hiển thị cụm từ tìm kiếm và thông tin dự đoán về địa điểm.

Xem thông tin chi tiết dưới đây.
Bạn có thể tạo đối tượng AutocompleteService để truy xuất thông tin dự đoán theo phương thức lập trình. 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 được đề xuất. Lưu ý: AutocompleteService không thêm bất kỳ thành phần điều khiển giao diện người dùng nào. Thay vào đó, các phương thức trên trả về một mảng các đối tượng dự đoán. Mỗi đối tượng dự đoán chứa văn bản của nội dung dự đoán, 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 dữ liệu đầu vào của người dùng. 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, cung cấp thông tin dự đoán về địa điểm trong danh sách lựa chọ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 yêu cầu getPlace(). Mỗi mục trong danh sách lựa 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ố:

Phần tử input HTML thuộc loại text. Đây là trường nhập mà dịch vụ tự động hoàn thành sẽ theo dõi và đính kèm kết quả của dịch vụ.
Đối số AutocompleteOptions không bắt buộc, 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 này hoặc nếu ['ALL'] được truyền vào, tất cả các trường có sẵn sẽ được trả về và được tính phí (không nên triển khai cho môi trường sản xuất). Để xem danh sách các trường, hãy xem PlaceResult.
- Một mảng types chỉ định một loại rõ ràng hoặc một tập hợp loại, như được liệt kê trong các loại đượ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à đối tượng google.maps.LatLngBounds chỉ định khu vực để tìm kiếm địa điểm. Kết quả có xu hướng thiên về, nhưng không giới hạn ở, các vị trí nằm trong những giới hạn này.
- strictBounds là một boolean chỉ định liệu API có phải chỉ trả về những địa điểm nằm hoàn toàn trong khu vực do 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 dữ liệu đầu vào của người dùng.
  Lưu ý: Quy tắc hạn chế vị trí chỉ áp dụng cho toàn bộ tuyến đường, kết quả tổng hợp nằm ngoài quy tắc hạn chế vị trí có thể được trả về dựa trên tuyến đường trùng lặp với quy tắc hạn chế vị trí.
- Bạn có thể sử dụng componentRestrictions để hạn chế kết quả cho một số 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 gồm hai ký tự, tương thích với ISO 3166-1 Alpha-2. Bạn phải truyề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ã bao gồm các quốc gia, lãnh thổ phụ thuộc và khu vực đặc biệt mà bạn quan tâm về mặt địa lý. Bạn có thể tìm thông tin về mã tại 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 của ISO.
- Bạn có thể sử dụng placeIdOnly để hướng dẫn tiện ích Autocomplete chỉ truy xuất mã nhận dạng địa điểm. Khi gọi getPlace() trên đối tượng Autocomplete, PlaceResult được cung cấp sẽ chỉ có các thuộc tính place id, types và name. Bạn có thể sử dụng mã nhận dạng đị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ý, Chỉ đường hoặc Ma trận khoảng cách.
  Lưu ý: Thuộc tính name sẽ chứa description từ các cụm từ gợi ý của tính năng Tự động hoàn thành trong Places. Bạn có thể đọc thêm về description trong tài liệu về AutocompleteService.
  
  Thông báo: placeIdOnly không còn được dùng nữa kể từ ngày 15 tháng 1 năm 2019 và sẽ bị tắt vào ngày 15 tháng 1 năm 2020. Thay vào đó, hãy sử dụng mảng fields trong giao diện AutocompleteOptions: fields: ['place_id', 'name', 'types'].

Giới hạn cụm từ gợi ý của tính năng Tự động hoàn thành

Theo mặc định, tính năng Tự động hoàn thành địa điểm sẽ hiển thị tất cả các loại địa điểm, ưu tiên các địa điểm dự đoán 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 cho Địa điểm để hiển thị các nội dung 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 tạo

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, componentRestrictions và types để yêu cầu địa điểm thuộc loại establishment, ưu tiên những địa điểm nằm trong khu vực địa lý được chỉ định và chỉ giới hạn kết quả dự đoán ở những địa điểm thuộc Hoa Kỳ. Việc đặt tuỳ chọn fields sẽ chỉ định thông tin cần trả về về địa điểm mà người dùng đã chọn.

Gọi setOptions() để thay đổi giá trị của một tuỳ chọn cho một 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);index.ts

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);
index.js

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 về địa điểm mà bạn không cần. Thêm thuộc tính fields vào 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 các thành phần thiên vị 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ể thiên vị 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 về việc tạo đối tượng Autocomplete.
Thay đổi các giới hạn trên Autocomplete hiện có.
Đặt ranh giới cho khung nhìn của bản đồ.
Hạn chế phạm vi tìm kiếm trong các giới hạn.
Hạn chế tìm kiếm ở một quốc gia cụ thể.

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

Lưu ý: Nếu bạn không cung cấp giới hạn hoặc khung nhìn bản đồ, API sẽ cố gắng phát hiện vị trí của người dùng từ địa chỉ IP của họ và sẽ thiên vị kết quả cho vị trí đó. Đặt giới hạn bất cứ khi nào có thể. Nếu không, người dùng khác nhau có thể nhận được kết quả dự đoán khác nhau. Ngoài ra, để cải thiện khả năng dự đoán nói chung, điều quan trọng là bạn phải cung cấp một khung nhìn hợp lý, chẳng hạn như khung nhìn mà bạn đặt bằng cách kéo hoặc thu phóng trên bản đồ, hoặc khung nhìn do nhà phát triển đặt dựa trên vị trí và bán kính của thiết bị. Khi không có bán kính, 5 km được coi là bán kính mặc định hợp lý cho tính năng Tự động hoàn thành địa điểm. Không đặt khung nhìn có bán kính bằng 0 (một điểm), khung nhìn chỉ rộng vài mét (dưới 100 m) hoặc khung nhìn trải dài trên toàn cầu.

Thay đổi giới hạn 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 giới hạn 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);index.ts

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);
index.js

Đặt ranh giới cho khung nhìn của bản đồ

Sử dụng bindTo() để thiên lệch kết quả cho khung nhìn của bản đồ, ngay cả khi khung nhìn đó thay đổi.

TypeScript

autocomplete.bindTo("bounds", map);index.ts

JavaScript

autocomplete.bindTo("bounds", map);
index.js

Sử dụng unbind() để huỷ liên kết các cụm từ gợi ý của tính năng Tự động hoàn thành khỏi khung nhìn của bản đồ.

TypeScript

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

JavaScript

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

Xem ví dụ

Hạn chế phạm vi tìm kiếm ở giới hạn hiện tại

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

autocomplete.setOptions({ strictBounds: true });

Hạn chế dự đoán ở một quốc gia cụ thể

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

TypeScript

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

JavaScript

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

Xem ví dụ

Hạn chế các loại địa điểm

Sử dụng tuỳ chọn types hoặc gọi setTypes() để ràng buộc các dự đoán cho 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 loại, như được liệt kê trong 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 truyề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 trong Loại địa điểm. Ví dụ:

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

hoặc:

autocomplete.setTypes(['hospital', 'pharmacy', 'bakery', 'country']);

Bất kỳ bộ lọc nào trong Bảng 3 thuộc Loại địa điểm. Bạn chỉ có thể chỉ định một giá trị 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 được nhận dạng.
Bạn có thể kết hợp bất kỳ loại nào trong 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ính năng Tự động hoàn thành của Places cho thấy sự khác biệt về nội dung gợi ý giữa các loại địa điểm.

Truy cập vào bản minh hoạ

Lấy thông tin về địa điểm

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

Tạo 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ý.
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 để biết 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 có sẵn cho địa điểm đã chọn và bạn sẽ được tính phí 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 danh sách các trường dữ liệu địa điểm mà bạn có thể yêu cầu. Để tránh phải trả phí cho dữ liệu mà bạn không cần, hãy nhớ sử dụng Autocomplete.setFields() để chỉ định dữ liệu vị trí mà bạn sẽ sử dụng.

LƯU Ý QUAN TRỌNG: Bạn không nên sử dụng tính năng tự động hoàn thành để làm mới Mã địa điểm, vì mỗi phiên sẽ bị tính phí. Thay vào đó, hãy gọi getDetails() và chỉ chỉ định trường place_id.

Thuộc tính name chứa description từ các cụm từ gợi ý của tính năng Tự động hoàn thành của Đị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 của Địa điểm.

Đối với biểu mẫu địa chỉ, bạn nên nhận đị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 vào các trường trong 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();
}index.ts

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;
index.js

Xem ví dụ

Thành phần địa chỉ street_number có thể không xuất hiện trong phản hồi Thông tin chi tiết về địa điểm cho mã địa điểm trong một số dự đoán tự động hoàn thành. Điều này thường xảy ra khi không thể nội suy địa chỉ cho một địa điểm. Trong những trường hợp này, mảng types của kết quả dự đoán sẽ chứa "tuyến đường". Đối với cụm từ gợi ý tự động hoàn thành có số trong nội dung mô tả (truy vấn đầu vào được so khớp), phản hồi Chi tiết địa điểm cho mã địa điểm chỉ chứa số nhà nếu mảng types cho cụm từ gợi ý chứa ít nhất một trong các thông tin sau:

street_address
tiền đề
cơ sở

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

Theo mặc định, trường văn bản do dịch vụ tự động điền tạo ra 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 đượ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ý việc 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ữ cần sử dụng, vui lòng đọc tài liệu về bản địa hoá.

Hãy xem phần Định 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 thực hiện tìm kiếm địa lý dựa trên 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 một trường văn bản và khi văn bản được nhập, dịch vụ sẽ trả về các dự đoán ở dạng danh sách chọn thả xuống.

SearchBox cung cấp danh sách mở rộng các cụm từ gợi ý, có thể bao gồm các địa điểm (do Places API xác định) cùng với các cụm từ tìm kiếm được đề xuất. Ví dụ: nếu người dùng nhập "pizza ở new", danh sách chọn có thể bao gồm cụm từ "pizza ở New York, NY" cũng như tên của nhiều cửa hàng pizza. 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à ứng dụng của bạn có thể truy xuất thông tin đó.

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

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

Mã sau đây sử dụng tham số giới hạn để thiên lệch kết quả về các địa điểm trong một khu vực địa lý cụ thể, được chỉ định thông qua toạ độ vĩ độ/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 vùng 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ụ

Khi người dùng chọn một mục trong nội dung gợi ý đính kèm vào 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 một số 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ả 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);
});index.ts

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);
});index.js

Xem ví dụ

Hãy xem phần Định 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 nội dung gợi ý của Dịch vụ tự động hoàn thành địa điểm theo phương thức lập trình

Để truy xuất kết quả 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 bất kỳ thành phần điều khiển nào trên giao diện người dùng. Thay vào đó, hàm này 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 của nội dung 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 dữ liệu đầu vào của người dùng. Điều này sẽ hữu ích nếu bạn muốn kiểm soát nhiều hơn đối với giao diện người dùng so với những gì Autocomplete và SearchBox cung cấp như mô tả ở trên.

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

getPlacePredictions() trả về thông tin dự đoán về địa điểm. Lưu ý: "Địa điểm" có thể là một cơ sở, vị trí địa lý hoặc điểm tham quan nổi bật, theo định nghĩa của API Địa điểm.
getQueryPredictions() trả về một danh sách mở rộng các nội dung dự đoán, trong đó 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 được đề xuất. Ví dụ: nếu người dùng nhập "pizza ở new", danh sách chọn có thể bao gồm cụm từ "pizza ở New York, NY" cũng như tên của nhiều cửa hàng pizza.

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

description là kết quả dự đoán phù hợp.
distance_meters là khoảng cách tính bằng mét của địa điểm từ AutocompletionRequest.origin đã chỉ định.
matched_substrings chứa một tập hợp các 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. Điều này hữu ích cho việc làm nổi bật các chuỗi con đó trong ứng dụng. Trong nhiều trường hợp, truy vấn sẽ xuất hiện dưới dạng một chuỗi con của trường mô tả.
- length là độ dài của chuỗi con.
- offset là độ dời ký tự, được đo từ đầu chuỗi mô tả, tại đó chuỗi con được so 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 truyề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 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 thành một phần của địa chỉ.
- offset là độ dời ký tự, được đo từ đầu chuỗi mô tả, tại đó chuỗi con được so khớp xuất hiện.
- value là từ khoá khớp.

Ví dụ bên dưới thực thi một yêu cầu dự đoán truy vấn cho cụm từ "pizza near" (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;index.ts

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;index.js

CSS

style.css

HTML

<html>
  <head>
    <title>Retrieving Autocomplete Predictions</title>

    <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 script 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>index.html

Thử mẫu

JSFiddle.net Google Cloud Shell

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 với nhau cho mục đích thanh toán. 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 phiên kết thúc, mã thông báo sẽ 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ã thông báo phiên cho tất cả phiên tự động hoàn thành. Nếu bạn bỏ qua tham số sessionToken hoặc sử dụng lại mã thông báo phiên, thì phiên sẽ được 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 để tạo một yêu cầu Thông tin chi tiết về địa điểm về địa điểm thu được 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à lệnh 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. Bạn sẽ không phải trả phí cho yêu cầu tự động hoàn thành.

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ẽ làm mất hiệu lực 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 theo yêu cầu. Đọc thêm về mã thông báo phiên.

Ví dụ sau đây cho thấy cách tạo mã thông báo phiên, sau đó truyền mã thông báo đó trong AutocompleteService (đã bỏ qua hàm displaySuggestions() để viết 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ã thông báo phiên.

Định kiểu cho các tiện ích Autocomplete (Tự động hoàn thành) và SearchBox (Hộp tìm kiếm)

Theo mặc định, các thành phần trên giao diện người dùng do Autocomplete và SearchBox cung cấp đượ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. Các lớp CSS sau đây có sẵn. Tất cả các lớp được liệt kê bên dưới đều áp dụng cho cả tiện ích Autocomplete và SearchBox.

Hình minh hoạ đồ hoạ các lớp CSS cho tiện ích Tự động hoàn thành và SearchBox — Các lớp CSS cho tiện ích Tự động hoàn thành và SearchBox

Lớp CSS	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 địa điểm trả về. Danh sách này xuất hiện dưới dạng 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 mỗi 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 chuột qua mục đó.
`pac-item-selected`	Mục khi người dùng chọn mục đó thông qua bàn phím. Lưu ý: Các mục đã chọn sẽ là thành viên của lớp này và lớp `pac-item`.
`pac-item-query`	Một span bên trong `pac-item` là phần chính của dự đoán. Đối với vị trí địa lý, thuộc tính này chứa tên địa điểm, chẳng hạn như "Sydney" hoặc tên và số đường, chẳng hạn như "10 King Street". Đối với các cụm từ tìm kiếm dựa trên văn bản như "pizza ở New York", thuộc tính này 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 bên ngoài `pac-item-query` và kế thừa kiểu của văn bản từ `pac-item`. Theo mặc định, nút này có màu xám. Văn bản bổ sung thường là địa chỉ.
`pac-matched`	Phần của kết quả dự đoán được trả về khớp với dữ liệu đầu vào của người dùng. Theo mặc định, văn bản đã 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 đã so khớp có thể nằm ở bất kỳ vị trí nào trong `pac-item`. Phần này không nhất thiết phải là một phần của `pac-item-query` và có thể nằm 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`.

Tối ưu hoá tính năng Tự động hoàn thành của Place

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 địa điểm.

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

Cách nhanh nhất để phát triển giao diện người dùng hoạt động là sử dụng Tiện ích tự động hoàn thành API Maps JavaScript, Tiện ích tự động hoàn thành SDK Địa điểm dành cho Android hoặc Chế độ điều khiển giao diện người dùng tự động hoàn thành SDK Địa điểm dành cho iOS
Ngay từ đầu, hãy tìm hiểu về các trường dữ liệu cần thiết của tính năng Tự động điền địa điểm.
Các trường thiên vị vị trí và hạn chế vị trí là không bắt buộc nhưng có thể ảnh hưởng đáng kể đến hiệu suất của tính năng tự động hoàn thành.
Sử dụng tính năng xử lý lỗi để đảm bảo ứng dụng của bạn giảm hiệu suất một cách linh hoạt nếu API trả về lỗi.
Đảm bảo ứng dụng của bạn xử lý khi không có lựa chọn nào và cung cấp cho người dùng một 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 điền địa điểm, hãy sử dụng mặt nạ trường trong tiện ích Chi tiết địa điểm và Tự động điền đị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 Giá theo yêu cầu và yêu cầu Kết quả của API Địa chỉ về địa điểm đã chọn thay vì Thông tin chi tiết về địa điểm. Giá theo yêu cầu kết hợp với API Địa chỉ được mã hoá địa lý sẽ tiết kiệm chi phí hơn so với giá theo 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 mà người dùng đã chọn, thì API Địa chỉ được mã hoá địa lý sẽ cung cấp thông tin này với chi phí thấp hơn một lệnh gọi Thông tin chi tiết về đị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 trung bình 4 yêu cầu cụm từ gợi ý tự động hoàn thành trở xuống, thì mức giá Theo yêu cầu có thể tiết kiệm chi phí hơn so với mức giá Theo phiên.

Để được trợ giúp về cách chọn cách triển khai tính năng Tự động hoàn thành đị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, chẳng hạn như tên địa điểm, trạng thái hoạt động kinh doanh hoặc giờ mở cửa, nên khi triển khai tính năng Tự động hoàn thành địa điểm, bạn phải sử dụng mã thông báo phiên (theo phương thức lập trình hoặc được tích hợp vào tiện ích JavaScript, Android hoặc iOS) với tổng chi phí là 0,017 USD cho mỗi phiên cộng với SKU Dữ liệu địa điểm hiện hành 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 tiện ích JavaScript, Android hoặc iOS. Trong đó bao gồm 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 trên 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 về địa điểm mà bạn cần.

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

Mã địa điểm trong phản hồi của tính năng Tự động hoàn thành địa điểm
Mã thông báo phiên được sử dụng trong yêu cầu Place Autocomplete
Tham số fields chỉ định các trường dữ liệu vị trí mà bạn cần

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

API Địa chỉ được mã hoá địa lý có thể là một lựa chọn tiết kiệm chi phí hơn so với Chi tiết địa điểm cho ứng dụng của bạn, tuỳ thuộc vào hiệu suất của tính năng Tự động hoàn thành địa điểm. Hiệu suất 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 người dùng đang nhập, vị trí ứng dụng đang được sử dụng và việc bạn đã triển khai các phương pháp hay nhất để tối ưu hoá hiệu suất hay chưa.

Để trả lời câu hỏi sau, hãy phân tích số lượng ký tự trung bình mà người dùng nhập trước khi chọn một nội dung 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ó chọn một cụm từ gợi ý tự động hoàn thành về Địa điểm trong 4 yêu cầu trở xuống không?

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 mà không cần mã thông báo phiên và gọi API Địa chỉ (Geocoding API) trên thông tin gợi ý về địa điểm đã chọn.
API Mã hoá địa lý cung cấp địa chỉ và toạ độ vĩ độ/kinh độ với mức phí 0,005 USD/yêu cầu. Việc tạo 4 yêu cầu Tự động hoàn thành địa điểm – Mỗi yêu cầu sẽ tốn 0,01132 đô la. Vì vậy, tổng chi phí của 4 yêu cầu cộng với một lệnh gọi Geocoding API về thông tin gợi ý đị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 theo phiên là 0,017 đô la/phiên.¹

Hãy cân nhắc việ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 nội dung gợi ý mà họ đang tìm kiếm chỉ bằng một vài ký tự.

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 dự kiến sẽ thực hiện trước khi người dùng chọn một kết quả dự đoán của tính năng Tự động hoàn thành địa điểm vượt quá chi phí theo mô hình tính phí theo Phiên, nên khi triển khai tính năng Tự động hoàn thành địa điểm, bạn phải sử dụng mã thông báo phiên cho cả yêu cầu Tự động hoàn thành địa điểm và yêu cầu Thông tin chi tiết về địa điểm được liên kết với tổng chi phí là 0,017 USD cho mỗi phiên.¹

Mã địa điểm trong phản hồi của tính năng Tự động hoàn thành địa điểm
Mã thông báo phiên được sử dụng trong yêu cầu Place Autocomplete
Tham số fields chỉ định các trường Dữ liệu cơ bản như địa chỉ và hình học

Cân nhắc trì hoãn các yêu cầu Tự động điền địa điểm
Bạn có thể áp dụng các chiến lược như trì hoãn yêu cầu Tự động điền đị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 gửi ít yêu cầu hơn. Ví dụ: việc tạo các yêu cầu Tự động hoàn thành địa điểm cho mỗi 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 cụm từ gợi ý mà bạn tạo một yêu cầu API Mã hoá địa lý, thì tổng chi phí sẽ là 0,01632 đô la Mỹ (4 * 0,00283 đô la Mỹ cho mỗi yêu cầu Tự động hoàn thành + 0,005 đô la Mỹ cho mỗi yêu cầu Mã hoá địa lý).¹

Nếu việc trì hoãn yêu cầu có thể làm giảm số yêu cầu có lập trình trung bình xuống dưới 4, thì bạn có thể làm theo hướng dẫn để triển khai tính năng Tự động hoàn thành địa điểm hiệu quả bằng API Địa chỉ. Xin lưu ý rằng người dùng có thể coi việc trì hoãn các yêu cầu là độ trễ, vì họ có thể mong đợi thấy nội dung dự đoán với mỗi thao tác nhấn phím mới.

Hãy cân nhắc việ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 nội dung gợi ý mà họ đang tìm kiếm trong ít ký tự hơn.

Chi phí được liệt kê ở đây tính theo USD. Vui lòng tham khảo trang Thanh toán trên Google Maps Platform để biết toàn bộ thông tin về giá.

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ách tối ưu hoá hiệu suất của tính năng Tự động hoàn thành địa điểm:

Thêm các quy định hạn chế về quốc gia, tính năng thiên vị vị trí và lựa chọn ưu tiên về ngôn ngữ (đối với việc triển khai theo phương thức lập trình) vào quá trình triển khai tính năng Tự động hoàn thành địa điểm. Bạn không cần lựa chọn ưu tiên về ngôn ngữ cho tiện ích vì các tiện ích sẽ chọn lựa chọn ưu tiên về ngôn ngữ từ 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 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 ý của tính năng Tự động hoàn thành, thường là vì không có cụm từ gợi ý nào là địa chỉ kết quả mong muốn, bạn có thể sử dụng lại dữ liệu đầu vào ban đầu của người dùng để cố gắng 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 dữ liệu đầ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 bạn chỉ mong đợi kết quả ở một khu vực cụ thể, hãy sử dụng tính năng thiên vị vị trí.
Các trường hợp khác mà bạn nên quay lại sử dụng API Địa chỉ được mã hoá địa lý bao gồm:
- Người dùng nhập địa chỉ cơ sở phụ, chẳng hạn như địa chỉ của các căn hộ hoặc căn phòng cụ thể trong một toà nhà. Ví dụ: địa chỉ bằng tiếng Séc "Stroupežnického 3191/17, Praha" sẽ đưa ra một phần nội dung gợi ý 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ố đoạn đường như "23-30 29th St, Queens" ở Thành phố New York hoặc "47-380 Kamehameha Hwy, Kaneohe" trên đảo Kauai ở Hawaii.

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à mức giá, hãy xem Tài liệu về việc sử dụng và thanh toán cho API Địa điểm.

Chính sách

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

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

Giới thiệu

Bắt đầu

Tải thư viện

Tóm tắt các lớp

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

Giới hạn cụm từ gợi ý của tính năng Tự động hoàn thành

Đặt tuỳ chọn khi tạo

TypeScript

JavaScript

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

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

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

TypeScript

JavaScript

Đặt ranh giới cho khung nhìn của bản đồ

TypeScript

JavaScript

TypeScript

JavaScript

Hạn chế phạm vi tìm kiếm ở giới hạn hiện tại

Hạn chế dự đoán ở một quốc gia cụ thể

TypeScript

JavaScript

Hạn chế các loại địa điểm

Lấy thông tin về địa điểm

TypeScript

JavaScript

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

Thêm tiện ích SearchBox

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

Lấy thông tin về địa điểm

TypeScript

JavaScript

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

TypeScript

JavaScript

CSS

HTML

Thử mẫu

Mã thông báo phiên

Định kiểu cho các tiện ích Autocomplete (Tự động hoàn thành) và SearchBox (Hộp tìm kiếm)

Tối ưu hoá tính năng Tự động hoàn thành của Place

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í nâng cao

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

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

Có

Không

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

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

Hạn mức

Chính sách