Dịch vụ Tự động hoàn thành (Mới) là một dịch vụ web trả về một vị trí các dự đoán và truy vấn dự đoán nhằm phản hồi yêu cầu HTTP. Trong yêu cầu, hãy chỉ định văn bản chuỗi tìm kiếm và giới hạn địa lý kiểm soát khu vực tìm kiếm.
Dịch vụ Tự động hoàn thành (Mới) có thể so khớp toàn bộ từ và chuỗi con của thông tin đầu vào, phân giải tên địa điểm, địa chỉ và mã cộng. Do đó, ứng dụng có thể gửi các truy vấn khi người dùng nhập, để cung cấp các dự đoán truy vấn và địa điểm nhanh chóng.
Phản hồi từ API Tự động hoàn thành (Mới) có thể chứa 2 loại dự đoán:
- Cụm từ gợi ý về địa điểm: Các địa điểm (chẳng hạn như doanh nghiệp, địa chỉ và điểm của) sở thích, dựa trên chuỗi văn bản đã nhập và vùng tìm kiếm được chỉ định. Các gợi ý về địa điểm là được trả về theo mặc định.
- Dự đoán truy vấn: Chuỗi truy vấn khớp với chuỗi văn bản đầu vào và
khu vực tìm kiếm. Các dự đoán truy vấn không được trả về theo mặc định. Sử dụng
includeQueryPredictions
yêu cầu tham số để thêm các dự đoán truy vấn vào của bạn.
Ví dụ: bạn gọi API bằng cách sử dụng dữ liệu đầu vào là một chuỗi có chứa một phần hoạt động đầu vào của người dùng, "Sicilian piz", với khu vực tìm kiếm giới hạn ở San Francisco, CA. Sau đó, phản hồi chứa danh sách cụm từ gợi ý địa điểm khớp với chuỗi tìm kiếm và khu vực tìm kiếm, chẳng hạn như nhà hàng có tên là "Sicilian Pizza Kitchen", cùng thông tin chi tiết về địa điểm này.
Gợi ý địa điểm được trả về được thiết kế để hiển thị với người dùng nhằm hỗ trợ họ trong việc chọn địa điểm mong muốn. Bạn có thể tạo một Thông tin chi tiết về địa điểm (Mới) yêu cầu để biết thêm thông tin về bất kỳ cụm từ gợi ý nào về địa điểm được trả về.
Phản hồi cũng có thể chứa danh sách cụm từ gợi ý truy vấn khớp với
chuỗi tìm kiếm và khu vực tìm kiếm, chẳng hạn như "Sicilian Pizza & Mì ống". Mỗi dự đoán truy vấn trong
phản hồi bao gồm trường text
chứa chuỗi tìm kiếm bằng văn bản được đề xuất. Sử dụng địa chỉ đó
làm dữ liệu đầu vào
Tìm kiếm văn bản (Mới)
để tìm kiếm chi tiết hơn.
API Explorer cho phép bạn đưa ra các yêu cầu trực tiếp để bạn có thể làm quen với API và Tuỳ chọn API:
Hãy làm thử!Yêu cầu tự động hoàn thành (Mới)
Yêu cầu Tự động hoàn thành (Mới) là một yêu cầu POST qua HTTP tới một URL trong biểu mẫu:
https://places.googleapis.com/v1/places:autocomplete
Truyền tất cả các tham số trong nội dung của yêu cầu JSON hoặc trong tiêu đề dưới dạng một phần của yêu cầu POST. Ví dụ:
curl -X POST -d '{ "input": "pizza", "locationBias": { "circle": { "center": { "latitude": 37.7937, "longitude": -122.3965 }, "radius": 500.0 } } }' \ -H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \ https://places.googleapis.com/v1/places:autocomplete
Giới thiệu về câu trả lời
Tính năng Tự động hoàn thành (Mới) trả về một đối tượng JSON dưới dạng phản hồi. Trong câu trả lời:
- Mảng
suggestions
chứa tất cả các địa điểm và truy vấn được dự đoán theo thứ tự dựa trên mức độ liên quan mà họ cảm nhận được. Mỗi địa điểm được đại diện bằng một TrườngplacePrediction
và mỗi truy vấn được biểu thị bởi trườngqueryPrediction
. - Trường
placePrediction
chứa thông tin chi tiết về một thông tin dự đoán về địa điểm, bao gồm cả mã địa điểm và nội dung mô tả bằng văn bản. - Trường
queryPrediction
chứa thông tin chi tiết về một dự đoán truy vấn.
Đối tượng JSON hoàn chỉnh có dạng:
{ "suggestions": [ { "placePrediction": { "place": "places/ChIJ5YQQf1GHhYARPKG7WLIaOko", "placeId": "ChIJ5YQQf1GHhYARPKG7WLIaOko", "text": { "text": "Amoeba Music, Haight Street, San Francisco, CA, USA", "matches": [ { "endOffset": 6 }] }, ... }, { "queryPrediction": { "text": { "text": "Amoeba Music", "matches": [ { "endOffset": 6 }] }, ... } ...] }
Thông số bắt buộc
-
input
Chuỗi văn bản mà bạn muốn tìm kiếm. Chỉ định từ đầy đủ và chuỗi con, tên địa điểm, địa chỉ và mã cộng. Dịch vụ Tự động hoàn thành (Mới) trả về kết quả phù hợp đề xuất dựa trên chuỗi này và kết quả đơn hàng dựa vào mức độ liên quan mà họ cảm nhận được.
Thông số tùy chọn
-
includedPrimaryTypes
Một địa điểm chỉ có thể có một loại chính trong số các loại được liệt kê trong Bảng A hoặc Bảng B. Ví dụ: loại chính có thể là
"mexican_restaurant"
hoặc"steak_house"
.Theo mặc định, API trả về tất cả địa điểm dựa trên tham số
input
, bất kể của giá trị loại chính được liên kết với địa điểm. Giới hạn kết quả ở một số nội dung loại chính hoặc loại chính bằng cách truyền tham sốincludedPrimaryTypes
.Sử dụng tham số này để chỉ định tối đa 5 giá trị loại từ Bảng A hoặc Bảng B. Địa điểm phải khớp với một trong các giá trị loại chính được chỉ định để đưa vào phản hồi.
Tham số này cũng có thể bao gồm
(regions)
hoặc(cities)
. Bộ lọc tập hợp loại(regions)
cho các khu vực hoặc đơn vị phân chia, chẳng hạn như vùng lân cận và mã bưu chính. Bộ lọc bộ sưu tập loại(cities)
cho các địa điểm mà Google xác định là thành phố.Yêu cầu sẽ bị từ chối kèm theo lỗi
INVALID_REQUEST
nếu:- Có hơn 5 loại được chỉ định.
- Ngoài
(cities)
hoặc(regions)
, mọi kiểu được chỉ định. - Mọi loại không nhận dạng được đều được chỉ định.
-
includeQueryPredictions
Nếu là
true
, phản hồi sẽ bao gồm cả thông tin dự đoán về địa điểm và truy vấn. Mặc định làfalse
, nghĩa là câu trả lời chỉ bao gồm thông tin dự đoán về địa điểm. -
includedRegionCodes
Chỉ bao gồm kết quả từ danh sách các khu vực đã chỉ định, được chỉ định dưới dạng một mảng tối đa là 15 ccTLD ("miền cấp cao nhất") 2 ký tự. Nếu bỏ qua, không có hạn chế nào được áp dụng cho câu trả lời. Ví dụ: để giới hạn khu vực ở Đức và Pháp:
"includedRegionCodes": ["de", "fr"]
Nếu bạn chỉ định cả
locationRestriction
vàincludedRegionCodes
, các kết quả nằm trong khu vực giao nhau của hai chế độ cài đặt này. -
inputOffset
Độ lệch ký tự Unicode dựa trên 0 cho biết vị trí con trỏ trong
input
. Vị trí con trỏ có thể ảnh hưởng đến cụm từ gợi ý mà hệ thống trả về. Nếu trống, giá trị mặc định sẽ là độ dàiinput
. -
languageCode
Ngôn ngữ ưu tiên dùng để trả về kết quả. Kết quả có thể bằng các ngôn ngữ kết hợp nếu ngôn ngữ dùng trong
input
khác với giá trị được chỉ định bởilanguageCode
hoặc nếu địa điểm được trả về không có bản dịch từ sanglanguageCode
.- Bạn phải sử dụng IETF Mã ngôn ngữ BCP-47 để chỉ định ngôn ngữ ưu tiên.
-
Nếu
languageCode
không được cung cấp, API sẽ sử dụng giá trị được chỉ định trong Tiêu đềAccept-Language
. Nếu không có đối tượng nào được chỉ định, giá trị mặc định sẽ làen
. Nếu bạn chỉ định mã ngôn ngữ không hợp lệ, API sẽ trả về mộtINVALID_ARGUMENT
lỗi. - Ngôn ngữ ưu tiên có ảnh hưởng nhỏ đến nhóm kết quả mà API chọn trả về và thứ tự mà hàm được trả về. Điều này cũng ảnh hưởng đến khả năng sửa lỗi chính tả của API.
-
API cố gắng cung cấp địa chỉ đường phố mà cả người dùng và người dùng có thể đọc được
dân số địa phương, đồng thời phản ánh hoạt động đầu vào của người dùng. Các gợi ý về địa điểm là
có định dạng khác nhau tuỳ thuộc vào hoạt động đầu vào của người dùng trong mỗi yêu cầu.
-
Các cụm từ khớp trong thông số
input
được chọn trước tiên, sử dụng tên được căn chỉnh với tùy chọn ngôn ngữ được biểu thị bằng thông sốlanguageCode
khi sẵn có, trong khi sử dụng tên phù hợp nhất với hoạt động đầu vào của người dùng. -
Địa chỉ đường phố được định dạng bằng ngôn ngữ địa phương, bằng tập lệnh mà người dùng có thể đọc được
khi có thể, chỉ sau khi các cụm từ trùng khớp đã được chọn để khớp với các cụm từ trong
Tham số
input
. -
Tất cả các địa chỉ khác được trả về bằng ngôn ngữ ưu tiên, sau khi các cụm từ trùng khớp
đã được chọn để khớp với các cụm từ trong thông số
input
. Nếu tên không phải là có sẵn bằng ngôn ngữ ưu tiên, API sẽ sử dụng kết quả khớp gần nhất.
-
Các cụm từ khớp trong thông số
Vị tríBias hoặc locationRestriction (Hạn chế vị trí)
Bạn có thể chỉ định
locationBias
hoặclocationRestriction
, nhưng không phải cả hai để xác định khu vực tìm kiếm. Hãy coilocationRestriction
là việc chỉ định khu vực nơi có kết quả vàlocationBias
là chỉ định khu vực nơi kết quả phải ở gần nhưng có thể ở bên ngoài khu vực đó.locationBias
Chỉ định một vùng để tìm kiếm. Vị trí này có nghĩa là có thể trả về kết quả quanh vị trí chỉ định, bao gồm kết quả bên ngoài khu vực được chỉ định.
locationRestriction
Chỉ định một vùng để tìm kiếm. Kết quả nằm ngoài khu vực được chỉ định không bị trả lại.
Chỉ định vùng
locationBias
hoặclocationRestriction
làm Khung nhìn hình chữ nhật hoặc dưới dạng hình tròn.Một đường tròn được xác định bởi tâm điểm và bán kính tính bằng mét. Bán kính phải nằm trong khoảng 0.0 và 50000.0. Giá trị mặc định là 0,0. Đối với
locationRestriction
, bạn phải đặt bán kính thành một giá trị lớn hơn 0,0. Nếu không, yêu cầu sẽ được trả về không có kết quả.Ví dụ:
"locationBias": { "circle": { "center": { "latitude": 37.7937, "longitude": -122.3965 }, "radius": 500.0 } }
Hình chữ nhật là một khung nhìn vĩ độ – kinh độ, được biểu thị dưới dạng hai theo đường chéo đối diện
low
và điểm cao. Khung nhìn được xem là khu vực khép kín, nghĩa là khu vực này bao gồm ranh giới của nó. Giới hạn vĩ độ phải nằm trong khoảng từ -90 đến 90 độ và giới hạn kinh độ phải nằm trong khoảng từ -180 độ đến 180 độ, bao gồm cả hai giá trị sau:- Nếu
low
=high
, khung nhìn chỉ bao gồm một điểm duy nhất đó. - Nếu
low.longitude
>high.longitude
, phạm vi kinh độ bị đảo ngược (khung nhìn vượt qua đường kinh độ 180 độ). - Nếu
low.longitude
= -180 độ vàhigh.longitude
= 180 độ, khung nhìn bao gồm tất cả kinh độ. - Nếu
low.longitude
= 180 độ vàhigh.longitude
= -180 độ, phạm vi kinh độ trống.
Cả
low
vàhigh
đều phải được điền và nhập vào hộp được đại diện không được để trống. Khung nhìn trống dẫn đến lỗi.Ví dụ: khung nhìn này bao quanh hoàn toàn Thành phố New York:
"locationBias": { "rectangle": { "low": { "latitude": 40.477398, "longitude": -74.259087 }, "high": { "latitude": 40.91618, "longitude": -73.70018 } } }
- Nếu
-
nguồn gốc
Điểm gốc để tính khoảng cách theo đường thẳng đến điểm đến (được trả về dưới dạng
distanceMeters
). Nếu giá trị này là bị bỏ qua, khoảng cách đường thẳng sẽ không được trả về. Phải được chỉ định là vĩ độ và kinh độ:"origin": { "latitude": 40.477398, "longitude": -74.259087 }
-
regionCode
Mã vùng dùng để định dạng phản hồi, được chỉ định làm ccTLD ("miền cấp cao nhất") 2 ký tự. Hầu hết mã ccTLD (miền cấp cao nhất theo mã quốc gia) đều giống với mã ISO 3166-1, với một số ngoại lệ đáng chú ý. Ví dụ: ccTLD (miền cấp cao nhất theo mã quốc gia) của Vương quốc Anh là "Vương quốc Anh" (.co.uk) trong khi mã ISO 3166-1 của trang web là "gb" (về mặt kỹ thuật cho pháp nhân "Vương quốc Anh và Bắc Ireland").
Nếu bạn chỉ định mã vùng không hợp lệ, API sẽ trả về
INVALID_ARGUMENT
. Tuỳ theo luật hiện hành, thông số này có thể ảnh hưởng đến kết quả. -
sessionToken
Mã thông báo phiên là các chuỗi do người dùng tạo theo dõi tính năng Tự động hoàn thành (Mới) gọi là "phiên". Tính năng Tự động hoàn thành (Mới) sử dụng mã thông báo phiên để nhóm các giai đoạn truy vấn và lựa chọn của tự động hoàn thành tìm kiếm của người dùng thành một phiên riêng biệt cho cho mục đích thanh toán. Để biết thêm thông tin, hãy xem Mã thông báo phiên.
Ví dụ về tính năng Tự động hoàn thành (Mới)
Sử dụng vị trí Hạn chế và vị tríBias
Theo mặc định, API sử dụng xu hướng IP để kiểm soát khu vực tìm kiếm. Với xu hướng IP, API sử dụng
Địa chỉ IP của thiết bị để sai lệch kết quả. Bạn có thể tuỳ ý sử dụng
locationRestriction
hoặc locationBias
(nhưng không phải cả hai) để chỉ định một khu vực cần tìm kiếm.
locationRestriction
chỉ định khu vực cần tìm kiếm. Kết quả nằm ngoài khu vực đã chỉ định
sẽ không được trả lại. Trong ví dụ sau, bạn sử dụng locationRestriction
để giới hạn
đưa ra yêu cầu đối với vòng tròn bán kính 5000 mét có tâm ở San Francisco:
curl -X POST -d '{ "input": "Amoeba", "locationRestriction": { "circle": { "center": { "latitude": 37.7749, "longitude": -122.4194 }, "radius": 5000.0 } } }' \ -H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \ https://places.googleapis.com/v1/places:autocomplete
Tất cả kết quả trong các vùng được chỉ định đều nằm trong mảng suggestions
:
{ "suggestions": [ { "placePrediction": { "place": "places/ChIJ5YQQf1GHhYARPKG7WLIaOko", "placeId": "ChIJ5YQQf1GHhYARPKG7WLIaOko", "text": { "text": "Amoeba Music, Haight Street, San Francisco, CA, USA", "matches": [ { "endOffset": 6 } ] }, "structuredFormat": { "mainText": { "text": "Amoeba Music", "matches": [ { "endOffset": 6 } ] }, "secondaryText": { "text": "Haight Street, San Francisco, CA, USA" } }, "types": [ "home_goods_store", "establishment", "store", "point_of_interest", "electronics_store" ] } } ] }
Với locationBias
, vị trí được coi là thiên vị, nghĩa là kết quả xung quanh
vị trí được chỉ định có thể trả về, bao gồm cả kết quả nằm ngoài khu vực được chỉ định. Trong thời gian tới
ví dụ: bạn thay đổi yêu cầu sử dụng locationBias
:
curl -X POST -d '{ "input": "Amoeba", "locationBias": { "circle": { "center": { "latitude": 37.7749, "longitude": -122.4194 }, "radius": 5000.0 } } }' \ -H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \ https://places.googleapis.com/v1/places:autocomplete
Kết quả hiện chứa nhiều mục khác, bao gồm cả các kết quả nằm ngoài bán kính 5000 mét:
{ "suggestions": [ { "placePrediction": { "place": "places/ChIJ5YQQf1GHhYARPKG7WLIaOko", "placeId": "ChIJ5YQQf1GHhYARPKG7WLIaOko", "text": { "text": "Amoeba Music, Haight Street, San Francisco, CA, USA", "matches": [ { "endOffset": 6 } ] }, "structuredFormat": { "mainText": { "text": "Amoeba Music", "matches": [ { "endOffset": 6 } ] }, "secondaryText": { "text": "Haight Street, San Francisco, CA, USA" } }, "types": [ "electronics_store", "point_of_interest", "store", "establishment", "home_goods_store" ] } }, { "placePrediction": { "place": "places/ChIJr7uwwy58hYARBY-e7-QVwqw", "placeId": "ChIJr7uwwy58hYARBY-e7-QVwqw", "text": { "text": "Amoeba Music, Telegraph Avenue, Berkeley, CA, USA", "matches": [ { "endOffset": 6 } ] }, "structuredFormat": { "mainText": { "text": "Amoeba Music", "matches": [ { "endOffset": 6 } ] }, "secondaryText": { "text": "Telegraph Avenue, Berkeley, CA, USA" } }, "types": [ "electronics_store", "point_of_interest", "establishment", "home_goods_store", "store" ] } }, ... ] }
Sử dụng includePrimaryTypes
Sử dụng tham số includedPrimaryTypes
để chỉ định tối đa 5 giá trị loại từ
Bảng A,
Bảng B,
hoặc chỉ (regions)
hoặc chỉ (cities)
. Địa điểm phải phù hợp với một trong các địa điểm được chỉ định
loại chính cần đưa vào phản hồi.
Trong ví dụ sau, bạn chỉ định một chuỗi input
của
"Bóng đá" và sử dụng tham số includedPrimaryTypes
để giới hạn kết quả
cơ sở thuộc loại "sporting_goods_store"
:
curl -X POST -d '{ "input": "Soccer", "includedPrimaryTypes": ["sporting_goods_store"], "locationBias": { "circle": { "center": { "latitude": 37.7749, "longitude": -122.4194 }, "radius": 500.0 } } }' \ -H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \ https://places.googleapis.com/v1/places:autocomplete
Nếu bạn bỏ qua tham số includedPrimaryTypes
, thì kết quả có thể bao gồm
cơ sở thuộc loại mà bạn không muốn, chẳng hạn như "athletic_field"
.
Yêu cầu dự đoán truy vấn
Các dự đoán truy vấn không được trả về theo mặc định. Sử dụng includeQueryPredictions
để thêm thông tin dự đoán truy vấn vào phản hồi. Ví dụ:
curl -X POST -d '{ "input": "Amoeba", "includeQueryPredictions": true, "locationBias": { "circle": { "center": { "latitude": 37.7749, "longitude": -122.4194 }, "radius": 5000.0 } } }' \ -H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \ https://places.googleapis.com/v1/places:autocomplete
Mảng suggestions
hiện chứa cả dự đoán địa điểm và dự đoán truy vấn
như đã trình bày ở trên trong phần Giới thiệu về phản hồi. Mỗi cụm từ gợi ý truy vấn
bao gồm trường text
có chứa chuỗi tìm kiếm dạng văn bản được đề xuất. Bạn có thể tạo một
Tìm kiếm văn bản (Mới)
để biết thêm thông tin về bất kỳ nội dung dự đoán truy vấn nào được trả về.
Sử dụng nguồn gốc
Trong ví dụ này, hãy thêm origin
vào yêu cầu dưới dạng toạ độ theo vĩ độ và kinh độ.
Khi bạn đưa origin
vào, API này sẽ bao gồm trường distanceMeters
trong phần tử
phản hồi chứa khoảng cách theo đường thẳng từ origin
đến đích.
Ví dụ sau đặt điểm khởi hành là trung tâm của San Francisco:
curl -X POST -d '{ "input": "Amoeba", "origin": { "latitude": 37.7749, "longitude": -122.4194 }, "locationRestriction": { "circle": { "center": { "latitude": 37.7749, "longitude": -122.4194 }, "radius": 5000.0 } } }' \ -H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \ https://places.googleapis.com/v1/places:autocomplete
Phản hồi hiện bao gồm distanceMeters
:
{ "suggestions": [ { "placePrediction": { "place": "places/ChIJ5YQQf1GHhYARPKG7WLIaOko", "placeId": "ChIJ5YQQf1GHhYARPKG7WLIaOko", "text": { "text": "Amoeba Music, Haight Street, San Francisco, CA, USA", "matches": [ { "endOffset": 6 } ] }, "structuredFormat": { "mainText": { "text": "Amoeba Music", "matches": [ { "endOffset": 6 } ] }, "secondaryText": { "text": "Haight Street, San Francisco, CA, USA" } }, "types": [ "home_goods_store", "establishment", "point_of_interest", "store", "electronics_store" ], "distanceMeters": 3012 } } ] }
Hãy dùng thử!
API Explorer cho phép bạn thực hiện các yêu cầu mẫu để mà bạn có thể làm quen với API và các tuỳ chọn API.
- Chọn biểu tượng API,
ở bên phải của trang.
- (Không bắt buộc) Mở rộng tuỳ chọn Hiển thị các tham số chuẩn rồi đặt
tham số
fields
vào mặt nạ trường. - Chỉnh sửa Nội dung yêu cầu (không bắt buộc).
- Chọn nút Thực thi. Trong cửa sổ bật lên, hãy chọn tài khoản mà bạn muốn dùng để gửi yêu cầu.
Trong bảng điều khiển API Explorer, hãy chọn biểu tượng mở rộng
, để mở rộng cửa sổ API Explorer.