X-GORB Search API

1. 接口概述

2. 请求参数规范

2.1 参数详情

2.2 请求示例

https://api.xgorb.cn/API/search.php?q=xgorb&page=1&refresh=1&api_key=你的APIKey

3. 返回参数说明

3.1 公共返回字段

3.2 缓存对象（cache）

3.3 单条搜索结果（results[]）

3.4 返回示例

{
    "status": 200,
    "keyword": "xgorb",
    "page": 1,
    "search_speed": "870ms",
    "result_count": 10,
    "xgorbcollectionsearch_results_count": 10,
    "results": [
        {
            "title": "X-GORB Search",
            "url": "https://so.xgorb.cn/",
            "description": "X-GORB Search是一个由迅风智界（ZephyrtTech）维护开发的安全、无广告的搜索引擎，致力于为用户提供纯净的搜索体验。",
            "domain": "so.xgorb.cn",
            "favicon": "https://favicon.im/zh/so.xgorb.cn",
            "image": "",
            "source": "XGorbCollectionSearch"
        }
    ],
    "cache": {
        "hit": false,
        "key": null,
        "expires_in": 300,
        "message": "已缓存，下次搜索会更快"
    },
    "proxy_used": "直连",
    "refresh": false
}

4. 状态码与错误说明

5. 对接示例代码

<?php
// 替换为从用户中心获取的实际API Key（敏感信息，请勿暴露在前端）
$apiKey = "你的APIKey";
// 搜索关键词，需进行URL编码（处理空格、中文、特殊符号，避免解析失败）
$keyword = urlencode("xgorb");
// 页码（可选，默认1，取值范围1-15，接口会自动修正）
$page = 1;
// 缓存刷新标识（可选，默认0，推荐默认配置提升响应速度）
$refresh = 1;

// 拼接接口请求地址，确保参数格式正确
$requestUrl = "https://api.xgorb.cn/API/search.php?q={$keyword}&page={$page}&refresh={$refresh}&api_key={$apiKey}";

// 初始化cURL请求，适配HTTPS协议
$ch = curl_init();
// 设置请求地址
curl_setopt($ch, CURLOPT_URL, $requestUrl);
// 设置返回结果不直接输出，转为字符串便于解析
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
// 启用HTTPS验证（生产环境必选，保障数据安全，避免api_key泄露）
curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, true);
curl_setopt($ch, CURLOPT_SSL_VERIFYHOST, 2);

// 发送请求并获取响应数据
$response = curl_exec($ch);
// 关闭cURL资源，释放内存
curl_close($ch);

// 解析JSON响应，转为关联数组
$responseData = json_decode($response, true);

// 校验请求是否成功（根据status状态码判断）
if ($responseData['status'] == 200) {
    // 处理搜索结果（示例：循环打印所有结果的标题和链接）
    foreach ($responseData['results'] as $result) {
        echo "结果标题：" . $result['title'] . "<br/>";
        echo "结果链接：" . $result['url'] . "<br/><br/>";
    }
} else {
    // 输出错误信息，便于排查问题（可根据实际需求调整错误处理逻辑）
    $errorMsg = isset($responseData['message']) ? $responseData['message'] : "未知错误";
    echo "请求失败，状态码：" . $responseData['status'] . "，原因：" . $errorMsg;
}
?>

6. 使用规范与安全提示

6.1 使用规范

• 必须传入合法有效的api_key，无密钥请先前往用户中心注册获取，禁止使用非法、他人密钥或空密钥（空密钥会导致请求失败）。
• 调用接口前，务必校验q参数：确保不为空、长度在1-200字符内，避免因参数错误导致400报错，影响对接效率。
• refresh参数建议默认使用0（启用缓存），仅在需要实时获取最新搜索结果时设置为1；频繁设置为1会跳过缓存，降低响应速度，增加接口压力。
• 页码参数无需额外处理超出范围的情况，接口会自动修正为1（小于1）或15（大于15），开发者可直接传入业务所需页码。
• 关键词若包含特殊字符（空格、中文、符号等），必须进行URL编码后传入，否则可能导致接口解析失败，出现“网页解析失败”报错。

6.2 安全提示

• 生产环境必须使用HTTPS协议调用接口，禁止使用HTTP协议传输，避免api_key及请求数据泄露，保障接口调用安全。
• api_key属于敏感信息，请勿泄露给第三方，建议在服务器端存储和调用，避免在前端代码中直接暴露，防止密钥被盗用。
• 请勿恶意调用接口（如高频重复请求、传入非法关键词），否则可能被限制接口使用权限，影响业务正常运行。
• 若遇到“link dead”“网页解析失败”等报错，可检查关键词合法性、链接有效性，或稍后重试接口。

7. 常见问题（FAQ）

Q1：为什么请求返回400错误？

Q2：缓存未命中时，expires_in为什么是300秒？

Q3：results数组中的image字段为什么始终为空？

Q4：调用接口时，Token消耗异常怎么办？

Q5：为什么会出现“link dead”“网页解析失败”报错？

Q6：favicon图标链接无法正常显示怎么办？

8. 技术支持

• 查看用户中心的接口调用日志，排查参数传入、响应异常等基础问题。
• 联系迅风智界（ZephyrtTech）技术支持团队，反馈具体问题、报错信息（如“link dead”）及调用示例，便于快速定位排查。