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

Wards

Trả về dữ liệu phường/xã — danh sách và chi tiết một phường/xã theo mã.

1. Danh sách phường/xã​

Loading...

Lấy danh sách phường/xã theo mã tỉnh/thành phố (prov_code) hoặc theo danh sách mã phường/xã (codes).

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ì rơi về bộ legacy
prov_codestringCó¹—Mã tỉnh/thành phố, 2 ký tự. Chỉ có tác dụng ở bộ sau sáp nhập
dist_codestringCó¹—Mã quận/huyện, 3 ký tự. Chỉ có tác dụng ở bộ legacy
codesstringCó¹—Danh sách mã phường/xã phân tách bằng dấu phẩy (00004,00008)
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
geom_levelstringKhôngwardauto, ward hoặc street — xem Mức chi tiết hình học
pageintegerKhông1Số trang. Chỉ dùng được cùng prov_code, hoặc dist_code ở bộ legacy
sizeintegerKhông10Số bản ghi mỗi trang, tối đa 50. Chỉ dùng được cùng prov_code, hoặc dist_code ở bộ legacy

¹ Bắt buộc một trong hai, và cặp này đổi theo bộ dữ liệu: bộ sau sáp nhập dùng prov_code hoặc codes, bộ legacy dùng dist_code hoặc codes. Không được truyền cả hai, cũng không được thiếu cả hai.

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 dist_code và region.

TrườngKiểuMặc địnhMô tả
idintegerCóMã nội bộ của bản ghi
prov_codestringCóMã tỉnh/thành phố chứa phường/xã, 2 ký tự
ward_codestringCóMã phường/xã, 5 ký tự
ward_namestring—Tên ngắn gọn tiếng Việt (Ba Đình)
ward_fnamestringCóTên đầy đủ tiếng Việt (Phường Ba Đình)
ward_nestring—Tên ngắn gọn tiếng Anh (Ba Dinh)
ward_fnestringCóTên đầy đủ tiếng Anh (Ba Dinh Ward)
levelstringCóCấp hành chính (Phường, Xã, Đặc khu)
regionstring—Vùng địa lý (Vùng đồng bằng sông Hồng…)
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)​

MứcMô tả
ward (mặc định)Chi tiết chuẩn theo ranh giới phường/xã
streetChi tiết cao hơn, hình học sát thực tế hơn, dung lượng nặng hơn
autoĐược quy về ward

Endpoint này không nhận country hoặc province.

Yêu cầu mẫu​

Lọc theo danh sách mã phường/xã:

Loading API request...

Lọc theo tỉnh/thành phố, có phân trang:

Loading API request...

Phản hồi​

{
"data": [
{
"id": 1,
"prov_code": "01",
"ward_code": "00004",
"ward_fname": "Phường Ba Đình",
"ward_fne": "Ba Dinh Ward",
"level": "Phường"
},
{
"id": 2,
"prov_code": "01",
"ward_code": "00008",
"ward_fname": "Phường Ngọc Hà",
"ward_fne": "Ngoc Ha Ward",
"level": "Phường"
}
],
"meta": {
"pagination": { "total": 126, "currentPage": 1, "pageSize": 3, "totalPages": 42 },
"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

2. Chi tiết phường/xã​

Loading...

Trả về thông tin một phường/xã 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ả
ward_codestringCóMã phường/xã, 5 ký tự (ví dụ 00004)

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 và cùng một mã có thể ra phường/xã khác, vẫn trả 200
fieldsstringKhôngxem bên dướiDanh sách trường muốn lấy — xem Trường hỗ trợ
geom_levelstringKhôngwardauto, ward hoặc 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: prov_code, ward_code, ward_fname, ward_fne, level, center, viewport, geom, kèm geomLevel.

Yêu cầu mẫu​

Loading API request...

Phản hồi​

{
"status": "OK",
"data": {
"ward_code": "00004",
"ward_fname": "Phường Ba Đình",
"ward_fne": "Ba Dinh Ward",
"level": "Phường",
"center": { "lat": 21.038550026517743, "lng": 105.83804327748028 },
"geomLevel": "ward"
},
"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ã phường/xã
422Tham số không hợp lệ