📖 禾搜开放 API 文档

1. 申请 API Key

1. 打开 禾搜开放平台,注册账号(用户名 + 密码)
2. 登录后填写「应用名称」,点击申请,即可获得 API Key
3. 默认日配额 1000 次调用(申请时可自定义 100 ~ 100000)

2. 认证方式

所有接口都需要携带 API Key,二选一:

方式 A(推荐):请求头

X-API-Key: hk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

方式 B:URL 参数

https://你的域名/api/v1/search?q=农业&key=hk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

请求头示例:

curl "http://localhost:8000/api/v1/search?q=农业" \
  -H "X-API-Key: hk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

3. 接口列表

3.1 搜索

参数	类型	必填	说明
q	string	✅	搜索关键词,如 农业;支持 site:域名 指令(如 site:tjstjs.com,含子域名;site:www.tjstjs.com/show 可带路径),仅 site: 时返回该站整站列表
domain	string	否	域名过滤(等价于 site: 指令,如 www.tjstjs.com;与 site: 同时存在时 site: 优先)
page	int	否	页码,默认 1
per_page	int	否	每页条数,默认 10,最大 50
type	string	否	垂直分类:web / image / doc / video / mall / biz / pan

返回示例:

{
  "ok": true,
  "data": {
    "query": "农业",
    "took": 12,
    "total": 4321,
    "page": 1,
    "pages": 433,
    "results": [
      {
        "title": "农业农村部…",
        "url": "https://www.gov.cn/…",
        "domain": "www.gov.cn",
        "snippet": "…农业…",
        "score": 23.45,
        "fetched_at": "2026-08-09 15:00:00",
        "type": "web"
      }
    ],
    "related": ["乡村振兴", "农业补贴"],
    "related_content": [{"title": "…", "url": "…", "from_kw": "乡村振兴"}]
  },
  "quota": { "daily": 1000, "used_today": 3 }
}

3.2 热词榜

参数	类型	必填	说明
platform	string	否	平台:douyin / toutiao / weibo / baidu / zhihu / douban / ithome / hn / thepaper / ifeng / tieba / tc / ifanr / woshipm;空 = 全部平台合并
limit	int	否	条数,默认 20,最大 50

curl "http://localhost:8000/api/v1/hotwords?platform=douyin&limit=5" \
  -H "X-API-Key: hk_xxx"

{
  "ok": true,
  "data": {
    "platform": "抖音",
    "items": [ {"word": "台风最新消息", "heat": 86832422} ]
  },
  "quota": { "daily": 1000, "used_today": 4 }
}

3.3 站点信息

curl "http://localhost:8000/api/v1/site_config" -H "X-API-Key: hk_xxx"

{
  "ok": true,
  "data": { "name": "禾搜", "desc": "…", "keywords": "…", "url": "https://…" },
  "quota": { "daily": 1000, "used_today": 5 }
}

3.4 查询配额

查看当前 Key 的配额用量、状态、创建时间(不消耗配额)。

4. 各语言调用示例

Python

import requests

KEY = "hk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
url = "http://localhost:8000/api/v1/search"
params = {"q": "农业", "page": 1, "per_page": 10}

r = requests.get(url, params=params, headers={"X-API-Key": KEY})
data = r.json()
if data["ok"]:
    for item in data["data"]["results"]:
        print(item["title"], "-", item["url"])
else:
    print("错误:", data.get("error"))

JavaScript(浏览器 / Node)

const KEY = "hk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx";

fetch("http://localhost:8000/api/v1/search?q=农业", {
  headers: { "X-API-Key": KEY }
})
  .then(r => r.json())
  .then(data => {
    if (data.ok) {
      data.data.results.forEach(item => console.log(item.title, item.url));
    }
  });

PHP

<?php
$key = "hk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx";
$ch = curl_init("http://localhost:8000/api/v1/search?q=" . urlencode("农业"));
curl_setopt($ch, CURLOPT_HTTPHEADER, ["X-API-Key: " . $key]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$data = json_decode(curl_exec($ch), true);
if ($data["ok"]) {
    foreach ($data["data"]["results"] as $item) {
        echo $item["title"] . " - " . $item["url"] . "\n";
    }
}
?>

5. 错误码

HTTP	说明
200	成功,返回 ok: true
400	参数错误(如缺少 q、platform 无效)
401	缺少 / 无效的 API Key
403	Key 已停用,或开放 API 已关闭
429	今日配额已用尽,次日 0 点自动恢复
500	服务器内部错误

6. 常见问题

• 配额什么时候重置? 每天 0 点自动重置今日用量。
• Key 泄露了怎么办? 到开放平台删除该 Key 重建,旧 Key 立即失效。
• 配额不够用? 联系管理员调整(后台可批量查看/调整)。
• 返回的中文是乱码? 接口统一 UTF-8 编码,请检查你的请求/解析库编码设置。
• 结果里的 jump_url? 开放 API 不返回中转跳转地址,直接使用 url 字段即可。