高考升学信息平台 - 免费开放数据 API 文档 (v1)

指南

快速上手

本 API 旨在提供结构化的、可查询的高考相关数据，完全兼容标准 RESTful 规范，返回 JSON 格式数据。

基本步骤：

1. 获取您的 API Base URL (API 基地址)。
2. 获取您的 API Key (访问令牌) - 如果需要认证。
3. 查阅下面的 API Endpoints，了解可用资源和参数。
4. 使用 HTTP客户端 (如 `curl`, Postman, 或编程语言库) 发起请求。

获取 Base URL 和 API Key

Base URL (API 基地址):

• API 的统一入口点。通常是您部署服务的域名加上 API 版本路径，例如: https://api.yourdomain.com/v1。
• 您可以在您的项目工作台或部署文档中找到确切的 Base URL。
• 对于本文档示例，我们将使用 https://api.yourdomain.com/v1 作为基地址。

API Key (访问令牌 / 密钥):

• 用于认证您的请求，确保只有授权用户才能访问 API。
• **（重要）目前本 v1 版本的 API 为公开 API，暂时无需 API Key 进行认证。**
• 未来如果启用认证，您将需要：
  1. 在平台的 令牌(Token) 或 API Key 管理页面生成您的专属 API Key。
  2. 在每个 API 请求的 HTTP Header 中包含此 Key。通常使用 Authorization Header，格式为 Bearer YOUR_API_KEY。

     Authorization: Bearer sk-xxxxxxxxxxxxxxxxxxxxxx

  3. 请妥善保管您的 API Key，不要泄露给他人。

简介

本 API 提供免费、公开的高考相关数据查询服务，旨在为开发者、研究人员、教育工作者及广大学生家长提供便利。数据主要来源于各省教育考试院、高校官网等公开渠道，并经过结构化处理。

• API 基地址 (Base URL): https://api.yourdomain.com/v1 (请替换为您的实际域名)
• 数据格式: 所有 API 响应均为 JSON 格式。
• 认证: 本 API (v1) 为公开 API，无需认证。
• 版本: v1
• 使用限制: 请合理使用 API 资源，避免短时间内发起大量请求。未来可能会根据服务器负载情况增加速率限制。
• 数据更新: 我们会尽力保持数据的及时性，但具体更新频率取决于上游数据源的发布情况。

数据模型 (Data Models)

API 请求和响应中使用的核心数据结构。

Province (省份)

{
    "code": "11", // 省份代码 (国标)
    "name": "北京"  // 省份名称
  }

Year (年份)

{
    "year": 2024 // 数据对应的年份
  }

Institution (院校)

{
    "code": "10001",          // 院校国标代码
    "name": "北京大学",        // 院校名称
    "province_code": "11",    // 所在省份代码
    "city_name": "北京市",    // 所在城市
    "type": "综合",           // 院校类型 (综合/理工/师范/农林/医药/财经/政法/语言/艺术/体育/民族/军事)
    "level": "本科",          // 办学层次 (本科/专科)
    "tags": ["985", "211", "双一流"], // 院校标签
    "website": "https://www.pku.edu.cn/", // 官方网址
    "logo_url": "https://...", // Logo URL
    "introduction": "北京大学创办于...", // 院校简介 (可能较长)
    // 可能包含更多字段，如主管部门、院士数量等
  }

Major (专业)

{
    "code": "080901",             // 专业代码
    "name": "计算机科学与技术",   // 专业名称
    "category": "工学",           // 专业门类
    "level": "本科",             // 专业层次 (本科/专科)
    "description": "本专业培养...", // 专业介绍
    "main_courses": ["数据结构", "..."], // 主要课程
    "employment_prospects": "就业方向包括...", // 就业前景
    "qualification_requirements": "建议色觉正常...", // 报考要求 (身体/选科等)
    // 可能包含更多字段，如学制、授予学位等
  }

ScoreLine (分数线)

{
    "province_code": "11",    // 省份代码
    "year": 2023,             // 年份
    "batch": "本科批",        // 批次名称
    "subject_type": "物理组", // 科类/选科组 (如 文科/理科/物理组/历史组/综合)
    "score": 680,             // 分数线
    "rank": 1500              // 对应位次 (可选)
  }

