TỔNG QUAN
API autocomplete trả về các cụm từ gợi ý để phản hồi một yêu cầu chỉ định một chuỗi tìm kiếm dạng văn bản và các giới hạn địa lý không bắt buộc. Dịch vụ này có thể được dùng để cung cấp chức năng tự động hoàn thành cho nội dung tìm kiếm theo địa lý dựa trên văn bản bằng cách trả về các địa điểm (ví dụ: doanh nghiệp, địa chỉ và địa điểm yêu thích) khi người dùng nhập thông tin.
Cho phép các nhà phát triển tích hợp chức năng tự động hoàn thành vào ứng dụng của họ. Khi người dùng nhập thông tin, API này sẽ đề xuất các kết quả tiềm năng dựa trên thông tin đã nhập. Điều này giúp người dùng tìm kiếm và lựa chọn được địa điểm chính xác từ một tập hợp các gợi ý một cách thuận tiện và nhanh chóng.
Bạn có thể thêm tính năng tự động hoàn thành vào ứng dụng hoặc trang web của mình bằng cách sử dụng tiện ích tự động hoàn thành địa điểm từ việc tạo một trường nhập dữ liệu văn bản.
Thêm một trường nhập văn bản vào trang web 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.
Điều kiện bắt buộc:
Để sử dụng tính năng hoàn thành địa điểm, 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 tự động hoàn thành địa điểm được thiết kế tối ưu nhất cho người dùng theo các cách như sau:
- Giao diện người dùng của tiện ích Tự động hoàn thànhđược thiết kế phù hợp với đặc đặ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ả…), cho phần giữ chỗ nhập văn bản, biểu trưng của danh sách cụm từ gợi ý và thông tin dự đoán về địa điểm.
- Tiện ích Tự động hoàn thành sẽ trả về lớp địa điểm mới để đơn giản hoá việc xử lý đối tượng được trả về.
- Hỗ trợ ngày càng tối ưu hơn cho các thiết bị màn hình nhỏ, thiết bị di động
- 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 TÍNH NĂNG TỰ ĐỘNG HOÀN THÀNH
Bạn có thể tích hợp tiện ích tự động hoàn thành 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:
Để thêm tiện ích Tự động hoàn thành vào một trang web, bạn có thể:
Bắt đầu
Trước khi bắt đầu sử dụng dịch vụ API autocomplete của Goong, bạn cần đảm bảo rằng đã có API key của mình.
Input (đầu vào):
“https://rsapi.goong.io/Place/AutoComplete?api_key={YOUR_API_KEY}&location=latlon&input=text”
| 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 |
| sessiontoken | Mã thông báo của bạn cho nhóm nhiều Autocomplete requests trong 1 session. Chúng tôi khuyến nghị nên sử dụng version 4 UUID cho các mã thông báo trong 1 session. (Tùy chọn) | a68dfa01-a5aa-47d1-aaa7-a3184896b283 |
| 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ề respone (Kết quả trả ra)
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 | Danh sách các địa điểm gợi ý phù hợp với chuỗi nhập của người dùng | |
| description | địa điểm được trả về từ các tìm kiếm hoặc gợi ý địa điể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. | |
| place_id | ||
| reference | là một chuỗi ký tự đại diện cho một địa điểm duy nhất trên bản đồ. | |
| structured_formatting | chứa thông tin được biến định dạng của địa điểm, 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ê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 | Chứa các từ khóa mô tả địa điểm hoặc điều kiện liên quan đến địa điểm. | |
| has_children | thông tin về các địa điểm con | |
| 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 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 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. Đặt các tuỳ chọn Tự động hoàn thành về địa điểm để đưa ra thông tin gợi ý phù hợp hơn bằng cách hạn chế hoặc xu hướng kết quả.
Việc hạn chế kết quả sẽ khiến tiện ích Tự động hoàn thành bỏ qua mọi 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ả ở ranh giới bản đồ. Kết quả xu hướng giúp tiện ích Tự động hoàn thành hiển thị kết quả trong khu vực được chỉ định, nhưng một số kết quả phù hợp có thể nằm ngoài khu vực đó.
Hạn chế tìm kiếm địa điểm theo bán kính
Giới hạn tìm kiếm trong phạm vi bản đồ
Gợi ý tìm kiếm theo địa điểm ưu tiên