| 参数 | 类型 | 必填 | 默认值 | 说明 |
|---|---|---|---|---|
| appkey | string | 否 | 无 | 付费后获取的 APPKEY。支持 AppKey、X-GUGUDATA-APPKEY、X-API-Key 请求头、Bearer、Query 和历史 JSON 鉴权字段;多处一致凭据允许,重复或冲突凭据失败。 AppKey 整体必填;在本操作已声明支持的鉴权位置任选一个提供,本位置无需重复填写。多处填写时须一致。 |
| province | string | 是 | 无 | 考生所在省份,与历年分数线数据保持一致 |
| subject_type | string | 是 | 无 | 科类/选科:理科、文科、物理类、历史类、综合等 |
| score | number | 否 | 无 | 考生裸分,与 rank 至少提供一项;一般省份 0–750,海南最高 900。仅位次请求是否可评估取决于当前模型与分段位次资料,无法换算时返回明确无数据原因。 |
| rank | integer | 否 | 无 | 考生全省位次,与 score 至少提供一项。保留该历史参数;当前模型未采用位次时以 meta.rank_source、effective_rank 说明,不将传入位次视为已参与计算。 |
| batch | string | 否 | 本科批 | 报考批次,目前支持普通本科批次 |
| top_n | integer | 否 | 50 | 返回院校数量上限,范围 1-200;传入 probability_tiers 时按各档位数量返回 |
| probability_tiers | array | 否 | 无,不传时使用 top_n | 概率分层配置,仅支持 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 | 概率分层每档内部排序策略,仅在 probability_tiers 生效时使用;可选 probability、college_rank、balanced。probability 按录取概率排序,college_rank 按院校排名优先,balanced 综合院校层次、排名和概率。 |
| include_explanation | boolean | 否 | false | 是否返回补充影响因素说明,默认关闭以控制响应时延,开启后仅对部分结果返回解释信息 |
| prefer_local | boolean | 否 | false | 是否在排序时优先本省院校 |
| college_provinces | array | 否 | 无 | 按院校所在省份过滤,留空则不过滤;Query 方式可多次传值,格式 ["江苏", "上海"] |
| target_colleges | array | 否 | 无 | 指定院校名单,仅对名单内院校预测 |
| uuid | string | 否 | 无 | 指定一个院校唯一 ID,仅对该院校预测; 可使用全国大学高校基础信息接口返回的 SchoolUUID |
| target_college_uuids | array | 否 | 无 | 指定院校唯一 ID 列表,仅对名单内院校预测;多个值可使用数组或逗号分隔字符串 |
| year | integer | 否 | 当前配置预测周期 | 目标招生年份,当前配置预测周期为 2026;兼容保留传入值,实际预测周期以 meta.prediction_year 和 requested_year/effective_year 为准,不提供历史回测语义。 |
| major_name | string | 否 | 无 | 专业名称(用于专业级预测),命中专业样本时优先返回该专业结果;若样本不足,系统可能切换到院校层或其他兼容预测路径 |
| local_batch_name | string | 否 | 无 | 本地批次名称(用于过滤),不提供时默认使用 batch 参数的值 |
| 字段 | 类型 | 说明 |
|---|---|---|
| DataStatus.StatusCode | integer | 接口状态码,100 表示成功 |
| DataStatus.StatusDescription | string | 接口返回状态说明 |
| DataStatus.ResponseDateTime | string | 返回时间 |
| DataStatus.DataTotalCount | integer | 本次返回院校数量 |
| Data.predictions | array | 预测结果列表 |
| Data.predictions[].college_name | string | 院校名称 |
| Data.predictions[].admission_probability | number | 兼容字段:历史条件下的录取参考概率(0-1),永久保留以兼容现有客户 |
| Data.predictions[].chance_score | number | 推荐使用字段:历史条件机会分(0-1),与 admission_probability 数值完全相同 |
| Data.predictions[].recommendation | string | 兼容字段:保留现有摘要文案和值,现有客户无需修改;新应用建议使用 interpretation |
| Data.predictions[].long_recommendation | string | 兼容字段:保留现有长文案和值;新应用建议使用可复算的 long_interpretation |
| Data.predictions[].interpretation | string | 推荐使用字段:按固定机会区间返回的志愿梯度解释 |
| Data.predictions[].long_interpretation | string | 推荐使用字段:只使用同一响应中的结构化证据拼装;证据不足时省略对应句子,证据冲突时停止输出详细数字 |
| Data.predictions[].historical_years | array | 该结果实际使用的历史招生年份;不会根据截至年份和数量推测连续年份 |
| Data.predictions[].data_through_year | integer | 该结果实际使用的最新历史招生年份 |
| Data.predictions[].plan_coverage | object | 招生计划覆盖信息;AVAILABLE 时 ratio 可由 covered_plan_total / school_plan_total 复算,未知不会用 0 表示 |
| Data.predictions[].fallback_path | object | 请求层级、实际数据层级、兼容策略和原因码 |
| Data.predictions[].evidence_consistency_status | string | 证据复算状态:VERIFIED、PARTIAL 或 FAILED |
| Data.predictions[].evidence | object | 关键证据对象;保留 recent_3y_min_score,并新增具名 historical_score_summary 供年份、最低线、输入分数和分差复算 |
| Data.predictions[].evidence.historical_score_summary | object | 具名历史分数摘要,包含 years、latest_min_score、recent_min_score_average、student_score、gap_to_latest_min 和 gap_to_recent_min_average |
| Data.predictions[].shap_explanation | object | 补充影响因素说明,仅在 include_explanation=true 且当前结果可解释时返回 |
| Data.predictions[].major_name | string | 命中专业级预测时返回对应专业名称;若结果回退到院校层,则该字段可能为空 |
| Data.predictions[].tier_name | string | 命中的概率档位标识,仅在请求 probability_tiers 时返回 |
| Data.predictions[].tier_label | string | 命中的概率档位展示名称,仅在请求 probability_tiers 时返回 |
| Data.predictions[].tier_min_probability | number | 命中档位的录取概率下限,仅在请求 probability_tiers 时返回;下一档会自动以上一档下限作为概率上界 |
| Data.meta.total_colleges | integer | 返回院校数量 |
| Data.meta.student_score | number | 考生分数 |
| Data.meta.student_province | string | 考生省份 |
| Data.meta.local_colleges | integer | 结果中同省院校数量,无 is_local 字段时为 null |
| Data.meta.score_diff_min | number | 分差绝对值最小值 |
| Data.meta.score_diff_median | number | 分差绝对值中位数,用于梯度判断 |
| Data.meta.prefer_local | boolean | 是否启用本省优先排序 |
| Data.meta.college_provinces | array | 请求中用于过滤院校省份的列 表 |
| Data.meta.model_version | string | 模型版本号 |
| Data.meta.data_through_year | integer | 本次返回结果实际使用的最新历史招生年份 |
| Data.meta.historical_years | array | 本次返回结果实际使用的历史招生年份并集 |
| Data.meta.coverage_level | string | 本次结果的历史数据覆盖等级;结果层级不一致时为 mixed |
| Data.meta.interpretation_policy_version | string | 机会与梯度解释策略版本 |
| Data.meta.policy_constraints | object | 请求级政策评估边界,列出已评估项、未评估项及核对提示 |
| Data.meta.probability_tiers | array | 概率分层返回统计,仅在请求 probability_tiers 时返回;每项包含 name、label、min_probability、limit、returned_count,下一档会自动以上一档下限作为概率上界 |
| Data.meta.tier_sort | string | 本次概率分层每档内部排序策略,仅在请求 probability_tiers 时返回 |
| Data.meta.fallback.applied | boolean | 是否启用了 fallback 或补充预测策略 |
| Data.meta.fallback.strategy | string | fallback 策略标识,用于说明当前结果采用的兼容预测路径 |
| Data.meta.fallback.requested_year | integer | 请求中传入的目标预测年份 |
| Data.meta.fallback.effective_year | integer | 实际用于匹配分数线或历史样本的有效年份 |
| Data.meta.fallback.requested_major_name | string | 请求中传入的专业名称 |
| Data.meta.fallback.effective_major_name | string | 实际命中的参考专业名称;若未命中稳定专业样本则为空 |
| Data.meta.fallback.reason | string | 采用兼容预测路径时返回稳定原因码;未采用时为空 |
| Data.disclaimer | string | 免责声明 |
| DataStatus.RequestParameter | string | 实际业务参数,不包含凭据。 |
| DataStatus.RequestId | string | 本次请求的关联标识。 |
| DataStatus.NoDataReason | string | 有效请求无可评估结果时返回稳定原因;有结果时省略。 |
| Data.meta.requested_year | integer | 请求中传入的年份。 |
| Data.meta.prediction_year | integer | 当前实际模型预测周期。 |
| Data.meta.rank_source | string | 实际位次来源;missing 表示本次模型没有采用可用位次。 |
| Data.meta.effective_rank | integer | 实际参与评估的位次;未采用时为 null。 |
| 业务状态码 | 业务状态码解释 | 备注 |
|---|---|---|
| 100 | 正常返回 | |
| 501 | 参数错误 | 缺少省份、科类、appkey,或成绩与位次均缺失,以及重复、冲突、类型或范围无效时返回;HTTP 422。 |
| 502 | 请求频率受限 | 请降低请求频率 |
| 503 | APPKEY 过期或订单失效 | 请前往开发者中心确认订单有效期 |
| 504 | APPKEY 错误 | 请检查传递的 APPKEY 是否正确 |
| 505 | 超出调用次数 | 当前 APPKEY 已达到订单调用上限 |
| -9 | 预测失败或服务处理异常 | 预测依赖失败使用 HTTP 503,超时或不可达使用 HTTP 504,内部错误使用 HTTP 500;机器状态说明具体类别。 |
| 字段 | 类型 |
|---|---|
| Data.predictions[].plan_coverage.ratio | number / null |
| Data.predictions[].plan_coverage.matched_plan_rows | integer / null |
| Data.predictions[].plan_coverage.covered_plan_total | integer / null |
| Data.predictions[].plan_coverage.school_plan_total | integer / null |
| Data.predictions[].fallback_path.reason | string / null |