Rank (一分一段表/位次)

{
    "province_code": "11",    // 省份代码
    "year": 2023,             // 年份
    "subject_type": "物理组", // 科类/选科组
    "score": 685,             // 分数
    "rank": 1200,             // 当前分数位次
    "cumulative_count": 1200  // 累计人数
  }

EnrollmentPlan (招生计划)

{
    "province_code": "11",    // 招生省份代码
    "year": 2024,             // 年份
    "institution_code": "10001", // 院校代码
    "institution_name": "北京大学", // 院校名称
    "major_code": "080901",   // 专业代码
    "major_name": "计算机科学与技术", // 专业名称
    "batch": "本科提前批A段", // 招生批次
    "plan_count": 5,          // 计划人数
    "subject_requirements": "物理+化学", // 选科要求 (新高考)
    "tuition_fee": 5000,      // 学费 (元/年)
    "remarks": "只招收英语语种考生" // 备注信息
  }

Brochure (招生简章)

{
    "institution_code": "10001", // 院校代码
    "institution_name": "北京大学", // 院校名称
    "year": 2024,             // 年份
    "type": "普通类",         // 简章类型 (普通类/艺术类/强基计划等)
    "title": "北京大学2024年本科招生章程", // 简章标题
    "publish_date": "2024-05-10", // 发布日期
    "source_url": "https://...", // 官方原文链接
    "content_summary": {      // 结构化关键信息 (示例)
      "admission_rules": "按分数优先原则录取...",
      "health_requirements": "参照教育部《普通高等学校招生体检工作指导意见》...",
      "tuition_standard": "学费标准：...",
      "contact_info": "招生电话：..."
    },
    "file_url": "https://.../pku2024.pdf" // PDF下载链接 (可选)
  }

News (招考资讯)

{
    "id": "news_12345",     // 资讯唯一ID
    "title": "XX省2024年高考报名通知", // 标题
    "publish_date": "2023-10-15", // 发布日期
    "source": "XX省教育考试院", // 信息来源
    "category": "高考报名",   // 分类 (报名/考试/查分/志愿/录取/政策解读等)
    "content_url": "https://...", // 原文链接 或 API提供内容详情接口
    "summary": "XX省定于X月X日开始..." // 摘要 (可选)
  }

API Endpoints

基础数据

[Province, ...]

[Year, ...]

院校信息

{
    "total": 150,
    "page": 1,
    "limit": 20,
    "data": [Institution, ...]
  }

Institution

专业信息

{
    "total": 500,
    "page": 1,
    "limit": 20,
    "data": [Major, ...]
  }

Major

分数线与位次

[ScoreLine, ...]

{
    "total": ...,
    "page": ...,
    "limit": ...,
    "data": [Rank, ...]
  }

招生计划

{
    "total": 2000,
    "page": 1,
    "limit": 50,
    "data": [EnrollmentPlan, ...]
  }

招生简章

{
    "total": 100,
    "page": 1,
    "limit": 20,
    "data": [Brochure, ...]
  }

招考资讯

{
    "total": 300,
    "page": 1,
    "limit": 20,
    "data": [News, ...]
  }

错误处理

API 使用标准的 HTTP 状态码来指示请求的成功或失败。

• 200 OK: 请求成功。
• 400 Bad Request: 请求参数无效或缺失。响应体中可能包含错误详情。
• 404 Not Found: 请求的资源不存在。
• 429 Too Many Requests: 请求频率超过限制。
• 500 Internal Server Error: 服务器内部错误。

错误响应示例 (400 Bad Request):

{
    "error": {
      "code": "INVALID_PARAMETER",
      "message": "Missing required parameter: province_code",
      "details": "Parameter 'province_code' is required for this endpoint."
    }
  }

注意事项

这只是一个初步的 API 设计 (v1)，具体实现时可能需要根据数据源的可用性和实际需求进行调整。例如，就业数据 (zhuanye_jiuye.md) 由于难以获得可靠的开放数据源，暂未包含在 API 中。政策解读、填报指南等内容更适合以内容形式（网页、文章）提供，而非结构化 API 数据。

所有 API 端点和数据模型可能会在未来的版本中进行更新或调整，请关注版本说明。