Akiba So
fc468464b2
Context: Build a spatial risk assessment system correlating air quality data with children's respiratory disease incidence across Wuhan. Approach: FastAPI backend serving PostGIS spatial queries, React frontend with Deck.gl maps, and a PyTorch SpatialTemporalGCN pipeline for multi-day (1d/3d/7d) risk prediction. Changes: - backend/ — FastAPI API with auth (JWT), alerts, risk analysis, geocoded case data, grid statistics, and report endpoints - frontend/ — React dashboard with interactive risk maps, alert monitoring, district comparison charts, and timeline player - models/ — SpatialTemporalGCN model with trained weights and ONNX export for inference - scripts/ — ETL pipeline for weather + medical data, grid generation, feature engineering, training, and daily inference - deploy/ — Docker Compose configs for backend, frontend, and MLflow - docs/ — API docs, deployment guide, user guide, and code review Impact: Enables spatial risk visualization, alert monitoring, and ML-driven health risk forecasting for environmental health teams.
242 lines
5.0 KiB
Markdown
242 lines
5.0 KiB
Markdown
# 武汉市疾病监测预警系统 API 文档
|
|
|
|
## 概述
|
|
|
|
本 API 提供武汉市 100m 网格级别的疾病监测、风险预测和历史数据查询功能。
|
|
|
|
**Base URL**: `http://localhost:8000/api`
|
|
|
|
**认证**: 当前无需认证
|
|
|
|
---
|
|
|
|
## 端点列表
|
|
|
|
### 1. 历史数据聚合
|
|
|
|
#### `GET /api/history/aggregated`
|
|
|
|
按区县和日期聚合的历史病例和气象数据。
|
|
|
|
**参数**:
|
|
| 参数 | 类型 | 必填 | 说明 |
|
|
|------|------|------|------|
|
|
| `start_date` | string | 是 | 开始日期 (YYYY-MM-DD) |
|
|
| `end_date` | string | 是 | 结束日期 (YYYY-MM-DD) |
|
|
| `aggregation` | string | 否 | 聚合级别：`daily` (默认), `weekly`, `monthly` |
|
|
| `district` | string | 否 | 区县名称筛选 |
|
|
|
|
**响应示例**:
|
|
```json
|
|
{
|
|
"aggregations": [
|
|
{
|
|
"district": "武昌区",
|
|
"date": "2022-12-01",
|
|
"total_cases": 15,
|
|
"outpatient_count": 12,
|
|
"inpatient_count": 3,
|
|
"avg_AQI": 85.5,
|
|
"avg_PM25": 45.2,
|
|
"avg_PM10": 78.3
|
|
}
|
|
],
|
|
"total_records": 365,
|
|
"date_range": ["2022-12-01", "2022-12-31"],
|
|
"timestamp": "2026-05-02T10:30:00"
|
|
}
|
|
```
|
|
|
|
**使用示例**:
|
|
```bash
|
|
curl "http://localhost:8000/api/history/aggregated?start_date=2022-12-01&end_date=2022-12-31&aggregation=daily"
|
|
```
|
|
|
|
---
|
|
|
|
### 2. 网格 GeoJSON
|
|
|
|
#### `GET /api/grids/geojson`
|
|
|
|
获取指定日期的网格数据 GeoJSON 格式，用于地图可视化。
|
|
|
|
**参数**:
|
|
| 参数 | 类型 | 必填 | 说明 |
|
|
|------|------|------|------|
|
|
| `date` | string | 是 | 日期 (YYYY-MM-DD) |
|
|
| `district` | string | 否 | 区县名称筛选 |
|
|
| `risk_level` | string | 否 | 风险等级筛选 |
|
|
|
|
**响应示例**:
|
|
```json
|
|
{
|
|
"type": "FeatureCollection",
|
|
"features": [
|
|
{
|
|
"type": "Feature",
|
|
"geometry": {
|
|
"type": "Point",
|
|
"coordinates": [114.305, 30.598]
|
|
},
|
|
"properties": {
|
|
"grid_id": "r100_c200",
|
|
"latitude": 30.598,
|
|
"longitude": 114.305,
|
|
"district": "武昌区",
|
|
"total_cases": 5,
|
|
"population_density": 12500
|
|
}
|
|
}
|
|
],
|
|
"timestamp": "2026-05-02T10:30:00"
|
|
}
|
|
```
|
|
|
|
**使用示例**:
|
|
```bash
|
|
curl "http://localhost:8000/api/grids/geojson?date=2022-12-15"
|
|
```
|
|
|
|
---
|
|
|
|
### 3. 多日风险预测
|
|
|
|
#### `POST /api/predict/multi-day`
|
|
|
|
生成指定日期开始的多日网格风险预测。
|
|
|
|
**请求体**:
|
|
```json
|
|
{
|
|
"date": "2022-12-15",
|
|
"days": 7,
|
|
"district": "武昌区"
|
|
}
|
|
```
|
|
|
|
**参数**:
|
|
| 参数 | 类型 | 必填 | 说明 |
|
|
|------|------|------|------|
|
|
| `date` | string | 是 | 开始日期 (YYYY-MM-DD) |
|
|
| `days` | integer | 否 | 预测天数 (1-14, 默认 7) |
|
|
| `district` | string | 否 | 区县名称筛选 |
|
|
|
|
**响应示例**:
|
|
```json
|
|
{
|
|
"predictions": [
|
|
{
|
|
"grid_id": "r100_c200",
|
|
"latitude": 30.598,
|
|
"longitude": 114.305,
|
|
"risk_1day": 0.75,
|
|
"risk_3day": 0.68,
|
|
"risk_7day": 0.72,
|
|
"risk_level": "medium_high",
|
|
"confidence": 0.85
|
|
}
|
|
],
|
|
"total_grids": 998601,
|
|
"date_range": ["2022-12-15", "2022-12-21"],
|
|
"model_version": "1.3.7",
|
|
"timestamp": "2026-05-02T10:30:00"
|
|
}
|
|
```
|
|
|
|
**使用示例**:
|
|
```bash
|
|
curl -X POST "http://localhost:8000/api/predict/multi-day" \
|
|
-H "Content-Type: application/json" \
|
|
-d '{"date": "2022-12-15", "days": 7}'
|
|
```
|
|
|
|
---
|
|
|
|
### 4. 网格历史数据
|
|
|
|
#### `GET /api/grids/{grid_id}/history`
|
|
|
|
获取指定网格的历史数据。
|
|
|
|
**参数**:
|
|
| 参数 | 类型 | 必填 | 说明 |
|
|
|------|------|------|------|
|
|
| `grid_id` | string | 是 | 网格 ID (如 `r100_c200`) |
|
|
| `days` | integer | 否 | 历史天数 (1-365, 默认 30) |
|
|
|
|
**响应示例**:
|
|
```json
|
|
{
|
|
"grid_id": "r100_c200",
|
|
"district": "武昌区",
|
|
"history": [
|
|
{
|
|
"date": "2022-12-01",
|
|
"cases": 5,
|
|
"outpatient": 4,
|
|
"inpatient": 1
|
|
}
|
|
],
|
|
"timestamp": "2026-05-02T10:30:00"
|
|
}
|
|
```
|
|
|
|
**使用示例**:
|
|
```bash
|
|
curl "http://localhost:8000/api/grids/r100_c200/history?days=30"
|
|
```
|
|
|
|
---
|
|
|
|
## 错误处理
|
|
|
|
**通用错误响应格式**:
|
|
```json
|
|
{
|
|
"detail": "错误描述信息"
|
|
}
|
|
```
|
|
|
|
**常见错误码**:
|
|
| 状态码 | 说明 |
|
|
|--------|------|
|
|
| 400 | 请求参数错误 (日期格式错误、超出范围等) |
|
|
| 404 | 资源不存在 (网格 ID 无效等) |
|
|
| 500 | 服务器内部错误 |
|
|
|
|
---
|
|
|
|
## 数据字典
|
|
|
|
### 风险等级 (risk_level)
|
|
|
|
| 等级 | 风险值范围 | 颜色 |
|
|
|------|-----------|------|
|
|
| `low` | 0.0 - 0.2 | 绿色 (#22c55e) |
|
|
| `medium_low` | 0.2 - 0.4 | 蓝色 (#3b82f6) |
|
|
| `medium` | 0.4 - 0.6 | 黄色 (#eab308) |
|
|
| `medium_high` | 0.6 - 0.8 | 橙色 (#f97316) |
|
|
| `high` | 0.8 - 1.0 | 红色 (#ef4444) |
|
|
|
|
### 区县列表
|
|
|
|
- 江岸区、江汉区、硚口区、汉阳区、武昌区
|
|
- 青山区、洪山区、东西湖区、汉南区、蔡甸区
|
|
- 江夏区、黄陂区、新洲区
|
|
|
|
---
|
|
|
|
## 性能优化
|
|
|
|
- **缓存**: 特征数据缓存 TTL 为 1 小时
|
|
- **批量处理**: 网格预测按 10,000 个/批处理
|
|
- **分页**: 大结果集自动限制 (最多 50,000 条)
|
|
|
|
---
|
|
|
|
## 版本历史
|
|
|
|
| 版本 | 日期 | 变更 |
|
|
|------|------|------|
|
|
| 1.0.0 | 2026-05-02 | 初始版本：历史聚合、网格 GeoJSON、多日预测 |
|