[DEMO] 高校录取概率模型预测 - 咕咕数据 API 文档

基于模型的高校录取概率预测
接口详情官网地址: https://www.gugudata.com/api/details/admission-predict

融合历年分数线与分段位次特征录取概率模型

请求方法: POST
接口路径: /ai/admission/predict
调试地址: https://api.gugudata.com/ai/admission/predict/demo
OpenAPI: https://www.gugudata.com/openapi/gugudata.openapi.3.1.json

请求参数:

appkey (string, 必填): 付费后获取的 APPKEY，可通过 Query (?appkey=) 提供

province (string, 必填): 考生所在省份，与历年分数线数据保持一致

subject_type (string, 必填): 科类/选科：理科、文科、物理类、历史类、综合等

score (number, 必填): 考生裸分（0-750）

rank (int, 可选): 考生全省位次，可为空（为空时结合分段位次推断）

batch (string, 可选): 报考批次，目前支持普通本科批次

top_n (int, 可选): 返回院校数量上限，范围 1-200

include_explanation (boolean, 可选): 是否返回 SHAP 补充解释，默认关闭以控制响应时延，开启后仅对部分结果返回解释信息

prefer_local (boolean, 可选): 是否在排序时优先本省院校

college_provinces (array(string), 可选): 按院校所在省份过滤，留空则不过滤；Query 方式可多次传值，格式 ["江苏", "上海"]

target_colleges (array(string), 可选): 指定院校名单，仅对名单内院校预测

year (int, 可选): 预测年份，用于匹配最新控制线与分数线

major_name (string, 可选): 专业名称（用于专业级预测），命中专业样本时优先返回该专业结果；若样本不足，系统可能切换到院校层或其他兼容预测路径

local_batch_name (string, 可选): 本地批次名称（用于过滤），不提供时默认使用 batch 参数的值

返回字段:

DataStatus.StatusCode: 接口状态码，100 表示成功

DataStatus.StatusDescription: 接口返回状态说明

DataStatus.ResponseDateTime: 返回时间

DataStatus.DataTotalCount: 本次返回院校数量

Data.predictions: 预测结果列表

Data.predictions[].college_name: 院校名称

Data.predictions[].admission_probability: 录取概率 (0-1)

Data.predictions[].recommendation: 结果摘要标签：录取概率高 / 需要注意梯度，但成功率较高 / 录取概率低，用于快速概览当前结果

Data.predictions[].long_recommendation: 面向用户的长句原因解释，结合近年录取线、分差、院校层次、专业匹配情况与补充策略生成

Data.predictions[].evidence: 关键证据信息对象，可能包含近三年最低线、加权基线分差、省控线差、院校层次、院校排名、招生计划覆盖率、聚合模式等字段

Data.predictions[].shap_explanation: SHAP 解释信息，含 base_probability、predicted_probability、top_features，仅在 include_explanation=true 时返回

Data.predictions[].major_name: 命中专业级预测时返回对应专业名称；若结果回退到院校层，则该字段可能为空

Data.meta.total_colleges: 返回院校数量

Data.meta.student_score: 考生分数

Data.meta.student_province: 考生省份

Data.meta.local_colleges: 结果中同省院校数量，无 is_local 字段时为 null

Data.meta.score_diff_min: 分差绝对值最小值

Data.meta.score_diff_median: 分差绝对值中位数，用于梯度判断

Data.meta.prefer_local: 是否启用本省优先排序

Data.meta.college_provinces: 请求中用于过滤院校省份的列表

Data.meta.model_version: 模型版本号

Data.meta.fallback.applied: 是否启用了 fallback 或补充预测策略

Data.meta.fallback.strategy: fallback 策略标识，用于说明当前结果采用的兼容预测路径

Data.meta.fallback.requested_year: 请求中传入的目标预测年份

Data.meta.fallback.effective_year: 实际用于匹配分数线或历史样本的有效年份

Data.meta.fallback.requested_major_name: 请求中传入的专业名称

Data.meta.fallback.effective_major_name: 实际命中的参考专业名称；若未命中稳定专业样本则为空

Data.disclaimer: 免责声明

HTTP 状态码:

200 接口正常响应: 业务状态码请结合响应体中的状态字段判断。

400 请求参数错误: 参数缺失、格式错误或非法组合。

401 鉴权失败: 缺少 APPKEY 或 APPKEY 无效。

403 无权限或额度不可用: 订单到期、权限不足或剩余额度不可用。

404 资源不存在: 请求路径不存在。

405 请求方法不允许: 请求方法与接口定义不匹配。

415 请求内容类型不支持: 文件上传或请求体格式不符合要求。

429 请求频率超限: 触发接口或网关限流策略。

500 服务内部异常: 服务执行异常，请联系技术支持。

502 上游依赖异常: 上游服务响应异常或暂不可用。

业务状态码:

100 正常返回: 暂无说明

501 参数错误: 缺少 province、subject_type、score 或 appkey 等必填参数

502 请求频率受限: 请降低请求频率

503 APPKEY 过期或订单失效: 请前往开发者中心确认订单有效期

504 APPKEY 错误: 请检查传递的 APPKEY 是否正确

505 超出调用次数: 当前 APPKEY 已达到订单调用上限

-9 预测失败或服务处理异常: 模型服务异常、数据源异常或内部处理失败时返回

接口特性:

基于 LightGBM 梯度提升框架，融合院校分数线、高校与专业录取分数线、分段位次等多源异构数据；

采用概率校准机制，对模型输出进行稳定化处理，提升录取概率结果的一致性与可解释性；

返回录取概率摘要标签，并提供分差、梯度与统计指标，辅助进行志愿分层判断；

支持按需返回 SHAP 因子解释，辅助理解当前预测结果的主要驱动因素；

支持省份过滤、白名单院校、Top-N 控制等高级筛选能力；

支持专业级预测；当专业样本不足时，系统会自动切换到可用的预测路径；

支持 Query 与 JSON 组合入参，便于脚本与后端系统同时调用；

预测结果会结合当前可用的最新招生年份数据与历史样本进行计算；

接口默认 HTTPS，兼容 Apple ATS，配合多节点 CDN 提供高可用服务；

全国多节点 CDN 部署；

接口极速响应，多台服务器构建 API 接口负载均衡；

请求参数

Header 参数

Body 参数application/json

示例

{
        "province": "江苏",
        "subject_type": "物理类",
        "score": 635,
        "rank": 12000,
        "batch": "本科批",
        "top_n": 20,
        "include_explanation": true,
        "prefer_local": false,
        "college_provinces": ["江苏", "上海"],
        "target_colleges": null,
        "year": 2025,
        "appkey": {{appkey}}
      }

请求示例代码

Shell

JavaScript

Java

Swift

PHP

Python

HTTP

Objective-C

Ruby

OCaml

Dart

返回响应

🟢200成功

application/json

Body

示例

{
  "DataStatus": {
    "StatusCode": 0,
    "StatusDescription": "string",
    "ResponseDateTime": "string",
    "DataTotalCount": 0
  },
  "Data": {
    "predictions": [
      {
        "college_name": "string",
        "admission_probability": 0,
        "recommendation": "string",
        "evidence": {},
        "shap_explanation": {},
        "major_name": "string"
      }
    ],
    "disclaimer": "string",
    "meta": {
      "total_colleges": 0,
      "student_score": 0,
      "student_province": "string",
      "local_colleges": 0,
      "score_diff_min": 0,
      "score_diff_median": 0,
      "prefer_local": false,
      "college_provinces": [
        "string"
      ],
      "model_version": "string"
    }
  }
}