高校录取概率模型预测 - 咕咕数据 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；传入 probability_tiers 时按各档位数量返回

probability_tiers (array(object), 可选): 概率分层配置，仅支持 JSON Body 传入。示例：[{"name":"safe","label":"保","min_probability":0.98,"limit":3},{"name":"stable","label":"稳","min_probability":0.8,"limit":3},{"name":"reach","label":"冲","min_probability":0.75,"limit":3}]。每项包含 name、label、min_probability、limit；min_probability 必须严格递减，相邻档位自动形成概率区间；可配合 tier_sort 控制每档内部取数顺序，用于一次返回保、稳、冲等多档志愿结果；不传时继续按 top_n 返回。

tier_sort (string, 可选): 概率分层每档内部排序策略，仅在 probability_tiers 生效时使用；可选 probability、college_rank、balanced。probability 按录取概率排序，college_rank 按院校排名优先，balanced 综合院校层次、排名和概率。

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

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

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

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

uuid (string, 可选): 指定一个院校唯一 ID，仅对该院校预测；可使用全国大学高校基础信息接口返回的 SchoolUUID

target_college_uuids (array(string), 可选): 指定院校唯一 ID 列表，仅对名单内院校预测；多个值可使用数组或逗号分隔字符串

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.predictions[].tier_name: 命中的概率档位标识，仅在请求 probability_tiers 时返回

Data.predictions[].tier_label: 命中的概率档位展示名称，仅在请求 probability_tiers 时返回

Data.predictions[].tier_min_probability: 命中档位的录取概率下限，仅在请求 probability_tiers 时返回；下一档会自动以上一档下限作为概率上界

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.probability_tiers: 概率分层返回统计，仅在请求 probability_tiers 时返回；每项包含 name、label、min_probability、limit、returned_count，下一档会自动以上一档下限作为概率上界

Data.meta.tier_sort: 本次概率分层每档内部排序策略，仅在请求 probability_tiers 时返回

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（TLS v1.0 / v1.1 / v1.2 / v1.3）；

全面兼容 Apple ATS；

全国多节点 CDN 部署；

接口调用状态与状态监控：https://www.gugudata.com/status。

请求参数

Authorization

API Key

在 header 添加参数

AppKey

示例：

AppKey: ********************

API Key

在 query 添加参数

appkey

示例：

appkey: ********************

Query 参数

Body 参数application/json必填

示例

{
    "province": "江苏",
    "subject_type": "物理类",
    "score": 635,
    "rank": 12000,
    "batch": "本科批",
    "top_n": 3,
    "include_explanation": false,
    "prefer_local": false,
    "college_provinces": [
        "江苏",
        "上海"
    ],
    "target_colleges": [
        "南京邮电大学"
    ],
    "year": 2026
}

请求示例代码

Shell

JavaScript

Java

Swift

PHP

Python

HTTP

Objective-C

Ruby

OCaml

Dart

返回响应

🟢200成功

application/json

接口正常响应。请求成功，业务状态请结合响应体中的自定义业务码判断。

Bodyapplication/json

示例

预测成功有效请求暂无可用结果

