Chuyển tới nội dung chính

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ố​

Loading...

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.

Chọn phiên bản dữ liệu

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ểuBắt buộcMặc địnhMô tả
data_versionstringKhônglegacyMã 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
codesstringKhông—Danh sách mã tỉnh/thành phố phân tách bằng dấu phẩy (01,79)
fieldsstringKhôngxem bên dướiDanh sách trường muốn lấy — xem Trường hỗ trợ
include_geomstringKhôngfalsetrue thêm geom kèm geomLevel; muốn center hoặc viewport thì phải liệt kê trong fields
geom_levelstringKhôngautoauto, 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ườngKiểuMặc địnhMô tả
idintegerCóMã nội bộ của bản ghi
prov_codestringCóMã tỉnh/thành phố, 2 ký tự
prov_namestring—Tên ngắn gọn tiếng Việt (Hà Nội)
prov_fnamestringCóTên đầy đủ tiếng Việt (Thành phố Hà Nội)
prov_nestring—Tên ngắn gọn tiếng Anh (Ha Noi)
prov_fnestringCóTên đầy đủ tiếng Anh (Ha Noi City)
levelstringCóCấp hành chính (Thành phố Trung ương, Tỉnh)
regionstring | 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
sortstringCó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
centerobject—Toạ độ trung tâm, dạng { lat, lng } theo WGS84 (EPSG:4326)
viewportobject—Khung nhìn, dạng { northeast, southwest }
geomobject—Ranh giới hành chính, GeoJSON geometry
geomLevelstring—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ứcMô tảTrường hợp dùng
countryKhái quát nhất, nhẹ nhấtHiển thị toàn quốc, zoom rất xa
provinceRanh giới cấp tỉnh, cân bằngXem vài tỉnh
wardChi tiết tới cấp phường/xãXem một tỉnh đơn lẻ
streetChi tiết cao nhất, nặng nhấtCầ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​

Loading API request...

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​

HTTPTình huống
400Giá trị tham số không hợp lệ
422Tham 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ố​

Loading...

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.

Chọn phiên bản dữ liệu

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ểuBắt buộcMô tả
province_codestringCóMã tỉnh/thành phố, 2 ký tự (ví dụ 01)

Tham số truy vấn

Tham sốKiểuBắt buộcMặc địnhMô tả
data_versionstringKhônglegacyMã 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
fieldsstringKhôngxem bên dướiDanh sách trường muốn lấy — xem Trường hỗ trợ
geom_levelstringKhôngautoauto, 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​

Loading API request...

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​

HTTPTình huống
404Không tồn tại mã tỉnh
422Tham số không hợp lệ, ví dụ fields sai tên trường