Bỏ qua

Autocomplete v4

Autocomplete cho tìm kiếm địa chỉ sau sáp nhập

autocomplete

Autocomplete API cho phép bạn gắn tính năng gợi ý địa chỉ vào ứng dụng của mình. API này giúp người dùng tìm và chọn nhanh một địa điểm trong kho dữ liệu bản đồ lớn, bằng cách gợi ý các kết quả khớp ngay khi họ đang gõ.

Playground

Bạn có thể thử Autocomplete v4 trên Live Map hoặc Playground.

Tích hợp AI Agent ✨ MỚI

Tải bộ tài liệu đã tối ưu cho AI agent: Search & Geocoding Agent Doc

URL

https://maps.vietmap.vn/api/autocomplete/v4?apikey={your-apikey}&text={text}&focus={lat,long}&display_type={display_type}

Method

GET

Chuyển từ v3 lên v4 (tóm tắt)

  • Endpoint đổi từ /api/autocomplete/v3 sang /api/autocomplete/v4; thêm display_type để chọn định dạng trả về (1=mới, 2=cũ, 3=tự động, ⅚=cả hai).
  • Phản hồi có thể dùng mô hình hành chính 2 cấp mới (phường/xã → tỉnh/thành); nếu chọn display_type=5 hoặc 6, v4 trả thêm data_old/data_new chứa định dạng còn lại.
  • Muốn giữ payload tương thích v3 thì gọi v4 với display_type=2.
  • API v4 dùng ref_id khác, xem Place v4 API để biết chi tiết — API này thay cho Place API cũ.
  • Chúng tôi khuyên dùng display_type=5 để quá trình chuyển đổi nhẹ nhàng nhất.

Xem tài liệu bản cũ: Autocomplete v3.

Tham số

Tham số Kiểu Bắt buộc Mô tả Ví dụ
apikey string có API key VIETMAP cấp cho tài khoản của bạn. Đăng ký tại đây
focus string không Tọa độ vị trí hiện tại của người dùng, dùng để ưu tiên kết quả ở gần. Định dạng lat,lng — vĩ độ trước. Bỏ trống thì kết quả chỉ xếp theo độ khớp chữ 10.762622,106.660172
text string có Nội dung người dùng gõ vào ô tìm kiếm. Nên gửi từ 2 ký tự trở lên 197 tran phu
display_type number không Định dạng kết quả trả về. Chi tiết xem Các giá trị display_type 1
cityId number không Lọc kết quả trong một tỉnh/thành. Tra ID tại kho dữ liệu hành chính 12
distId number không Lọc kết quả trong một quận/huyện. Tra ID tại kho dữ liệu hành chính 1292
wardId number không Lọc kết quả trong một phường/xã. Tra ID tại kho dữ liệu hành chính 984332
circle_center string không Tọa độ tâm của vùng tròn cần tìm, định dạng lat,lng. Đi kèm circle_radius 10.758867,106.675566
circle_radius number không Bán kính vùng tròn cần tìm, tính bằng mét. Chỉ có tác dụng khi đã gửi circle_center 200
cats string không Danh sách nhóm địa điểm (POI). Xem tại POI Categories 1002-1
layers string không Giới hạn loại dữ liệu trả về. Giá trị cho phép: POI, ADDRESS, VILLAGE, WARD, DIST, CITY, STREET. Bỏ trống thì tìm trong mọi loại POI
admin_new boolean không Chọn ranh giới hành chính mới (true) hay cũ (false). Chỉ có tác dụng khi lọc theo cityId/distId/wardId. Đặt false rồi lọc theo ID TP.HCM thì chỉ trả dữ liệu trong ranh giới cũ, không gồm Bình Dương và Vũng Tàu false

Các giá trị display_type

Giá trị Tên Mô tả
1 Trả định dạng mới Định dạng hành chính mới sau sáp nhập (2 cấp: phường/xã, tỉnh/thành).
2 Trả định dạng cũ Định dạng hành chính cũ (3 cấp: phường/xã, quận/huyện, tỉnh/thành).
3 Trả theo định dạng đầu vào API tự nhận diện kiểu người dùng nhập và trả về đúng kiểu đó.
5 Trả cả Mới & Cũ Kết quả chính theo định dạng mới, kèm bản theo đơn vị hành chính cũ trong data_old.
6 Trả cả Cũ & Mới Kết quả chính theo định dạng cũ, kèm bản theo đơn vị hành chính mới trong data_new.

Ví dụ

Đầu vào 

