Trang thông tin điện tử Trung tâm Nước sạch và Vệ sinh môi trường Nông thôn An Giang

API mở dữ liệu

Giao diện lập trình ứng dụng (API) cung cấp dữ liệu mở của Cổng thông tin điện tử theo định dạng REST/JSON, phục vụ kết nối, chia sẻ và khai thác dữ liệu tự động (Phụ lục VI – Thông tư của Bộ Khoa học và Công nghệ về cổng/trang thông tin điện tử cơ quan nhà nước).

1. Thông tin chung

Địa chỉ gốc (Base URL)https://dev.nuocnongthonangiang.vn/api/v1
Phiên bảnv1
Giao thứcHTTPS, phương thức GET
Định dạng trả vềapplication/json; charset=utf-8
Ngôn ngữ dữ liệuTiếng Việt (vi), mã hóa UTF-8

2. Xác thực

Mọi yêu cầu tới các endpoint dữ liệu phải gửi kèm khóa API trong tiêu đề (HTTP header) X-API-Key. Khóa do quản trị viên Cổng thông tin cấp; tổ chức/cá nhân có nhu cầu khai thác liên hệ Trung tâm để được cấp khóa.

X-API-Key: <khóa-API-được-cấp>

Tất cả endpoint (bao gồm /health) đều yêu cầu khóa API theo Phụ lục VI của Thông tư.

Nếu thiếu hoặc sai khóa, máy chủ trả mã 401 Unauthorized. Nếu hệ thống chưa được quản trị viên cấu hình khóa, các endpoint dữ liệu trả mã 503 Service Unavailable.

3. Danh sách endpoint

GET /api/v1/health 🔒 Cần X-API-Key

Kiểm tra tình trạng hoạt động của dịch vụ và kết nối cơ sở dữ liệu (liveness/health check).

Ví dụ yêu cầu

curl -H "X-API-Key: <khóa>" \
  https://dev.nuocnongthonangiang.vn/api/v1/health

Ví dụ phản hồi (200)

{
  "status": "healthy",
  "timestamp": "2026-06-09T08:00:00+07:00",
  "version": "1.0.0",
  "service": "Cong thong tin dien tu - Trung tam Nuoc sach va Ve sinh moi truong Nong thon An Giang",
  "services": {
    "database": "healthy",
    "cache": "healthy",
    "storage": "healthy"
  }
}

Khi cơ sở dữ liệu không kết nối được: "status": "degraded", "services.database": "error", mã HTTP 503.

GET /api/v1/statistics/posts 🔒 Cần X-API-Key

Thống kê tin bài đã xuất bản: tổng số, phân theo chuyên mục và theo năm.

Tham số truy vấn (tùy chọn)

Tham sốMô tả
category_idLọc theo mã chuyên mục (số nguyên).
from_dateNgày bắt đầu, định dạng YYYY-MM-DD.
to_dateNgày kết thúc, định dạng YYYY-MM-DD.

Ví dụ yêu cầu

curl -H "X-API-Key: <khóa>" \
  "https://dev.nuocnongthonangiang.vn/api/v1/statistics/posts?from_date=2026-01-01&to_date=2026-12-31"

Ví dụ phản hồi (200)

{
  "status": "success",
  "data": {
    "total_posts": 145,
    "by_category": [
      { "category_id": "56", "category_name": "Tin hoạt động NS & VSMT", "count": 30 },
      { "category_id": "23", "category_name": "Lịch cúp nước", "count": 15 }
    ],
    "by_year": [
      { "year": 2026, "count": 11 },
      { "year": 2025, "count": 16 }
    ],
    "time_range": { "from": "2026-01-01", "to": "2026-12-31" }
  },
  "timestamp": "2026-06-09T08:00:00+07:00"
}
TrườngÝ nghĩa
data.total_postsTổng số tin bài đang xuất bản (theo bộ lọc).
data.by_categorySố tin theo chuyên mục (category_id, category_name, count).
data.by_yearSố tin theo năm xuất bản.
data.time_rangeKhoảng thời gian áp dụng bộ lọc (null nếu không lọc).
GET /api/v1/metadata/{id} 🔒 Cần X-API-Key

Dữ liệu đặc tả (metadata) Dublin Core của một tin bài theo mã {id} (định dạng Phụ lục II – Thông tư BKHCN).

Tham số đường dẫn

Tham sốKiểuMô tả
idsố nguyênMã tin bài (New_ID). Bắt buộc, > 0.

Ví dụ yêu cầu

curl -H "X-API-Key: <khóa>" \
  https://dev.nuocnongthonangiang.vn/api/v1/metadata/12594

Ví dụ phản hồi (200)

{
  "status": "success",
  "data": {
    "identifier": "https://dev.nuocnongthonangiang.vn/tin-tuc/...-12594-5",
    "title": "Tiêu đề tin bài",
    "creator": "Trung tâm Nước sạch và Vệ sinh môi trường Nông thôn An Giang",
    "publisher": "Trung tâm Nước sạch và Vệ sinh môi trường Nông thôn An Giang",
    "date": { "created": "2026-04-17", "issued": "2026-04-17", "modified": "2026-04-17" },
    "description": "Tóm tắt nội dung…",
    "language": "vie",
    "subject": ["Tên chuyên mục"],
    "type": "NewsArticle",
    "format": "text/html",
    "coverage": "An Giang, Việt Nam",
    "source": "https://dev.nuocnongthonangiang.vn/tin-tuc/...-12594-5",
    "url": "https://dev.nuocnongthonangiang.vn/tin-tuc/...-12594-5"
  },
  "timestamp": "2026-06-09T08:00:00+07:00"
}

Không tìm thấy tin (sai mã hoặc tin đã ẩn): mã 404 Not Found.

4. Mã trạng thái HTTP

Ý nghĩa
200 OKThành công, trả dữ liệu JSON.
400 Bad RequestTham số không hợp lệ (vd id sai định dạng).
401 UnauthorizedThiếu hoặc sai X-API-Key.
404 Not FoundKhông tìm thấy tài nguyên hoặc endpoint không tồn tại.
405 Method Not AllowedDùng phương thức khác GET.
503 Service UnavailableDịch vụ chưa cấu hình khóa API hoặc CSDL gián đoạn.

Định dạng lỗi

{
  "status": "error",
  "code": 401,
  "message": "Thiếu hoặc sai header X-API-Key.",
  "error": "unauthorized",
  "timestamp": "2026-06-09T08:00:00+07:00"
}

5. Dữ liệu mở khác (máy đọc)

Tài nguyênĐường dẫn
Sơ đồ trang (Sitemap)https://dev.nuocnongthonangiang.vn/sitemap.xml
Nguồn tin RSS 2.0https://dev.nuocnongthonangiang.vn/rss.xml
Quy tắc thu thập (robots)https://dev.nuocnongthonangiang.vn/robots.txt

6. Liên hệ cấp khóa API

Trung tâm Nước sạch và Vệ sinh môi trường Nông thôn An Giang
Điện thoại: (0297) 3811564, 3813420  •  Email: ttnsvsmtnt.snnmt@angiang.gov.vn