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ã
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).
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ì rơi về bộ legacy |
prov_code | string | Có¹ | — | Mã tỉnh/thành phố, 2 ký tự. Chỉ có tác dụng ở bộ sau sáp nhập |
dist_code | string | Có¹ | — | Mã quận/huyện, 3 ký tự. Chỉ có tác dụng ở bộ legacy |
codes | string | Có¹ | — | Danh sách mã phường/xã phân tách bằng dấu phẩy (00004,00008) |
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 |
geom_level | string | Không | ward | auto, ward hoặc street — xem Mức chi tiết hình học |
page | integer | Không | 1 | Số trang. Chỉ dùng được cùng prov_code, hoặc dist_code ở bộ legacy |
size | integer | Không | 10 | Số 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ườ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ố chứa phường/xã, 2 ký tự |
ward_code | string | Có | Mã phường/xã, 5 ký tự |
ward_name | string | — | Tên ngắn gọn tiếng Việt (Ba Đình) |
ward_fname | string | Có | Tên đầy đủ tiếng Việt (Phường Ba Đình) |
ward_ne | string | — | Tên ngắn gọn tiếng Anh (Ba Dinh) |
ward_fne | string | Có | Tên đầy đủ tiếng Anh (Ba Dinh Ward) |
level | string | Có | Cấp hành chính (Phường, Xã, Đặc khu) |
region | string | — | Vùng địa lý (Vùng đồng bằng sông Hồng…) |
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)
| Mức | Mô tả |
|---|---|
ward (mặc định) | Chi tiết chuẩn theo ranh giới phường/xã |
street | Chi 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ã:
Lọc theo tỉnh/thành phố, có phân trang:
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
| 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 |
2. Chi tiết phường/xã
Trả về thông tin một phường/xã 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ả |
|---|---|---|---|
ward_code | string | Có | Mã phường/xã, 5 ký tự (ví dụ 00004) |
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 và cùng một mã có thể ra phường/xã khác, vẫn trả 200 |
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 | ward | auto, 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
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
| HTTP | Tình huống |
|---|---|
404 | Không tồn tại mã phường/xã |
422 | Tham số không hợp lệ |