https://maps.vietmap.vn/api/autocomplete/v4?apikey={your-apikey}&text=197 tran phu&focus=10.75887508,106.67538868&display_type=6
Phản hồi

Cần thông tin chi tiết của địa điểm thì bạn dùng VIETMAP Place API

[
    {
        "ref_id": "geocode:RAkPcicmZ3d-NQhac2kADHYlbFAkBiEeAQAkCV0EXwdFbESDiMNbEzMK9ogWVwJMBRgNBwdRFFZWBlIdAQZcCVcFUB5TDwNbAlYDClJSBQIdVQk2QFhR",
        "distance": 0.06911172534949989,
        "address": "Phường 4,Quận 5,Thành Phố Hồ Chí Minh",
        "name": "197 Trần Phú",
        "display": "197 Trần Phú Phường 4,Quận 5,Thành Phố Hồ Chí Minh",
        "boundaries": [
            {
                "type": 2,
                "id": 656652,
                "name": "4",
                "prefix": "Phường",
                "full_name": "Phường 4"
            },
            {
                "type": 1,
                "id": 1292,
                "name": "5",
                "prefix": "Quận",
                "full_name": "Quận 5"
            },
            {
                "type": 0,
                "id": 12,
                "name": "Hồ Chí Minh",
                "prefix": "Thành Phố",
                "full_name": "Thành Phố Hồ Chí Minh"
            }
        ],
        "categories": [],
        "entry_points": [],
        "data_new": {
            "ref_id": "geocode:RAkPcicmZ3d-NQhac2kADHYlbFAkBiEeAQAkCV0EXwdFbESDiMNbEzMK9ogWVwJMBRgNBwdRFFZWBlIdAQZcCVcFUB5TDwNbAlYDClJSBQIdVQkkU0FHUA",
            "distance": 0.06911172534949989,
            "address": "Phường Chợ Quán,Thành Phố Hồ Chí Minh",
            "name": "197 Trần Phú",
            "display": "197 Trần Phú Phường Chợ Quán,Thành Phố Hồ Chí Minh",
            "boundaries": [
                {
                    "type": 2,
                    "id": 18700,
                    "name": "Chợ Quán",
                    "prefix": "Phường",
                    "full_name": "Phường Chợ Quán"
                },
                {
                    "type": 0,
                    "id": 12,
                    "name": "Hồ Chí Minh",
                    "prefix": "Thành Phố",
                    "full_name": "Thành Phố Hồ Chí Minh"
                }
            ],
            "categories": [],
            "entry_points": [],
            "data_new": null,
            "data_old": null
        },
        "data_old": null
    }
]

[
    {
        "ref_id": "geocode:RAkPcicmZ3d-NQhac2kADHYlbFAkBiEeAQAkCV0EXwdFbESDiMNbEzMK9ogWVwJMBRgNBwdRFFZWBlIdAQZcCVcFUB5TDwNbAlYDClJSBQIdVQkkU0FHUA",
        "distance": 0.06911172534949989,
        "address": "Phường Chợ Quán,Thành Phố Hồ Chí Minh",
        "name": "197 Trần Phú",
        "display": "197 Trần Phú Phường Chợ Quán,Thành Phố Hồ Chí Minh",
        "boundaries": [
            {
                "type": 2,
                "id": 18700,
                "name": "Chợ Quán",
                "prefix": "Phường",
                "full_name": "Phường Chợ Quán"
            },
            {
                "type": 0,
                "id": 12,
                "name": "Hồ Chí Minh",
                "prefix": "Thành Phố",
                "full_name": "Thành Phố Hồ Chí Minh"
            }
        ],
        "categories": [],
        "entry_points": [],
        "data_new": null,
        "data_old": {
            "ref_id": "geocode:RAkPcicmZ3d-NQhac2kADHYlbFAkBiEeAQAkCV0EXwdFbESDiMNbEzMK9ogWVwJMBRgNBwdRFFZWBlIdAQZcCVcFUB5TDwNbAlYDClJSBQIdVQk2QFhR",
            "distance": 0.06911172534949989,
            "address": "Phường 4,Quận 5,Thành Phố Hồ Chí Minh",
            "name": "197 Trần Phú",
            "display": "197 Trần Phú Phường 4,Quận 5,Thành Phố Hồ Chí Minh",
            "boundaries": [
                {
                    "type": 2,
                    "id": 656652,
                    "name": "4",
                    "prefix": "Phường",
                    "full_name": "Phường 4"
                },
                {
                    "type": 1,
                    "id": 1292,
                    "name": "5",
                    "prefix": "Quận",
                    "full_name": "Quận 5"
                },
                {
                    "type": 0,
                    "id": 12,
                    "name": "Hồ Chí Minh",
                    "prefix": "Thành Phố",
                    "full_name": "Thành Phố Hồ Chí Minh"
                }
            ],
            "categories": [],
            "entry_points": [],
            "data_new": null,
            "data_old": null
        }
    }
]

