地区招生分布图

接口概述

• 接口名称：获取地区招生分布数据
• 接口用途：获取各省份招生人数分布数据，支持按年份筛选，包括近五年选项
• 请求路径：POST /api/v1/charts/province-distribution
• 请求方法：POST
• Content-Type：application/json

请求参数

参数名	类型	必填	说明	示例
year	string	否	年份，传具体年份查询该年数据，不传或传"近五年"查询近五年数据	"近五年"、"2024"

返回结构

接口返回标准统一响应格式：

{
  "code": 200,
  "message": "success",
  "data": [
    {
      "province": "广东",
      "num": 123456
    },
    {
      "province": "山东",
      "num": 98765
    }
  ]
}

字段说明

data 数组元素

字段名	类型	说明
province	string	省份名称
num	number	该省份招生人数总和

调用示例

请求示例 - 近五年

curl -X POST http://localhost:3666/api/v1/charts/province-distribution \
  -H "Content-Type: application/json" \
  -d '{
    "year": "近五年"
  }'

请求示例 - 指定年份

curl -X POST http://localhost:3666/api/v1/charts/province-distribution \
  -H "Content-Type: application/json" \
  -d '{
    "year": "2024"
  }'

响应示例

{
  "code": 200,
  "message": "success",
  "data": [
    { "province": "广东", "num": 123456 },
    { "province": "山东", "num": 98765 },
    { "province": "河南", "num": 87654 },
    { "province": "北京", "num": 0 },
    { "province": "天津", "num": 0 }
  ]
}

注意事项

1. 当 year 为具体年份时，查询该年份的各省份招生人数；
2. 当 year 为 "近五年" 或不传时，查询当前年份往前推 5 年（含当前年）的累计数据；
3. 返回结果包含全部 34 个省级行政区，未查询到数据的省份 num 为 0；
4. 最终结果按 num 降序排序。