Autocomplete v4

Autocomplete v4 — địa chỉ sau sáp nhập¶

Autocomplete API trả về tối đa 10 địa điểm gợi ý theo chuỗi người dùng đang gõ. Gọi mỗi khi ô nhập thay đổi (có debounce), hiển thị trường display cho người dùng; khi họ chọn một dòng, lấy ref_id gọi Place v4 để lấy tọa độ và chi tiết địa chỉ. Gửi kèm focus (vị trí người dùng) để kết quả gần được xếp trước.

Playground¶

Thử ngay trên Playground

Gọi thử Autocomplete v4 với dữ liệu thật, không cần viết code: Mở Playground · hoặc xem trên Live Map

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

Hoặc dùng thử bằng Postman.

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¶

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).
v4 trả theo mô hình hành chính 2 cấp (phường/xã → tỉnh/thành) với display_type=1, 5 và 3 (khi input là địa chỉ mới): boundaries không còn phần tử type=1 (quận/huyện). Với display_type=5/6, mỗi kết quả kèm thêm định dạng còn lại trong data_old/data_new; các giá trị khác, hai trường này là null.
Muốn giữ payload tương thích v3 thì gọi v4 với display_type=2.
ref_id của v4 không dùng được với Place API cũ. Lấy chi tiết bằng Place v4.
Khi migrate nên dùng display_type=5: kết quả chính theo định dạng mới, data_old giữ nguyên định dạng 3 cấp cũ — một request có đủ cả hai, code parse cũ vẫn chạy trong lúc chuyển.

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

Trả cả Cũ & Mới
display_type=6Trả cả Mới & Cũ
display_type=5Trả theo định dạng đầu vào
display_type=3Trả định dạng cũ
display_type=2Trả định dạng mới
display_type=1

[
    {
        "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¶

Response là một mảng JSON, tối đa 10 phần tử.

Trường	Kiểu	Mô tả
ref_id	string	ID địa điểm, luôn có tiền tố (`auto:` hoặc `geocode:`, tùy display_type). Truyền nguyên xi vào param `refid` của Place v4 để lấy tọa độ và chi tiết — không cắt tiền tố.
distance	number	Khoảng cách, tính bằng `km`
address	string	Phần hành chính của địa chỉ: phường/xã, quận/huyện (chỉ ở định dạng cũ), tỉnh/thành. Không gồm số nhà và tên đường — phần đó nằm ở `name`. Cần chuỗi đầy đủ thì dùng `display`.
name	string	Tên POI, hoặc số nhà + tên đường nếu kết quả là địa chỉ (ví dụ `197 Trần Phú`)
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 lối vào của địa điểm; `[]` nếu không có. Thường chỉ sân bay, khách sạn, trung tâm thương mại mới có.
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ó)

Response không có tọa độ. Cần lat/lng và chi tiết địa chỉ của một kết quả hoặc một lối vào thì truyền ref_id của nó sang Place v4.

Lưu ý khi tích hợp¶

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   ← lat,lng hiện tại của người dùng

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.