TỔNG QUAN
Autocomplete API là dịch vụ tự động gợi ý tìm kiếm nhanh địa chỉ, địa điểm dựa trên từ khóa người dùng nhập giúp dễ dàng chọn lựa và chọn đúng kết quả cần tìm kiếm. Khi người dùng nhập từ khóa, dịch vụ sẽ trả về danh sách gợi ý phù hợp, có thể kèm theo giới hạn địa lý nếu cần. Dịch vụ này hỗ trợ hiển thị các gợi ý như tên doanh nghiệp, địa chỉ hoặc các địa điểm yêu thích… dựa trên vị trí địa lý liên quan đến nội dung tìm kiếm.
Goong cho phép các nhà phát triển tích hợp tính năng Autocomplete vào nền tảng hoặc ứng dụng của họ. Khi người dùng nhập thông tin, API sẽ tự động đề xuất các kết quả tiềm năng dựa trên dữ liệu đã nhập. Điều này giúp người dùng dễ dàng và nhanh chóng tìm kiếm, chọn lựa địa điểm chính xác từ danh sách gợi ý đưa ra.
Bạn có thể thêm tính năng Autocomplete vào ứng dụng hoặc trang web của mình bằng cách sử dụng tiện ích Autocomplete địa điểm từ việc tạo một trường nhập dữ liệu văn bản.
Khi người dùng nhập văn bản, tính năng Autocomplete sẽ trả về các cụm từ gợi ý địa điểm dưới dạng một danh sách chọn. 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ề và ứng dụng của bạn có thể truy xuất thông tin địa điểm này.
Điều kiện bắt buộc
Để sử dụng Autocomplete API, bạn phải có tài khoản đã được kích hoạt và có API key để bắt đầu tích hợp.
Các tính năng hỗ trợ
Tính năng Autocomplete được thiết kế tối ưu nhất cho người dùng theo các cách như sau:
- Được thiết kế phù hợp với đặc trưng khu vực người dùng Việt Nam, bao gồm cả ngôn ngữ vùng miền, chữ viết tắt, viết sai chính tả…
- Hiệu suất ngày càng được cải thiện, độ chính xác cao và dữ liệu gợi ý chi tiết đến tận các vùng ngoại ô, rìa thành phố, vùng nông thôn và các cột sân bay, cổng, sảnh trung tâm thương mại….
CÁCH THỨC TÍCH HỢP AUTOCOMPLETE
Bạn có thể tích hợp Autocomplete API vào ứng dụng/trang web của bạn trên cả nền bản đồ của Goong hoặc các nền bản đồ khác.
Cách thêm
Trước khi bắt đầu sử dụng dịch vụ Autocomplete API của Goong, bạn cần đảm bảo rằng đã có API Key của mình.
Bạn có thể tham khảo cách đăng ký tài khoản và tạo key chi tiết tại đây.
URL: /place/autocomplete
Phương thức: GET
Ví dụ về request:
curl 'https://rsapi.goong.io/place/autocomplete?input=aqua&location=10.700920276971795%2C%20106.73296613898738&limit=10&radius=10&api_key={YOUR_API_KEY}'
Tham số |
Mô tả |
Ví dụ |
input |
Từ khóa tìm kiếm (bắt buộc). |
ho hoan kiem |
location |
Tọa độ tìm kiếm ưu tiên. | 20.981971,105.864323 |
limit |
Giới hạn số lượng kết quả trả ra, mặc định là 10. |
20 |
radius |
Giới hạn tìm kiếm trong phạm vi bán kính từ vị trí đã chỉ định (đơn vị km). Mặc định là 50. |
2000 |
more_compound | Boolean. Nếu là true, Autocomplete sẽ trả về các trường thông tin: quận, xã, tỉnh. Mặc định là false. |
true |
Ví dụ về response:
application/json { "predictions": [ { "description": "91 Trung Kính, Trung Hòa, Cầu Giấy, Hà Nội", "matched_substrings": [], "place_id": "Hobn8WqBW6rsKtKq2PDrVKp4BJNRtiILxTQbB__muXgRB3v8GRDTfkp_6lc4cbLw/5PUgWrMDrSI/xlqDBt5XA==.ZXhwYW5kMA==", "reference": "o/QzXNc_eBKsOWX6kdbOcABtO4zUQz0lzdK1jpi0R__J2vFKeRAM2VSYo38AfaShP/7qpUhrwc0l/t/AIYwRnQ==.ZXhwYW5kMA==", "structured_formatting": { "main_text": "91 Trung Kính", "secondary_text": "Trung Hòa, Cầu Giấy, Hà Nội" }, "terms": [], "has_children": false, "display_type": "expand0", "score": 633.7587, "plus_code": { "compound_code": "+6DW1G Trung Hòa, Cầu Giấy, Hà Nội", "global_code": "LOC1+6DW1G" } }, { "description": "43/91 Trung Kính, Trung Hòa, Cầu Giấy, Hà Nội", "matched_substrings": [], "place_id": "ytdKslLHBd1_mSnLu_bQHGu1yZyLeBt9haGgyFDN1EIOy7I9uEQyTmRkyNZL3BRpT_Knj31YK/Irv3KkEIIZqw==.ZXhwYW5kMA==", "reference": "nP7fBjweFzWzkU8gq/ki_xEAF3fpVoZ3aQcfXx4ZRHX7QaQPNBPpNToMKx1KZw09gWUhpnSdXJSLowB4qFlCMg==.ZXhwYW5kMA==","structured_formatting": { "main_text": "43/91 Trung Kính", "secondary_text": "Trung Hòa, Cầu Giấy, Hà Nội" }, "terms": [], "has_children": false, "display_type": "expand0", "score": 597.5509, "plus_code": { "compound_code": "+63G73 Trung Hòa, Cầu Giấy, Hà Nội", "global_code": "LOC1+63G73" } }, { "description": "95 Trung Kính, Trung Hòa, Cầu Giấy, Hà Nội", "matched_substrings": [], "place_id": "mUuwMwTPf5/1WFznDr94rtLvQffNhj1NzWQqDJqgsdUfCqTZdUcHTTav64BxPOC6dSdgZ9WUmwARwQlhmYonvA==.ZXhwYW5kMA==", "reference": "lPHbKnLx64d2Ikp35RrFcdRphjayJn2rjapjNhjPuBmPxB9GzirgM6NT0OH65gG2Mf4qGswZXQ8d6U4XBfltjQ==.ZXhwYW5kMA==", "structured_formatting": { "main_text": "95 Trung Kính", "secondary_text": "Trung Hòa, Cầu Giấy, Hà Nội" }, "terms": [], "has_children": false, "display_type": "expand0", "score": 358.45456, "plus_code": { "compound_code": "+6DW1M Trung Hòa, Cầu Giấy, Hà Nội", "global_code": "LOC1+6DW1M" } }, { "description": "93 Trung Kính, Trung Hòa, Cầu Giấy, Hà Nội", "matched_substrings": [], "place_id": "xFchTd18UNmq7/rWipBrI6LtqEcDdReZ8cGV3mxeK4yxmmL7hZat/i8cLBdGhdaeNYFQLk4H5AuP2ntIHfS7EQ==.ZXhwYW5kMA==", "reference": "dMG3Lmo6Rux8NsEd9lwoDGUOH22aZbMdzDiMy1RhS73mM/uA0rZsX2M0y0Wm990nx4PGw1jd54YkUeqLzySwaQ==.ZXhwYW5kMA==", "structured_formatting": { "main_text": "93 Trung Kính", "secondary_text": "Trung Hòa, Cầu Giấy, Hà Nội" }, "terms": [], "has_children": false, "display_type": "expand0", "score": 358.1594, "plus_code": { "compound_code": "+6DW1I Trung Hòa, Cầu Giấy, Hà Nội", "global_code": "LOC1+6DW1I" } }, { "description": "89 Trung Kính, Trung Hòa, Cầu Giấy, Hà Nội", "matched_substrings": [], "place_id": "OTzyxbl3DUoqV90GZW8D_2FCVMaEizDWVmAhzTc2d8KmYL/h2cPpfE97BmSabHzliRz3GSgjXWVRxI0bZMxqew==.ZXhwYW5kMA==", "reference": "7ESn5kbjYSJJfOstrAkpIRG26bEQi1atPuZKWKyymY9Q7raTcScHyAFeWejvoiu_aa46E/IYxOvOPsmkZgYfOQ==.ZXhwYW5kMA==", "structured_formatting": { "main_text": "89 Trung Kính", "secondary_text": "Trung Hòa, Cầu Giấy, Hà Nội" }, "terms": [], "has_children": false, "display_type": "expand0", "score": 358.14783, "plus_code": { "compound_code": "+6DW1E Trung Hòa, Cầu Giấy, Hà Nội", "global_code": "LOC1+6DW1E" } } ], "executed_time": 61, "executed_time_all": 63, "status": "OK" }
Tham số | Mô tả | Ví dụ |
predictions | Là một mảng, chứa danh sách các địa điểm gợi ý phù hợp với thông tin nhập của người dùng, mỗi phần tử chứa các thông tin như: description (tên đầy đủ), structured_formatting (cấu trúc tên bao gồm main_text (tên chính) và secondary_text (bổ sung)),… |
{
“description”: “91 Trung Kính, Phường Trung Hòa, Quận Cầu Giấy, Thành phố Hà Nội”,
“place_id”: “Hobn8WqBW6…“,
“reference”: “c1OLm3XsXS5rpI9Svkpg_k…….”,
“structured_formatting”:…
…
|
description | Địa điểm được trả về từ các tìm kiếm. | 95 Trung Kính, Trung Hòa, Cầu Giấy, Hà Nội |
matched_substrings | Các phần của chuỗi tìm kiếm ban đầu hoặc một phần của địa điểm đã được khớp với kết quả trả về từ API. |
{
“length”: 2,
“offset”: 0
}
|
place_id | Mã định danh duy nhất của một địa điểm trên hệ thống được cung cấp bởi Goong, dùng id này để lấy thông tin chi tiết của địa chỉ thông qua Place Detail API hoặc Geocode API. | Hobn8WqBW6rsKtKq2PDrVKp4BJNRtiILx
TQbB__muXgRB3v8GRDTfkp_6lc4cbLw/ 5PUgWrMDrSI/xlqDBt5XA==.ZXhwYW5kMA== |
reference | Là một chuỗi ký tự đại diện cho một địa điểm duy nhất trên bản đồ. |
7ESn5kbjYSJJfOstrAkpIRG26bEQi1atPuZKWK yymY9Q7raTcScHyAFeWejvoiu_ aa46E/IYxOvOPsmkZgYfOQ==.ZXhwYW5kMA== |
structured_formatting | Chứa thông tin định dạng của địa điểm (gồm thông tin chính và thông tin bổ sung), giúp bạn hiển thị các gợi ý địa điểm một cách dễ hiểu và dễ đọc. |
{
“main_text”: “Tòa nhà Blue Sea”,
“secondary_text”: “91 Trung Kính, Trung Hòa, Cầu Giấy, Hà Nội”
}
|
main_text | Tên chính của địa điểm được tìm thấy. | 91 Trung Kính |
secondary_text | Chứa các thông tin phụ về vị trí địa lý hoặc vùng khu vực mà địa điểm (main text) đó thuộc về. | Trung Hòa, Cầu Giấy, Hà Nội |
terms | Mảng chứa các object gồm từ khóa mô tả địa điểm đến địa điểm (value) và vị trí của từ đó (offset). |
{
“offset”: 15,
“value”: “Phường Trung Hòa”
}
|
has_children | Thông tin về các địa điểm con, nếu có giá trị là true, thì có thể dùng place_id này để gọi những địa điểm con (địa điểm nằm bên trong khu vục của địa điểm này, như sân bay có các địa điểm con là từng cửa vào) thông qua Child ID API. | true |
display_type | Cung cấp thông tin về loại hiển thị của địa điểm hoặc kết quả được trả về. | expand0 |
score | Thuộc tính thường được sử dụng để biểu thị mức độ liên quan hoặc độ chính xác của kết quả so với truy vấn của người dùng, giúp đánh giá và xếp hạng các kết quả tìm kiếm nhằm hiển thị những kết quả phù hợp nhất lên trên cùng. | 633.7587 |
compound_code | Mã địa phương đi kèm với mã khu vực, cho phép xác định chính xác một vị trí địa lý cụ thể. | +6DW1G Trung Hòa, Cầu Giấy, Hà Nội |
global_code | Mã toàn cầu có thể xác định vị trí chính xác ở mức độ thành phố hoặc khu vực. | LOC1+6DW1G |
GIỚI HẠN CÁC CỤM TỪ GỢI Ý CỦA AUTOCOMPLE
Theo mặc định, tính năng Autocomplete sẽ hiển thị tất cả các địa điểm có liên quan đến các cụm tìm kiếm dẫn đến nhiều địa điểm không chuẩn. Chính vì vậy, ta có thể đặt các tuỳ chọn gợi ý về địa điểm để đưa ra thông tin gợi ý phù hợp hơn bằng cách hạn chế kết quả tìm kiếm.
Việc hạn chế kết quả sẽ khiến tiện ích Autocomplete bỏ qua các kết quả nằm ngoài vùng hạn chế. Một phương pháp phổ biến là giới hạn kết quả trong một phạm vi bán kính nhất định. Kết quả của Autocomplete trả về sẽ chỉ hiển thị kết quả trong khu vực được chỉ định:
- Hạn chế tìm kiếm địa điểm theo bán kính (radius).
- Gợi ý tìm kiếm xung quanh địa chỉ cụ thể (location).
Ví dụ:
- Khi người dùng nhập input là “aqua” và không sử dụng thêm tính năng giới hạn:
curl 'https://rsapi.goong.io/place/autocomplete?input=aqua&api_key={YOUR_API_KEY}'
Kết quả trả về sẽ ưu tiên các kết quả gần Hà Nội:
{ "predictions": [ { "description": "Aqua, 30 Phan Bội Châu, Phường Cửa Nam, Quận Hoàn Kiếm, Thành phố Hà Nội", ... }, { "description": "AQUA Cafe, Phường Cổ Nhuế 1, Quận Bắc Từ Liêm, Thành phố Hà Nội", ... }, .... ], "execution_time": "", "status": "OK" }
- Khi người dùng nhập input tương tự “aqua” nhưng thêm địa chỉ (location ở Hồ Chí Minh, 10.700920276971795, 106.73296613898738) và bán kính (radius, 10):
curl 'https://rsapi.goong.io/place/autocomplete?input=aqua&api_key={YOUR_API_KEY}&location=10.700920276971795%2C%20106.73296613898738'
Kết quả trả về sẽ là các địa điểm ở Hồ Chí Minh:
{ "predictions": [ { "description": "Aqua Clinic, 67 Nguyễn Trãi, Phường Bến Thành, Quận 1, Thành phố Hồ Chí Minh", ... }, { "description": "Aqua Day spa, Khách sạn Sheraton Sài Gòn, 88 Đồng Khởi, Phường Bến Nghé, Quận 1, Thành phố Hồ Chí Minh", ... }, { "description": "Aqua sport wear, Chung cư Ngô Gia Tự, 28 Lô L Hòa Hảo, Phường 2, Quận 10, Thành phố Hồ Chí Minh", ... }, { "description": "Aqua Hotel, 25 Hẻm 207 Nguyễn Văn Đậu, Phường 11, Quận Bình Thạnh, Thành phố Hồ Chí Minh", ... }, { "description": "Aquarium Cafe, 1117 Phan Văn Trị, Phường 10, Quận Gò Vấp, Thành phố Hồ Chí Minh", ... } ],... }