Endpoints
| Method | Endpoint | Mô tả | Phân trang |
|---|
| GET | /api/v1/total | Thống kê tổng quan (số bộ, tỉnh, xã/phường, trường) | — |
| GET | /api/v1/ministries | Danh sách 17 bộ/ban/ngành | page, limit |
| GET | /api/v1/province/wards/ | Danh sách 34 tỉnh/thành kèm số xã/phường | page, limit |
| GET | /api/v1/province/wards/{id} | Xã/phường của một tỉnh — {id} là mã tỉnh, tên tiếng Việt hoặc tên tiếng Anh (không cần dấu) | page, limit |
| GET | /api/v1/search?q=... | Tìm kiếm trên 4 bộ dữ liệu, không phân biệt dấu tiếng Việt | page, limit |
| GET | /api/v1/all | Toàn bộ dữ liệu (~500KB) | — |
Tham số truy vấn
| Tham số | Áp dụng cho | Mặc định | Mô tả |
|---|
q | search | — | Từ khoá (bắt buộc), tự động bỏ dấu: "ha noi" khớp "Hà Nội" |
type | search | tất cả | Giới hạn loại kết quả: ministry | province | ward | school |
page | các endpoint có phân trang | 1 | Số trang, phải ≥ 1 |
limit | các endpoint có phân trang | 100 (search: 200) | Số kết quả mỗi trang, tối đa 500 |
Định dạng phân trang
{
"pagination": {
"page": 2,
"limit": 20,
"total": 126,
"total_pages": 7,
"has_prev": true,
"has_next": true
},
"data": [ ... ]
}
Mã trạng thái
| Mã | Ý nghĩa |
|---|
| 200 | Thành công |
| 400 | Tham số không hợp lệ (thiếu q, page < 1, limit vượt 500, type sai...) |
| 404 | Không tìm thấy tỉnh/thành phố với {id} đã cho |
| 405 | Phương thức không phải GET |
| 500 | Lỗi xử lý phía server |
Ví dụ
curl "https://your-project.pages.dev/api/v1/province/wards/12?page=2&limit=20"
curl "https://your-project.pages.dev/api/v1/search?q=ha+noi&type=ward&page=1&limit=50"
curl "https://your-project.pages.dev/api/v1/ministries?page=1&limit=10"