• API 功能

    • 基于 LightGBM 梯度提升框架,融合院校分数线、高校与专业录取分数线、分段位次等多源异构数据;
    • 采用 Isotonic 回归进行预测校准,保证录取概率输出稳定可信;
    • 自动生成冲/稳/保梯度建议,并提供分差最小值与中位数等统计指标;
    • 返回 SHAP 特征贡献明细,透明解释模型决策依据;
    • 支持省份过滤、白名单院校、Top-N 控制等高级筛选能力;
    • 支持 Query 与 JSON 组合入参,便于脚本与后端系统同时调用;
    • 底层数据实时更新,同步最新高考年份信息;
    • 接口默认 HTTPS,兼容 Apple ATS,配合多节点 CDN 提供高可用服务。
    • 全国多节点 CDN 部署;
    • 接口极速响应,多台服务器构建 API 接口负载均衡。
    • 接口调用状态与状态监控
  • 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}}

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

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

    请求参数(POST 请求参数以 application/x-www-form-urlencoded 格式、文件流以 formdata 格式传递,具体可参见下方示例代码)

    参数名 参数类型 是否必须 默认值 备注
    appkey string YOUR_APPKEY 付费后获取的 APPKEY,可通过 Query (?appkey=) 提供
    province string N/A 考生所在省份,与历年分数线数据保持一致
    subject_type string N/A 科类/选科:理科、文科、物理类、历史类、综合等
    score number N/A 考生裸分(0-750)
    rank int N/A 考生全省位次,可为空(为空时结合分段位次推断)
    batch string 本科批 报考批次,目前支持普通本科批次
    top_n int 50 返回院校数量上限,范围 1-200
    include_explanation bool true 是否返回 SHAP 特征贡献解释
    prefer_local bool false 是否在排序时优先本省院校
    college_provinces array(string) N/A 按院校所在省份过滤,留空则不过滤;Query 方式可多次传值,格式 ["江苏", "上海"]
    target_colleges array(string) N/A 指定院校名单,仅对名单内院校预测

    返回参数

    参数名 参数类型 备注
    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[].evidence object 关键信息:recent_3y_min_score、score_gap、province_line_gap、is_985、is_211、is_dual_class、college_rank 等
    Data.predictions[].shap_explanation object SHAP 解释信息,含 base_probability、predicted_probability、top_features
    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 bool 是否启用本省优先排序
    Data.meta.college_provinces array(string) 请求中用于过滤院校省份的列表
    Data.meta.model_version string 模型版本号
    Data.disclaimer string 免责声明
  • 接口 HTTP 响应标准状态码

    状态码 状态码解释 备注
    200 接口正常响应 业务状态码参见下方 接口自定义状态码
    403 / 429 请求频率超限 CDN 层通过 IP 请求频率智能判断,一般不同 IP 高频请求不会触发此状态码。
  • 接口自定义状态码

    自定义状态码 自定义状态码解释 备注
    100 正常返回 可通过判断此状态码断言接口正常返回。
    -1 请求失败 请求处理请求失败。
    501 参数错误 请检查您传递的参数个数以及参数类型是否匹配。
    429 / 502 请求频率受限 一般建议同一个 IP 每秒请求不超过 5 次 (QPS<=5),我们不限制同一个 key 的请求总次数,但当单位时间内同一个 IP 请求次数过多,或 AI CDN 判定为恶意抓取数据、流量攻击等异常时,CDN 会返回此状态码,请适当降低请求频率。如有特殊大并发请求场景需求,可联系我们添加白名单处理。
    503 APPKEY 权限超限/订单到期 请至开发者中心检查您的 APPKEY 是否到期或是否权限超限。
    504 APPKEY 错误 请检查传递的 APPKEY 是否为开发者中心获取到的值。
    505 请求的次数超出接口限制 请检查对应接口是否有请求次数限制以及您目前的接口请求剩余次数。
    900 接口内部响应错误 接口服务可用性 (SLA) 为 99.8069%,如获取到此状态码请邮件联系我们。
  • 请求示例代码
    curl --location --request POST 'https://api.gugudata.com/ai/admission/predict?appkey={{appkey}}' \
    --header 'Content-Type: application/x-www-form-urlencoded' \
    --data-urlencode 'appkey=YOUR_APPKEY' \
    --data-urlencode 'province=N/A' \
    --data-urlencode 'subject_type=N/A' \
    --data-urlencode 'score=N/A' \
    --data-urlencode 'rank=N/A' \
    --data-urlencode 'batch=本科批' \
    --data-urlencode 'top_n=50' \
    --data-urlencode 'include_explanation=true' \
    --data-urlencode 'prefer_local=false' \
    --data-urlencode 'college_provinces=N/A' \
    --data-urlencode 'target_colleges=N/A'
    CURL *curl;
    CURLcode res;
    curl = curl_easy_init();
    if(curl) {
      curl_easy_setopt(curl, CURLOPT_CUSTOMREQUEST, "POST");
      curl_easy_setopt(curl, CURLOPT_URL, "https://api.gugudata.com/ai/admission/predict?appkey={{appkey}}");
      curl_easy_setopt(curl, CURLOPT_FOLLOWLOCATION, 1L);
      curl_easy_setopt(curl, CURLOPT_DEFAULT_PROTOCOL, "https");
      struct curl_slist *headers = NULL;
      headers = curl_slist_append(headers, "Content-Type: application/x-www-form-urlencoded");
      curl_easy_setopt(curl, CURLOPT_HTTPHEADER, headers);
      const char *data = "appkey=YOUR_APPKEY&province=N/A&subject_type=N/A&score=N/A&rank=N/A&batch=本科批&top_n=50&include_explanation=true&prefer_local=false&college_provinces=N/A&target_colleges=N/A";
      curl_easy_setopt(curl, CURLOPT_POSTFIELDS, data);
      res = curl_easy_perform(curl);
    }
    curl_easy_cleanup(curl);
    var myHeaders = new Headers();
    myHeaders.append("Content-Type", "application/x-www-form-urlencoded");
    var urlencoded = new URLSearchParams();
    urlencoded.append("appkey", "YOUR_APPKEY");
    urlencoded.append("province", "N/A");
    urlencoded.append("subject_type", "N/A");
    urlencoded.append("score", "N/A");
    urlencoded.append("rank", "N/A");
    urlencoded.append("batch", "本科批");
    urlencoded.append("top_n", "50");
    urlencoded.append("include_explanation", "true");
    urlencoded.append("prefer_local", "false");
    urlencoded.append("college_provinces", "N/A");
    urlencoded.append("target_colleges", "N/A");
    var requestOptions = {
      method: 'POST',
      headers: myHeaders,
      body: urlencoded,
      redirect: 'follow'
    };
    fetch("https://api.gugudata.com/ai/admission/predict?appkey={{appkey}}", requestOptions)
      .then(response => response.text())
      .then(result => console.log(result))
      .catch(error => console.log('error', error));
    var client = new RestClient("https://api.gugudata.com/ai/admission/predict?appkey={{appkey}}");
    client.Timeout = -1;
    var request = new RestRequest(Method.POST);
    request.AddHeader("Content-Type", "application/x-www-form-urlencoded");
    request.AddParameter("appkey", "YOUR_APPKEY");
    request.AddParameter("province", "N/A");
    request.AddParameter("subject_type", "N/A");
    request.AddParameter("score", "N/A");
    request.AddParameter("rank", "N/A");
    request.AddParameter("batch", "本科批");
    request.AddParameter("top_n", "50");
    request.AddParameter("include_explanation", "true");
    request.AddParameter("prefer_local", "false");
    request.AddParameter("college_provinces", "N/A");
    request.AddParameter("target_colleges", "N/A");
    IRestResponse response = client.Execute(request);
    Console.WriteLine(response.Content);
    package main
    import (
      "fmt"
      "strings"
      "net/http"
      "io/ioutil"
    )
    func main() {
      url := "https://api.gugudata.com/ai/admission/predict?appkey={{appkey}}"
      method := "POST"
      payload := strings.NewReader("appkey=YOUR_APPKEY&province=N/A&subject_type=N/A&score=N/A&rank=N/A&batch=本科批&top_n=50&include_explanation=true&prefer_local=false&college_provinces=N/A&target_colleges=N/A")
      client := &http.Client {
      }
      req, err := http.NewRequest(method, url, payload)
      if err != nil {
        fmt.Println(err)
      }
      req.Header.Add("Content-Type", "application/x-www-form-urlencoded")
      res, err := client.Do(req)
      defer res.Body.Close()
      body, err := ioutil.ReadAll(res.Body)
      fmt.Println(string(body))
    }
    OkHttpClient client = new OkHttpClient().newBuilder()
      .build();
    MediaType mediaType = MediaType.parse("application/x-www-form-urlencoded");
    RequestBody body = RequestBody.create(mediaType, "appkey=YOUR_APPKEY&province=N/A&subject_type=N/A&score=N/A&rank=N/A&batch=本科批&top_n=50&include_explanation=true&prefer_local=false&college_provinces=N/A&target_colleges=N/A");
    Request request = new Request.Builder()
      .url("https://api.gugudata.com/ai/admission/predict?appkey={{appkey}}")
      .method("POST", body)
      .addHeader("Content-Type", "application/x-www-form-urlencoded")
      .build();
    Response response = client.newCall(request).execute();
    var settings = {
      "url": "https://api.gugudata.com/ai/admission/predict?appkey={{appkey}}",
      "method": "POST",
      "timeout": 0,
      "headers": {
        "Content-Type": "application/x-www-form-urlencoded"
      },
      "data": {
                "appkey":'YOUR_APPKEY', 
                "province":'N/A', 
                "subject_type":'N/A', 
                "score":N/A, 
                "rank":N/A, 
                "batch":'本科批', 
                "top_n":50, 
                "include_explanation":true, 
                "prefer_local":false, 
                "college_provinces":N/A, 
                "target_colleges":N/A
      }
    };
    $.ajax(settings).done(function (response) {
      console.log(response);
    });
    #import <Foundation/Foundation.h>
    dispatch_semaphore_t sema = dispatch_semaphore_create(0);
    NSMutableURLRequest *request = [NSMutableURLRequest requestWithURL:[NSURL URLWithString:@"https://api.gugudata.com/ai/admission/predict?appkey={{appkey}}"]
      cachePolicy:NSURLRequestUseProtocolCachePolicy
      timeoutInterval:10.0];
    NSDictionary *headers = @{
      @"Content-Type": @"application/x-www-form-urlencoded"
    };
    [request setAllHTTPHeaderFields:headers];
    NSMutableData *postData =
    [[NSMutableData alloc] initWithData:[@"appkey=YOUR_APPKEY" dataUsingEncoding:NSUTF8StringEncoding]];[postData appendData:[@"&province=N/A" dataUsingEncoding:NSUTF8StringEncoding]];[postData appendData:[@"&subject_type=N/A" dataUsingEncoding:NSUTF8StringEncoding]];[postData appendData:[@"&score=N/A" dataUsingEncoding:NSUTF8StringEncoding]];[postData appendData:[@"&rank=N/A" dataUsingEncoding:NSUTF8StringEncoding]];[postData appendData:[@"&batch=本科批" dataUsingEncoding:NSUTF8StringEncoding]];[postData appendData:[@"&top_n=50" dataUsingEncoding:NSUTF8StringEncoding]];[postData appendData:[@"&include_explanation=true" dataUsingEncoding:NSUTF8StringEncoding]];[postData appendData:[@"&prefer_local=false" dataUsingEncoding:NSUTF8StringEncoding]];[postData appendData:[@"&college_provinces=N/A" dataUsingEncoding:NSUTF8StringEncoding]];[postData appendData:[@"&target_colleges=N/A" dataUsingEncoding:NSUTF8StringEncoding]];
    [request setHTTPBody:postData];
    [request setHTTPMethod:@"POST"];
    NSURLSession *session = [NSURLSession sharedSession];
    NSURLSessionDataTask *dataTask = [session dataTaskWithRequest:request
    completionHandler:^(NSData *data, NSURLResponse *response, NSError *error) {
      if (error) {
        NSLog(@"%@", error);
      } else {
        NSHTTPURLResponse *httpResponse = (NSHTTPURLResponse *) response;
        NSError *parseError = nil;
        NSDictionary *responseDictionary = [NSJSONSerialization JSONObjectWithData:data options:0 error:&parseError];
        NSLog(@"%@",responseDictionary);
        dispatch_semaphore_signal(sema);
      }
    }];
    [dataTask resume];
    dispatch_semaphore_wait(sema, DISPATCH_TIME_FOREVER);
    import requests
    url = "https://api.gugudata.com/ai/admission/predict?appkey={{appkey}}"
    payload = 'appkey=YOUR_APPKEY&province=N/A&subject_type=N/A&score=N/A&rank=N/A&batch=本科批&top_n=50&include_explanation=true&prefer_local=false&college_provinces=N/A&target_colleges=N/A'
    headers = {
      'Content-Type': 'application/x-www-form-urlencoded'
    }
    response = requests.request("POST", url, headers=headers, data = payload)
    print(response.text)
    require "uri"
    require "net/http"
    url = URI("https://api.gugudata.com/ai/admission/predict?appkey={{appkey}}")
    https = Net::HTTP.new(url.host, url.port);
    https.use_ssl = true
    request = Net::HTTP::Post.new(url)
    request["Content-Type"] = "application/x-www-form-urlencoded"
    request.body = "appkey=YOUR_APPKEY&province=N/A&subject_type=N/A&score=N/A&rank=N/A&batch=本科批&top_n=50&include_explanation=true&prefer_local=false&college_provinces=N/A&target_colleges=N/A"
    response = https.request(request)
    puts response.read_body
    import Foundation
    var semaphore = DispatchSemaphore (value: 0)
    let parameters = "appkey=YOUR_APPKEY&province=N/A&subject_type=N/A&score=N/A&rank=N/A&batch=本科批&top_n=50&include_explanation=true&prefer_local=false&college_provinces=N/A&target_colleges=N/A"
    let postData =  parameters.data(using: .utf8)
    var request = URLRequest(url: URL(string: "https://api.gugudata.com/ai/admission/predict?appkey={{appkey}}")!,timeoutInterval: Double.infinity)
    request.addValue("application/x-www-form-urlencoded", forHTTPHeaderField: "Content-Type")
    request.httpMethod = "POST"
    request.httpBody = postData
    let task = URLSession.shared.dataTask(with: request) { data, response, error in
      guard let data = data else {
        print(String(describing: error))
        return
      }
      print(String(data: data, encoding: .utf8)!)
      semaphore.signal()
    }
    task.resume()
    semaphore.wait()
    /*
     * GuGuData API Request Node.js Demo
     * 咕咕数据 API Node.js 请求 DEMO
     * 咕咕数据,专业的数据提供商,提供全面的数据接口 API,并提供专业全面的数据接口、商业数据分析。
     * 让数据成为您的生产原料。
     * https://www.gugudata.com
     */
    
    /* 咕咕数据 API 请求 DEMO ***开始***/
    // 导入相关类库
    var request = require("request");
    var api_host = "https://api.gugudata.com";
    var api_path = "/ai/admission/predict?appkey={{appkey}}"; // todo: 注意修改请求对应的 API 接口
    // todo: 注意修改构造请求参数
    var data = {
     appkey:'YOUR_APPKEY', province:'N/A', subject_type:'N/A', score:N/A, rank:N/A, batch:'本科批', top_n:50, include_explanation:true, prefer_local:false, college_provinces:N/A, target_colleges:N/A
    };
    var options = {
        'method': "POST",
        'url': api_host + api_path,
        'headers': {
            'Content-Type': 'application/x-www-form-urlencoded'
        },
        form: data
    };
    // 发送网络请求
    var requestGuGuData = request(options, (error, response) => {
        if (error) throw new Error(error);
        console.log("********接口响应返回 JSON 数据********");
        console.log(JSON.parse(response.body));
        requestGuGuData.end();
        console.log("********接口响应结束********");
    });
    /* 咕咕数据 API 请求 DEMO ***结束***/
    <?php
    $curl = curl_init();
    curl_setopt_array($curl, array(
      CURLOPT_URL => "https://api.gugudata.com/ai/admission/predict?appkey={{appkey}}",
      CURLOPT_RETURNTRANSFER => true,
      CURLOPT_ENCODING => "",
      CURLOPT_MAXREDIRS => 10,
      CURLOPT_TIMEOUT => 0,
      CURLOPT_FOLLOWLOCATION => true,
      CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
      CURLOPT_CUSTOMREQUEST => "POST",
      CURLOPT_POSTFIELDS => "appkey=YOUR_APPKEY&province=N/A&subject_type=N/A&score=N/A&rank=N/A&batch=本科批&top_n=50&include_explanation=true&prefer_local=false&college_provinces=N/A&target_colleges=N/A",
      CURLOPT_HTTPHEADER => array(
        "Content-Type: application/x-www-form-urlencoded"
      ),
    ));
    $response = curl_exec($curl);
    curl_close($curl);
    echo $response;
  • 常见问题 Q&A

    • Q: 数据请求有缓存吗?

      A: 我们为所有数据请求提供实时响应。对于定期更新的数据,我们在其更新周期内实施缓存策略,以优化性能。

    • Q: 如何保证请求时 key 的安全性?

      A: 我们建议将对 API 的请求操作放置在您的应用程序后端。这样,前端请求只与您的后端服务交互,确保了更高的安全性和易于维护的架构。

    • Q: 接口可以用于哪些开发语言?

      A: 我们的接口支持所有能进行网络请求的开发语言,便于在各类项目中快速整合数据。

    • Q: 接口的性能可以保证吗?

      A: 我们的接口后台使用与商业级项目相同的架构,保证了稳定且高效的性能。您可以通过访问测试接口了解更多性能信息。

  • 服务协议以及服务免责声明

    用户应当充分阅读 服务协议 以及 服务免责声明 ,用户购买与使用咕咕数据 API 服务亦视为接受本协议。

  • 技术支持

    • 技术支持邮箱: support@gugudata.com
    • 微信客服: 客服链接

业务相关接口推荐

高考教育信息智能助手
  • 高考教育信息智能问答助手
  • 智能问答 / 知识库检索 / 多轮对话
  • 9999元/年限时折扣 4999元/年
查看详情 数据校验更新于 10 小时前
50% 折扣
职业心理测评问卷
  • 职业心理测评问卷 API 服务
  • 心理测评 / 职业测试 / 人格分析
  • 1999元/年限时折扣 999元/年
查看详情 被调用于 8 秒前
50% 折扣
高校评分实时分析与推荐
  • 基于多维度指标对大学进行综合评分与分析
  • 多维度评估 / 专业推荐
  • 1999元/年限时折扣 999元/年
查看详情 数据校验更新于 8 小时前
50% 折扣
稳定提供服务 10 年 全球 QS 世界大学排名数据
  • 详细排名指标和得分信息
  • 全球排名 / 高等教育
  • 1999元/年限时折扣 999元/年
查看详情 数据校验更新于 2 小时前
50% 折扣