Endpoints
| Method | Endpoint | Mô tả | Phân trang |
|---|
| GET | /api/v1/total | Thống kê tổng quan | — |
| GET | /api/v1/ministries | Danh sách 17 bộ/ban/ngành | page, limit |
| GET | /api/v1/province/wards/ | 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 | page, limit |
| GET | /api/v1/search?q=… | Tìm kiếm toàn văn, không cần dấu | page, limit |
| GET | /api/v1/all | Toàn bộ dữ liệu JSON (~500KB) | — |
| GET | /api/v1/data | Tải data.json (rewrite 200 → file tĩnh) | — |
| GET | /api/v1/data.jsonl | Tải data.jsonl (NDJSON) | — |
| GET | /api/v1/openapi | OpenAPI 3.0 spec (rewrite 200 → file tĩnh) | — |
| GET | /docs | Swagger UI | — |
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 |
type | search | all | ministry | province | ward | school |
page | có phân trang | 1 | Số trang ≥ 1 |
limit | có phân trang | 100 (search: 200) | Số kết quả/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 HTTP
| Mã | Ý nghĩa |
|---|
| 200 | Thành công |
| 400 | Tham số không hợp lệ (thiếu q, page < 1, limit > 500, type sai…) |
| 404 | Không tìm thấy tỉnh/thành với {id} |
| 405 | Phương thức không phải GET |
| 500 | Lỗi xử lý phía server |
Ví dụ cURL
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"
curl "https://your-project.pages.dev/api/v1/ministries?page=1&limit=10"