Provinces
Tỉnh/thành phố có ở cả ba phiên bản dữ liệu; trang này gồm hai endpoint — lấy danh sách và lấy chi tiết một tỉnh/thành phố theo mã.
1. Danh sách tỉnh/thành phố
Trả về danh sách tỉnh/thành phố. Không truyền codes thì trả về toàn bộ tỉnh/thành phố của phiên bản dữ liệu đang chọn.
Luôn truyền query parameter data_version hoặc header X-Data-Version trong mọi request. Xem
Data Versions.
Tham số
| Tham số | Kiểu | Bắt buộc | Mặc định | Mô tả |
|---|---|---|---|---|
data_version | string | Không | legacy | Mã phiên bản dữ liệu sau sáp nhập — xem Data Versions; không truyền thì trả về bộ legacy, tức 63 tỉnh/thành phố trước sáp nhập |
codes | string | Không | — | Danh sách mã tỉnh/thành phố phân tách bằng dấu phẩy (01,79) |
fields | string | Không | xem bên dưới | Danh sách trường muốn lấy — xem Trường hỗ trợ |
include_geom | string | Không | false | true thêm geom kèm geomLevel; muốn center hoặc viewport thì phải liệt kê trong fields |
geom_level | string | Không | auto | auto, country, province, ward, street — xem Mức chi tiết hình học |
Trường hỗ trợ
Cột Mặc định cho biết trường có được trả về khi không truyền fields hay không. Cột này áp cho
bộ dữ liệu sau sáp nhập; bộ legacy trả thêm region và không trả sort.
| Trường | Kiểu | Mặc định | Mô tả |
|---|---|---|---|
id | integer | Có | Mã nội bộ của bản ghi |
prov_code | string | Có | Mã tỉnh/thành phố, 2 ký tự |
prov_name | string | — | Tên ngắn gọn tiếng Việt (Hà Nội) |
prov_fname | string | Có | Tên đầy đủ tiếng Việt (Thành phố Hà Nội) |
prov_ne | string | — | Tên ngắn gọn tiếng Anh (Ha Noi) |
prov_fne | string | Có | Tên đầy đủ tiếng Anh (Ha Noi City) |
level | string | Có | Cấp hành chính (Thành phố Trung ương, Tỉnh) |
region | string | null | — | Vùng địa lý, ví dụ Đồng bằng sông Hồng. Chỉ legacy có giá trị; sau sáp nhập trả null |
sort | string | Có | Thứ tự hiển thị. Chỉ khi fields có sort, kết quả mới sắp xếp tăng dần theo trường này |
center | object | — | Toạ độ trung tâm, dạng { lat, lng } theo WGS84 (EPSG:4326) |
viewport | object | — | Khung nhìn, dạng { northeast, southwest } |
geom | object | — | Ranh giới hành chính, GeoJSON geometry |
geomLevel | string | — | Mức chi tiết hình học đã dùng, tự trả về khi kết quả có dữ liệu không gian |
Mức chi tiết hình học (geom_level)
Điều khiển độ khái quát của dữ liệu không gian — đánh đổi giữa dung lượng và độ chính xác.
Mặc định là auto, server tự chọn mức phù hợp.
| Mức | Mô tả | Trường hợp dùng |
|---|---|---|
country | Khái quát nhất, nhẹ nhất | Hiển thị toàn quốc, zoom rất xa |
province | Ranh giới cấp tỉnh, cân bằng | Xem vài tỉnh |
ward | Chi tiết tới cấp phường/xã | Xem một tỉnh đơn lẻ |
street | Chi tiết cao nhất, nặng nhất | Cần độ chính xác cao ở mức rất gần |
geom_level=street chỉ hỗ trợ khi truyền đúng một mã tỉnh.
Yêu cầu mẫu
Phản hồi
{
"status": "OK",
"data": [
{
"id": 14,
"prov_code": "79",
"prov_fname": "Thành phố Hồ Chí Minh",
"prov_fne": "Ho Chi Minh City",
"level": "Thành phố Trung ương",
"sort": "1"
},
{
"id": 15,
"prov_code": "01",
"prov_fname": "Thành phố Hà Nội",
"prov_fne": "Ha Noi City",
"level": "Thành phố Trung ương",
"sort": "2"
}
],
"meta": { "data_version": "2025-07.r2" },
"licence": "© GTEL Maps"
}
Lỗi thường gặp
| HTTP | Tình huống |
|---|---|
400 | Giá trị tham số không hợp lệ |
422 | Tham số không hợp lệ hoặc không khớp dữ liệu — mã sai độ dài, fields sai tên trường, codes không tìm ra tỉnh nào |
2. Chi tiết tỉnh/thành phố
Trả về thông tin một tỉnh/thành phố theo mã, mặc định kèm đầy đủ dữ liệu không gian.
Luôn truyền query parameter data_version hoặc header X-Data-Version trong mọi request. Xem
Data Versions.
Tham số
Tham số đường dẫn
| Tham số | Kiểu | Bắt buộc | Mô tả |
|---|---|---|---|
province_code | string | Có | Mã tỉnh/thành phố, 2 ký tự (ví dụ 01) |
Tham số truy vấn
| Tham số | Kiểu | Bắt buộc | Mặc định | Mô tả |
|---|---|---|---|---|
data_version | string | Không | legacy | Mã phiên bản dữ liệu sau sáp nhập — xem Data Versions; không truyền thì tra cứu chạy trên bộ legacy, dữ liệu trước sáp nhập |
fields | string | Không | xem bên dưới | Danh sách trường muốn lấy — xem Trường hỗ trợ |
geom_level | string | Không | auto | auto, country, province, ward, street — xem Mức chi tiết hình học |
Trường hỗ trợ
Giống endpoint danh sách. Trường mặc định: id, prov_code, prov_fname, prov_fne, level,
center, viewport, geom, kèm geomLevel.
Yêu cầu mẫu
Phản hồi
{
"status": "OK",
"data": {
"prov_name": "Hà Nội",
"geomLevel": "province",
"center": { "lat": 20.998875592925128, "lng": 105.70037221622583 },
"viewport": {
"northeast": { "lat": 21.38539000000003, "lng": 105.29018100000008 },
"southwest": { "lat": 20.565271000000052, "lng": 106.02003400000007 }
}
},
"meta": { "data_version": "2025-07.r2" },
"licence": "© GTEL Maps"
}
Lỗi thường gặp
| HTTP | Tình huống |
|---|---|
404 | Không tồn tại mã tỉnh |
422 | Tham số không hợp lệ, ví dụ fields sai tên trường |