当前位置：首页 > news >正文

基于模型的高校录取概率预测 API 接口

news 2026/6/1 5:50:35

接口详情官网地址: https://www.gugudata.com/api/details/admission-predict

基于模型的高校录取概率预测 API 融合历年分数线与分段位次特征录取概率模型，AI、高考、高考录取、高等教育等关键词场景常会用到，适合用于字典与基础库查询、教育与行业数据整合与筛选条件补全与业务检索等业务场景，方便开发者直接在应用、脚本或数据流程中接入。

gugudata_api_cover

1. 产品功能

基于 LightGBM 梯度提升框架，融合院校分数线、高校与专业录取分数线、分段位次等多源异构数据；
采用概率校准机制，对模型输出进行稳定化处理，提升录取概率结果的一致性与可解释性；
返回录取概率摘要标签，并提供分差、梯度与统计指标，辅助进行志愿分层判断；
支持按需返回 SHAP 因子解释，辅助理解当前预测结果的主要驱动因素；
支持省份过滤、白名单院校、Top-N 控制等高级筛选能力；
支持专业级预测；当专业样本不足时，系统会自动切换到可用的预测路径；
支持 Query 与 JSON 组合入参，便于脚本与后端系统同时调用；
预测结果会结合当前可用的最新招生年份数据与历史样本进行计算；
接口默认 HTTPS，兼容 Apple ATS，配合多节点 CDN 提供高可用服务；
全国多节点 CDN 部署；
接口极速响应，多台服务器构建 API 接口负载均衡；

2. API 文档

接口地址: https://api.gugudata.com/ai/admission/predict?appkey={{appkey}}

返回格式: application/json; charset=utf-8

请求方式: POST

请求协议: HTTPS

请求示例: https://api.gugudata.com/ai/admission/predict?appkey={{appkey}}?appkey=YOUR_APPKEY&province=YOUR_VALUE&subject_type=YOUR_VALUE&score=YOUR_VALUE&rank=YOUR_VALUE&batch=YOUR_VALUE&top_n=50&include_explanation=false&prefer_local=false&college_provinces=YOUR_VALUE&target_colleges=YOUR_VALUE&year=2025&major_name=YOUR_VALUE&local_batch_name=YOUR_VALUE

数据预览: https://www.gugudata.com/preview/admission-predict

接口测试: https://api.gugudata.com/ai/admission/predict/demo

3. 请求参数

参数名	参数类型	是否必须	默认值	备注
appkey	string	是	YOUR_APPKEY	付费后获取的 APPKEY，可通过 Query (?appkey=) 提供
province	string	是	YOUR_VALUE	考生所在省份，与历年分数线数据保持一致
subject_type	string	是	YOUR_VALUE	科类/选科：理科、文科、物理类、历史类、综合等
score	number	是	YOUR_VALUE	考生裸分（0-750）
rank	int	否	YOUR_VALUE	考生全省位次，可为空（为空时结合分段位次推断）
batch	string	否	YOUR_VALUE	报考批次，目前支持普通本科批次
top_n	int	否	50	返回院校数量上限，范围 1-200
include_explanation	boolean	否	false	是否返回 SHAP 补充解释，默认关闭以控制响应时延，开启后仅对部分结果返回解释信息
prefer_local	boolean	否	false	是否在排序时优先本省院校
college_provinces	array(string)	否	YOUR_VALUE	按院校所在省份过滤，留空则不过滤；Query 方式可多次传值，格式 ["江苏", "上海"]
target_colleges	array(string)	否	YOUR_VALUE	指定院校名单，仅对名单内院校预测
year	int	否	2025	预测年份，用于匹配最新控制线与分数线
major_name	string	否	YOUR_VALUE	专业名称（用于专业级预测），命中专业样本时优先返回该专业结果；若样本不足，系统可能切换到院校层或其他兼容预测路径
local_batch_name	string	否	YOUR_VALUE	本地批次名称（用于过滤），不提供时默认使用 batch 参数的值

4. 返回参数

参数名	参数类型	备注
DataStatus.StatusCode	int	接口状态码，100 表示成功
DataStatus.StatusDescription	string	接口返回状态说明
DataStatus.ResponseDateTime	string	返回时间
DataStatus.DataTotalCount	int	本次返回院校数量
Data.predictions	array	预测结果列表
Data.predictions[].college_name	string	院校名称
Data.predictions[].admission_probability	float	录取概率 (0-1)
Data.predictions[].recommendation	string	结果摘要标签：录取概率高 / 需要注意梯度，但成功率较高 / 录取概率低，用于快速概览当前结果
Data.predictions[].long_recommendation	string	面向用户的长句原因解释，结合近年录取线、分差、院校层次、专业匹配情况与补充策略生成
Data.predictions[].evidence	object	关键证据信息对象，可能包含近三年最低线、加权基线分差、省控线差、院校层次、院校排名、招生计划覆盖率、聚合模式等字段
Data.predictions[].shap_explanation	object	SHAP 解释信息，含 base_probability、predicted_probability、top_features，仅在 include_explanation=true 时返回
Data.predictions[].major_name	string	命中专业级预测时返回对应专业名称；若结果回退到院校层，则该字段可能为空
Data.meta.total_colleges	int	返回院校数量
Data.meta.student_score	float	考生分数
Data.meta.student_province	string	考生省份
Data.meta.local_colleges	int	结果中同省院校数量，无 is_local 字段时为 null
Data.meta.score_diff_min	float	分差绝对值最小值
Data.meta.score_diff_median	float	分差绝对值中位数，用于梯度判断
Data.meta.prefer_local	boolean	是否启用本省优先排序
Data.meta.college_provinces	array(string)	请求中用于过滤院校省份的列表
Data.meta.model_version	string	模型版本号
Data.meta.fallback.applied	boolean	是否启用了 fallback 或补充预测策略
Data.meta.fallback.strategy	string	fallback 策略标识，用于说明当前结果采用的兼容预测路径
Data.meta.fallback.requested_year	int	请求中传入的目标预测年份
Data.meta.fallback.effective_year	int	实际用于匹配分数线或历史样本的有效年份
Data.meta.fallback.requested_major_name	string	请求中传入的专业名称
Data.meta.fallback.effective_major_name	string	实际命中的参考专业名称；若未命中稳定专业样本则为空
Data.disclaimer	string	免责声明

5. 错误码说明

状态码	错误说明	备注
100	正常返回	-
501	参数错误	缺少 province、subject_type、score 或 appkey 等必填参数
502	请求频率受限	请降低请求频率
503	APPKEY 过期或订单失效	请前往开发者中心确认订单有效期
504	APPKEY 错误	请检查传递的 APPKEY 是否正确
505	超出调用次数	当前 APPKEY 已达到订单调用上限
-9	预测失败或服务处理异常	模型服务异常、数据源异常或内部处理失败时返回