[
    {
        "ref_id": "auto:RAkPcicmZ3d-NQhac2kADHYlbFAkBiEeAQAkCV0EXwdF_KakgoWOrg0FFWZfh4jFXA1kXfbZFlNRGFUYCAJXAF8BUQBVCAZUC18EA1VMAwUYXwJQBBQFBQVTHVFacANBQlU",
        "distance": 0.05455783214665687,
        "address": "Phường Chợ Quán,Thành Phố Hồ Chí Minh",
        "name": "197 Đường Trần Phú",
        "display": "197 Đường Trần Phú Phường Chợ Quán,Thành Phố Hồ Chí Minh",
        "boundaries": [
            {
                "type": 2,
                "id": 18700,
                "name": "Chợ Quán",
                "prefix": "Phường",
                "full_name": "Phường Chợ Quán"
            },
            {
                "type": 0,
                "id": 12,
                "name": "Hồ Chí Minh",
                "prefix": "Thành Phố",
                "full_name": "Thành Phố Hồ Chí Minh"
            }
        ],
        "categories": [],
        "entry_points": []
    }
]

[
    {
        "ref_id": "auto:RAkPcicmZ3d-NQhac2kADHYlbFAkBiEeAQAkCV0EXwdF_KakgoWOrg0FFWZfh4jFXA1kXfbZFlNRGFUYCAJXAF8BUQBVCAZUC18EA1VMAwUYXwJQBBQFBQVTHVFaYhBYVA",
        "distance": 0.05455783214665687,
        "address": "Phường 4,Quận 5,Thành Phố Hồ Chí Minh",
        "name": "197 Đường Trần Phú",
        "display": "197 Đường Trần Phú Phường 4,Quận 5,Thành Phố Hồ Chí Minh",
        "boundaries": [
            {
                "type": 2,
                "id": 656652,
                "name": "4",
                "prefix": "Phường",
                "full_name": "Phường 4"
            },
            {
                "type": 1,
                "id": 1292,
                "name": "5",
                "prefix": "Quận",
                "full_name": "Quận 5"
            },
            {
                "type": 0,
                "id": 12,
                "name": "Hồ Chí Minh",
                "prefix": "Thành Phố",
                "full_name": "Thành Phố Hồ Chí Minh"
            }
        ],
        "categories": [],
        "entry_points": []
    }
]

[
    {
        "ref_id": "auto:RAkPcicmZ3d-NQhac2kADHYlbFAkBiEeAQAkCV0EXwdF_KakgoWOrg0FFWZfh4jFXA1kXfbZFlNRGFUYCAJXAF8BUQBVCAZUC18EA1VMAwUYXwJQBBQFBQVTHVFacANBQlU",
        "distance": 0.05455783214665687,
        "address": "Phường Chợ Quán,Thành Phố Hồ Chí Minh",
        "name": "197 Đường Trần Phú",
        "display": "197 Đường Trần Phú Phường Chợ Quán,Thành Phố Hồ Chí Minh",
        "boundaries": [
            {
                "type": 2,
                "id": 18700,
                "name": "Chợ Quán",
                "prefix": "Phường",
                "full_name": "Phường Chợ Quán"
            },
            {
                "type": 0,
                "id": 12,
                "name": "Hồ Chí Minh",
                "prefix": "Thành Phố",
                "full_name": "Thành Phố Hồ Chí Minh"
            }
        ],
        "categories": [],
        "entry_points": []
    }
]

Mô tả phản hồi

Autocomplete API trả về một list chứa tối đa 10 địa điểm.

Trường Kiểu Mô tả
ref_id string Mã tham chiếu của địa điểm (POI), có thể kèm tiền tố ứng với display_type. Dùng VIETMAP Place API để lấy thông tin chi tiết.
distance number Khoảng cách, tính bằng km
address string Địa chỉ đầy đủ gồm đường, phường/xã, quận/huyện và tỉnh/thành.
name string Tên địa điểm (POI)
display string Tên hiển thị, chứa đầy đủ thông tin địa chỉ của địa điểm
boundaries array Mảng các đơn vị hành chính của địa chỉ, xếp từ cấp nhỏ đến cấp lớn (phường/xã, quận/huyện, tỉnh/thành).
categories array Mảng các nhóm mà địa điểm thuộc về
entry_points array Mảng các lối vào của địa điểm. Chỉ có ở một số địa điểm đặc biệt như sân bay, khách sạn...
data_old object hoặc null Bản định dạng cũ của kết quả này (khi display_type có yêu cầu), còn lại là null.
data_new object hoặc null Bản định dạng mới của kết quả này (khi display_type có yêu cầu), còn lại là null.

