API 文档

地表水监测系统 REST API — 版本 v1

公开无需认证登录需要登录 API Key 需要 API Key（专业版+）

简介

本 API 提供全国 1873 个地表水监测断面的实时水质数据、7天 AI 预测、历史趋势等功能。

Base URL： https://dibiaoshui.com

响应格式： 均为 JSON；时间字段为 ISO 8601 格式。

编码： UTF-8。

认证方式

Session 认证（浏览器登录）

通过 POST /auth/login/ 获取 Session，浏览器自动携带 Cookie。

API Key 认证（程序调用）

在请求头中添加：

Authorization: Bearer wm_your_api_key_here

API Key 可在「API Key 管理」页面创建（需专业版及以上套餐）。

水质数据

GET /api/sections/dynamic/ 公开

全国断面实时水质数据

参数	类型	必填	说明	示例
province	string	否	省份名称筛选	北京市
watershed	string	否	流域筛选	海河流域
quality	string	否	水质类别筛选	Ⅱ
limit	int	否	返回条数，默认100	50

{"total": 1873, "data": [{"断面名称": "永定河卢沟桥", "省份": "北京市", "流域": "海河流域", "水质类别": "Ⅲ", "pH": "7.8", "溶解氧": "9.2", ...}]}

GET /api/stats/ 公开

水质统计汇总（各等级数量、达标率等）

{"total_stations": 1873, "grade_distribution": {"Ⅱ": 523, "Ⅲ": 812, ...}, "compliance_rate": 88.6}

GET /api/provincial/realtime/ 公开

省级实时水质数据汇总

参数	类型	必填	说明	示例
province	string	否	省份名称	广东省
limit	int	否	返回条数	30

水质预测

GET /prediction/api/forecast/ API Key

7天水质预测（XGBoost + 时序模型，1873站覆盖）

参数	类型	必填	说明	示例
station	string	是	断面名称	永定河卢沟桥
days	int	否	预测天数 1-7，默认7	3
parameter	string	否	指定参数，默认全部	氨氮

{"station": "永定河卢沟桥", "forecasts": [{"date": "2026-02-28", "pH": {"value": 7.9, "confidence": 0.87}, "氨氮": {"value": 0.32, ...}}]}

GET /prediction/api/locations/ 公开

支持预测的站点列表

GET /prediction/api/parameters/ 公开

支持预测的参数列表（pH、溶解氧、氨氮、总磷等11项）

数据导出

数据导出接口需要 专业版 或以上套餐。

GET /api/export/stations/ 登录

站点信息导出（CSV/JSON）

参数	类型	必填	说明
format	string	否	csv 或 json，默认 json

GET /api/export/realtime-data/ 登录

实时水质数据导出

参数	类型	必填	说明
start_date	date	否	开始日期，如 2026-01-01
end_date	date	否	结束日期
province	string	否	省份筛选
format	string	否	csv 或 json

GET /api/export/predictions/ 登录

预测数据批量导出

天气与水文

GET /api/weather/data/ 公开

全国气象站点天气数据（温度、降水、风速）

参数	类型	必填	说明
station	string	否	气象站名称
days	int	否	最近N天，默认7
limit	int	否	返回条数

错误码说明

HTTP 状态码	含义	常见原因
`200`	成功	请求正常处理
`400`	请求参数错误	缺少必填参数或参数格式不对
`401`	未认证	未提供 API Key 或 Key 已失效
`403`	权限不足	当前套餐不支持此功能
`404`	资源不存在	站点名称拼写错误
`429`	请求过频	超过 API Key 日限额
`500`	服务器错误	请联系技术支持

错误响应格式：{"error": "错误描述", "code": 400}