CA/docs/API.md

武汉市疾病监测预警系统 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	否	区县名称筛选

响应示例:

{
  "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"
}

使用示例:

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	否	风险等级筛选

响应示例:

{
  "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"
}

使用示例:

curl "http://localhost:8000/api/grids/geojson?date=2022-12-15"

---

3. 多日风险预测

POST /api/predict/multi-day

生成指定日期开始的多日网格风险预测。

请求体:

{
  "date": "2022-12-15",
  "days": 7,
  "district": "武昌区"
}

参数:

参数	类型	必填	说明
date	string	是	开始日期 (YYYY-MM-DD)
days	integer	否	预测天数 (1-14, 默认 7)
district	string	否	区县名称筛选

响应示例:

{
  "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"
}

使用示例:

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)

响应示例:

{
  "grid_id": "r100_c200",
  "district": "武昌区",
  "history": [
    {
      "date": "2022-12-01",
      "cases": 5,
      "outpatient": 4,
      "inpatient": 1
    }
  ],
  "timestamp": "2026-05-02T10:30:00"
}

使用示例:

curl "http://localhost:8000/api/grids/r100_c200/history?days=30"

---

错误处理

通用错误响应格式:

{
  "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、多日预测