Với mảng boundaries:

Trường con Kiểu Mô tả
type int Cấp hành chính (0 = tỉnh/thành, 1 = quận/huyện, 2 = phường/xã)
id int Mã định danh của đơn vị hành chính
name string Tên đơn vị hành chính, chưa kèm tiền tố
prefix string Tiền tố cấp hành chính. Ví dụ: Phường, Quận, Thành Phố
full_name string Tên đầy đủ gồm cả tiền tố. Ví dụ: Phường 9

Với mảng entry_points:

Trường con Kiểu Mô tả
ref_id string Mã tham chiếu của địa điểm (POI)
name string Tên địa điểm (POI)

Với object data_old và data_new:

Trường con Kiểu Mô tả
ref_id string Mã tham chiếu của bản kết quả này
distance number Khoảng cách, tính bằng km
address string Địa chỉ đầy đủ
name string Tên địa điểm
display string Chuỗi hiển thị chứa đầy đủ thông tin địa chỉ
boundaries array Cấu trúc giống mảng boundaries ở trên
categories array Mã nhóm địa điểm
entry_points array Lối vào của địa điểm (nếu có)

Cần thông tin chi tiết của lối vào thì bạn dùng VIETMAP Place v4 API

Kinh nghiệm dùng tốt nhất

1. Luôn gửi focus — vị trí hiện tại của người dùng

focus là tham số ảnh hưởng nhiều nhất tới chất lượng kết quả. Nó kéo thứ hạng về phía các địa điểm gần người dùng, nên gõ "Cà phê" ở TP.HCM sẽ không ra kết quả ngoài Hà Nội.

  • App di động: gửi tọa độ GPS mới nhất của máy.
  • Web: gửi tâm bản đồ hiện tại, hoặc dùng Geolocation API của trình duyệt.
  • Phương án dự phòng: không lấy được vị trí thì dùng tâm của tỉnh/thành mà bạn đoán người dùng đang ở.
focus=10.776655,106.700876   ← user's current lat,lng

Không có focus, kết quả chỉ xếp theo độ khớp chữ — hai địa điểm trùng tên ở hai tỉnh khác nhau sẽ ra thứ tự tùy ý.

2. Gửi text theo từng phím gõ (có debounce)

Gọi API mỗi khi ô nhập thay đổi, debounce 200–300 ms. Ngắn hơn thì phí transaction, dài hơn thì giao diện thấy ì.

  • Độ dài tối thiểu: 2 ký tự — một ký tự cho ra kết quả vừa nhiều vừa kém.
  • Hủy request đang chạy trước khi gửi request mới (web dùng AbortController, mobile dùng cancel token).

3. Dùng display_type=5 (mặc định nên chọn)

Kết quả chính là định dạng 2 cấp mới, còn định dạng 3 cấp cũ nằm trong data_old. Một lượt gọi có đủ cả hai kiểu địa chỉ, không phải gọi thêm lần nữa.

4. Chỉ gọi Place v4 khi người dùng chọn — đừng gọi cho mọi gợi ý

Mỗi lượt gọi Place v4 tính một transaction. Chỉ gọi một lần, sau khi người dùng bấm vào một kết quả cụ thể để lấy thông tin chi tiết. Đừng gọi cho từng dòng trong danh sách gợi ý.

5. Hiển thị display cho người dùng — ref_id chỉ dùng bên trong

display là chuỗi cho người đọc (ví dụ "197 Trần Phú Phường 4,Quận 5,Thành Phố Hồ Chí Minh"). Còn ref_id là chuỗi mã hóa — truyền nguyên xi sang Place v4.

6. An toàn hơn

Nếu được, hãy mã hóa ref_id ở phía server. Khi người dùng chọn một gợi ý, gửi ref_id đã mã hóa về server của bạn, giải mã ở đó rồi mới gọi Place API. Cách này giúp API của bạn tránh bị lạm dụng.

facebook
Tổng đài hỗ trợ
089.616.4567 facebook Chat Facebook zalo Chat Zalo