TỔNG QUAN
Tính năng Autocomplete (gợi ý địa điểm theo từ khóa) không chỉ giúp rút ngắn thời gian nhập liệu mà còn giảm thiểu lỗi sai khi nhập địa chỉ, đặc biệt trong các hệ thống yêu cầu định vị chính xác như: giao hàng, gọi xe, tìm kiếm bất động sản, hoặc khai báo hành chính.
Với Autocomplete API, Goong cho phép các nhà phát triển dễ dàng tích hợp tính năng gợi ý địa điểm theo thời gian thực vào website hoặc ứng dụng. Chỉ cần người dùng bắt đầu gõ từ khóa, API sẽ tự động trả về danh sách địa điểm phù hợp – từ địa chỉ cụ thể, tên đường, đến các doanh nghiệp hay địa danh phổ biến – có thể giới hạn theo khu vực địa lý nếu cần.
Đặc biệt, trong bối cảnh cả nước đang thực hiện điều chỉnh địa giới hành chính theo các nghị quyết mới nhất của Trung ương, Goong đã kịp thời cập nhật dữ liệu bản đồ để đảm bảo mọi kết quả gợi ý luôn phản ánh đúng tên tỉnh, huyện, xã mới sau sáp nhập. Điều này giúp các nền tảng số luôn đồng bộ với hệ thống địa lý – hành chính hiện hành, hạn chế sai sót và tăng độ tin cậy.
Trong bài viết này, bạn sẽ được hướng dẫn chi tiết cách tích hợp tính năng Autocomplete vào hệ thống của mình – từ cấu hình cơ bản, xử lý kết quả trả về, đến các tùy chọn nâng cao giúp kiểm soát phạm vi tìm kiếm và hiển thị gợi ý theo ngữ cảnh ứng dụng.
CÁCH THỨC TÍCH HỢP AUTOCOMPLETE
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: https://rsapi.goong.io/v2/place/autocomplete
Phương thức: GET
Các tham số trong request truyền vào:
curl 'https://rsapi.goong.io/v2/place/autocomplete?input=aqua&location=10.700920276971795%2C106.73296613898738&limit=5&radius=10&administrative_unit=new&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à 05. | 5 |
| 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 |
| administrative_unit | Đây là tham số không bắt buộc. Để mặc định hoặc administrative_unit= new sẽ trả về kết quả là đơn vị hành chính mới sau khi đã sáp nhập. Thêm tham số administrative_unit=old sẽ trả về kết quả đơn vị hành chính cũ trước khi sáp nhập. | new |
Các tham số respose trả về
| Tham số | Mô tả | Ví dụ |
| predictions | Mảng chứa các gợi ý địa điểm trả về từ truy vấn của người dùng | Gồm 5 địa chỉ tại đường Nguyễn Trãi, Sao Đỏ, Chí Linh, Hải Phòng |
| description | Chuỗi mô tả đầy đủ địa chỉ | “91 Nguyễn Trãi, Sao Đỏ, Chí Linh, Hải Phòng” |
| matched_substrings | Các đoạn chuỗi trong kết quả khớp với từ khóa người dùng nhập vào (dùng để highlight) | [] (trống – tức không có phần nào cần highlight) |
| place_id | ID định danh duy nhất của địa điểm (dùng để truy xuất chi tiết từ Place Detail API hoặc Geocode API) | “Hobn8WqBW6r…/5PUgWrMDrSI/xlqDBt5XA==.ZXhwYW5kMA==” |
| reference | Chuỗi tham chiếu địa điểm – tương tự như place_id, phục vụ backend hoặc caching | “o/QzXNc_eBK…/t/AIYwRnQ==.ZXhwYW5kMA==” |
| structured_formatting | Định dạng chia nhỏ description gồm main_text và secondary_text để hiển thị rõ ràng hơn | { “main_text”: “91 Nguyễn Trãi”, “secondary_text”: “Sao Đỏ, Chí Linh, Hải Phòng” } |
| main_text | Phần địa chỉ chính – dùng làm tiêu đề khi render UI | “91 Nguyễn Trãi” |
| secondary_text | Phần địa chỉ phụ – địa danh hành chính đi kèm để xác định vị trí rõ ràng hơn | “Sao Đỏ, Chí Linh, Hải Phòng” |
| terms | Mảng rỗng – trong một số hệ thống có thể chứa các thành phần địa chỉ dạng “value” và “offset” | |
| has_children | Boolean cho biết địa điểm có chứa các địa điểm con không (ví dụ toà nhà có các văn phòng bên trong) | FALSE |
| display_type | Loại hiển thị – thường dùng để frontend xác định cách nhóm/kết quả | “expand0” |
| score | Điểm đánh giá độ phù hợp của kết quả (càng cao thì càng chính xác) | 633.7587 (cao nhất ở entry đầu tiên, giảm dần về sau) |
| plus_code.compound_code | Mã vị trí kết hợp địa phương, thường để biểu diễn location rút gọn | “+6DW1G Sao Đỏ, Chí Linh, Hải Phòng” |
| plus_code.global_code | Mã định vị toàn cầu theo chuẩn OLC (Open Location Code) | “LOC1+6DW1G” |
| status | Trạng thái phản hồi – “OK” nghĩa là thành công | “OK” |
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).
Mục lục