{
    "DataStatus": {
        "RequestParameter": "{\"province\": \"江苏\", \"subject_type\": \"物理类\", \"score\": 635, \"rank\": 12000, \"batch\": \"本科批\", \"top_n\": 10, \"include_explanation\": false, \"prefer_local\": false, \"college_provinces\": [\"江苏\", \"上海\"], \"target_colleges\": [\"南京大学\", \"东南大学\", \"南京航空航天大学\", \"南京理工大学\", \"苏州大学\", \"南京邮电大学\", \"河海大学\", \"江南大学\", \"上海大学\", \"华东理工大学\"], \"local_batch_name\": \"本科批\", \"year\": 2026}",
        "StatusCode": 100,
        "StatusDescription": "预测成功",
        "ResponseDateTime": "2026-07-12 13:52:24.665",
        "DataTotalCount": 7,
        "RequestId": "dc85b98c-4ac6-4832-b7e7-3d5c247dd402"
    },
    "Data": {
        "predictions": [
            {
                "college_name": "南京邮电大学",
                "admission_probability": 0.8372396892372395,
                "evidence": {
                    "recent_3y_min_score": [
                        623,
                        623
                    ],
                    "score_gap": 12,
                    "score_gap_original": 12,
                    "province_line_gap": 172,
                    "is_985": false,
                    "is_211": false,
                    "is_dual_class": true,
                    "college_rank": 122,
                    "plan_enrollment": 297,
                    "plan_coverage_ratio": 0.9179767600820232,
                    "major_hist_avg": 627,
                    "major_recent_min_trend": 0,
                    "aggregation_mode": "plan_weighted_school_probability",
                    "matched_plan_rows": 29,
                    "covered_plan_total": 2686,
                    "school_plan_total": 2926
                },
                "shap_explanation": null,
                "recommendation": "录取概率高",
                "long_recommendation": "当前录取概率较高，按近年录取情况看，你的分数处于相对安全区间。你的分数高于近三年最低线12分，也高于近三年均值线12分。该结果按可匹配专业的招生计划加权汇总，更接近学校整体录取难度。",
                "major_name": null,
                "tier_name": null,
                "tier_label": null,
                "tier_min_probability": null
            },
            {
                "college_name": "江南大学",
                "admission_probability": 0.7834302033631845,
                "evidence": {
                    "recent_3y_min_score": [
                        624,
                        600
                    ],
                    "score_gap": 27.799999999999955,
                    "score_gap_original": 11,
                    "province_line_gap": 172,
                    "is_985": false,
                    "is_211": true,
                    "is_dual_class": true,
                    "college_rank": 57,
                    "plan_enrollment": 61,
                    "plan_coverage_ratio": 0.940554821664465,
                    "major_hist_avg": 627,
                    "major_recent_min_trend": 44,
                    "aggregation_mode": "plan_weighted_school_probability",
                    "matched_plan_rows": 46,
                    "covered_plan_total": 712,
                    "school_plan_total": 757
                },
                "shap_explanation": null,
                "recommendation": "需要注意梯度，但成功率较高",
                "long_recommendation": "当前录取机会较大，但仍需关注同分段竞争和院校梯度波动。你的分数高于近三年最低线11分，也高于近三年均值线35分。该结果按可匹配专业的招生计划加权汇总，更接近学校整体录取难度。",
                "major_name": null,
                "tier_name": null,
                "tier_label": null,
                "tier_min_probability": null
            },
            {
                "college_name": "苏州大学",
                "admission_probability": 0.6957940753052466,
                "evidence": {
                    "recent_3y_min_score": [
                        635,
                        636
                    ],
                    "score_gap": -0.7000000000000455,
                    "score_gap_original": 0,
                    "province_line_gap": 172,
                    "is_985": false,
                    "is_211": true,
                    "is_dual_class": true,
                    "college_rank": 42,
                    "plan_enrollment": 130,
                    "plan_coverage_ratio": 0.8998971546109016,
                    "major_hist_avg": 636,
                    "major_recent_min_trend": -4,
                    "aggregation_mode": "plan_weighted_school_probability",
                    "matched_plan_rows": 68,
                    "covered_plan_total": 2625,
                    "school_plan_total": 2917
                },
                "shap_explanation": null,
                "recommendation": "需要注意梯度，但成功率较高",
                "long_recommendation": "当前录取机会较大，但仍需关注同分段竞争和院校梯度波动。你的分数高于近三年最低线0分，但仍比近三年均值线低1分。该结果按可匹配专业的招生计划加权汇总，更接近学校整体录取难度。",
                "major_name": null,
                "tier_name": null,
                "tier_label": null,
                "tier_min_probability": null
            },
            {
                "college_name": "河海大学",
                "admission_probability": 0.46791220754157176,
                "evidence": {
                    "recent_3y_min_score": [
                        629,
                        629
                    ],
                    "score_gap": 6,
                    "score_gap_original": 6,
                    "province_line_gap": 172,
                    "is_985": false,
                    "is_211": true,
                    "is_dual_class": true,
                    "college_rank": 65,
                    "plan_enrollment": 95,
                    "plan_coverage_ratio": 0.8977871443624869,
                    "major_hist_avg": 633,
                    "major_recent_min_trend": 0,
                    "aggregation_mode": "plan_weighted_school_probability",
                    "matched_plan_rows": 23,
                    "covered_plan_total": 852,
                    "school_plan_total": 949
                },
                "shap_explanation": null,
                "recommendation": "需要注意梯度，但成功率较高",
                "long_recommendation": "当前录取机会较大，但仍需关注同分段竞争和院校梯度波动。你的分数高于近三年最低线6分，也高于近三年均值线6分。该结果按可匹配专业的招生计划加权汇总，更接近学校整体录取难度。",
                "major_name": null,
                "tier_name": null,
                "tier_label": null,
                "tier_min_probability": null
            },
            {
                "college_name": "东南大学",
                "admission_probability": 0.3539651913843792,
                "evidence": {
                    "recent_3y_min_score": [
                        644,
                        644
                    ],
                    "score_gap": -9,
                    "score_gap_original": -9,
                    "province_line_gap": 172,
                    "is_985": true,
                    "is_211": true,
                    "is_dual_class": true,
                    "college_rank": 20,
                    "plan_enrollment": 87,
                    "plan_coverage_ratio": 0.7524875621890548,
                    "major_hist_avg": 649,
                    "major_recent_min_trend": 0,
                    "aggregation_mode": "plan_weighted_school_probability",
                    "matched_plan_rows": 24,
                    "covered_plan_total": 605,
                    "school_plan_total": 804
                },
                "shap_explanation": null,
                "recommendation": "录取概率低",
                "long_recommendation": "当前录取概率偏低，按近年录取情况看仍有明显压力。你的分数比近三年最低线低9分，也比近三年均值线低9分。虽然你的分数高出本省控制线172分，但目标院校近年门槛整体更高。该结果按可匹配专业的招生计划加权汇总，更接近学校整体录取难度。院校层次高、竞争强，通常会把整体录取分数要求拉高。",
                "major_name": null,
                "tier_name": null,
                "tier_label": null,
                "tier_min_probability": null
            },
            {
                "college_name": "南京理工大学",
                "admission_probability": 0.2910228914369988,
                "evidence": {
                    "recent_3y_min_score": [
                        642,
                        642
                    ],
                    "score_gap": -7,
                    "score_gap_original": -7,
                    "province_line_gap": 172,
                    "is_985": false,
                    "is_211": true,
                    "is_dual_class": true,
                    "college_rank": 37,
                    "plan_enrollment": 60,
                    "plan_coverage_ratio": 0.7988165680473372,
                    "major_hist_avg": 643,
                    "major_recent_min_trend": 0,
                    "aggregation_mode": "plan_weighted_school_probability",
                    "matched_plan_rows": 23,
                    "covered_plan_total": 405,
                    "school_plan_total": 507
                },
                "shap_explanation": null,
                "recommendation": "录取概率低",
                "long_recommendation": "当前录取概率偏低，按近年录取情况看仍有明显压力。你的分数比近三年最低线低7分，也比近三年均值线低7分。虽然你的分数高出本省控制线172分，但目标院校近年门槛整体更高。该结果按可匹配专业的招生计划加权汇总，更接近学校整体录取难度。院校层次高、竞争强，通常会把整体录取分数要求拉高。",
                "major_name": null,
                "tier_name": null,
                "tier_label": null,
                "tier_min_probability": null
            },
            {
                "college_name": "南京航空航天大学",
                "admission_probability": 0.27860252802394925,
                "evidence": {
                    "recent_3y_min_score": [
                        645,
                        645
                    ],
                    "score_gap": -10,
                    "score_gap_original": -10,
                    "province_line_gap": 172,
                    "is_985": false,
                    "is_211": true,
                    "is_dual_class": true,
                    "college_rank": 47,
                    "plan_enrollment": 76,
                    "plan_coverage_ratio": 0.6012145748987854,
                    "major_hist_avg": 649.5,
                    "major_recent_min_trend": 0,
                    "aggregation_mode": "plan_weighted_school_probability",
                    "matched_plan_rows": 19,
                    "covered_plan_total": 297,
                    "school_plan_total": 494
                },
                "shap_explanation": null,
                "recommendation": "录取概率低",
                "long_recommendation": "当前录取概率偏低，按近年录取情况看仍有明显压力。你的分数比近三年最低线低10分，也比近三年均值线低10分。虽然你的分数高出本省控制线172分，但目标院校近年门槛整体更高。该结果按可匹配专业的招生计划加权汇总，更接近学校整体录取难度。院校层次高、竞争强，通常会把整体录取分数要求拉高。",
                "major_name": null,
                "tier_name": null,
                "tier_label": null,
                "tier_min_probability": null
            }
        ],
        "meta": {
            "total_colleges": 7,
            "student_score": 635,
            "student_province": "江苏",
            "local_colleges": null,
            "score_diff_min": 0,
            "score_diff_median": 9,
            "prefer_local": false,
            "college_provinces": [
                "江苏",
                "上海"
            ],
            "model_version": "v1.1.0"
        },
        "disclaimer": "本预测结果综合历年真实招生数据、院校录取趋势与机器学习模型推算而成，仅供志愿填报参考。建议结合当年政策、院校最新官方信息及个人实际情况综合判断，最终录取结果以各省考试院和院校官方公布为准。"
    }
}

🟠400

🟠401

🟠403

🟠404

🟠405

🟠415

🟠422

🟠429

🔴500

🔴502

🔴503

🔴504