埃里克 Eric干招投标和项目管理这行的人，应该都体会过每天被信息轰炸的感觉。中项网这类平台把全国各地的拟在建项目、招标公告、采购信息都聚合到了一起，信息全是真的全，但信息多也是真的多。我最早是每天打开网站，输入关键词，一页一页手动翻，后来维护的关键词一多，一个上午就耗在里面了，还总担心漏掉新公告。后来我下决心把中项网的 API 接起来，用代码自动做关键词搜索，替代人工翻页，效果是肉眼可见的——以前一上午的信息搜集量，现在一次脚本调用几十秒就处理完了。这篇文章就把我从申请凭证、调通接口到落地定时搜索的全过程拆开讲清楚，顺便把那些文档里不会写的坑都列出来，给同样在跟信息打交道的人一个可直接照做的参考。
1. 为什么需要 API 做关键词搜索：场景与痛点
1.1 招投标信息获取的现状与痛点
先说说业务场景。不管是做工程施工、设备供应还是软件服务的企业，日常都离不开招投标信息。这些信息来源渠道很多，有各级公共资源交易中心、政府采购网、企业官网，分散得厉害。中项网这类平台的价值在于把碎片化信息聚合起来，做了初步清洗和分类，用户只需要在一个地方检索就行。
但聚合平台也有它的烦恼：信息量实在太大。一个稍微宽泛点的关键词，比如"污水处理"，当天新增的招标公告可能就是几十甚至上百条。如果只依赖人工在网页端搜索，每天至少得投入专人花两三个小时去翻页、筛选、复制、整理，而且这种方式有几个天生缺陷。
第一个缺陷是容易漏。人工翻阅一旦状态不好，或者信息更新混在页面上，很容易漏掉某条关键公告。要知道一条合适的招标信息可能就是几百万的生意，漏掉是真肉疼。第二个缺陷是重复劳动。搜索关键词一多，比如你同时维护十几组关键词，同样的翻页动作要重复十几次，大量时间花在了机械操作上。第三个缺陷是数据沉淀差。网页上看到的信息，复制到 Excel 里就算记录，但字段不全，后续想按时间、地区、金额维度分析，基本无从下手。
这些问题本质上都指向同一个结论：人工操作已经跟不上信息更新的速度了。而 API 的出现，就是把"人盯着屏幕找"变成"程序自动去查"，而且查完之后数据结构化、可存储、可分析，这是质的区别。
1.2 中项网 API 能解决什么问题
中项网的 API 提供的是结构化数据访问能力，你只需要按接口规范传入搜索条件，就能拿到 JSON 或 XML 格式的结果集，包含标题、发布时间、来源、地区、项目阶段等字段。基于这套能力，可以做几类很实际的事情。
第一类是自动检索。把过去人工输入的每一个关键词转化为 API 请求参数，程序循环调用接口，把所有关键词的结果汇总回来。这样最直接的收益是效率提升，原来一个上午的工作量，现在几分钟跑完。
第二类是实时监控。配合定时任务，每隔一定时间自动拉取一次最新数据。比如每天早上八点执行一次，上班就能看到前一天夜间发布的新公告。这个对于投标决策来说很重要，很多项目的报名截止时间很紧，早发现一天，准备标书的时间就宽裕一天。
第三类是数据沉淀与二次分析。API 返回的字段是规整的，直接入库之后，可以做周报统计、竞争对手中标分析、某地区市场活跃度分析等。这些深度分析在纯网页操作模式下几乎不可能实现，因为根本没有结构化数据可以做处理。
1.3 适合谁用
我把这个方案的实际使用人群梳理了一下，大概有这么几类：投标专员和市场信息员，他们是最直接的受益者，能把自己的双手从高频刷新网页中解放出来；销售团队负责人，需要快速掌握区域内新释放的项目机会；企业内部 IT 或信息化人员，需要把招投标信息接入自己的 CRM 或项目管理系统；还有做行业数据服务的团队，把 API 作为数据源做二次加工。
当然，它不是万能的。如果你只是偶尔查一条信息，那打开网页搜索就够了，没必要搭一套程序。API 的价值在"高频、批量、持续"这三个词的场景下才会完全释放出来。这也是我后面所有方案设计的出发点。
需要模型API调用？ 免费领10W Token，多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. 中项网 API 的方案设计与接口理解
2.1 RESTful API 的请求模型
在用代码写第一行之前，我建议先花半小时把 API 的基本模型理解透，不然后面排错会很痛苦。中项网的 API 目前采用的是典型的 RESTful 风格接口，底层走 HTTP 协议，请求和响应都是标准格式。这类接口的基本逻辑你掌握一次，以后接任何同类平台都通用。
一个完整的 RESTful 请求包含这么几个要素：接口地址（Endpoint）、请求方法（Method）、请求头（Headers）、查询或提交参数（Parameters）。
接口地址通常是一个 URL，比如 https://api.zhongxiangwang.com/v1/search 这种格局，具体域名以你申请到的文档为准。请求方法中，关键词搜索这类读操作主要是 GET，部分平台也有 POST 方式提交复杂查询条件的情况，按文档来就行。请求头里最关键的是鉴权信息，一般是一个 Authorization 字段，值为你申请的 API Key，作用就是告诉服务端"我是合法用户"。查询参数则是你要传给服务端的搜索条件，比如关键词、页码、数量。
这个模型你可以理解成去图书馆借书：请求方法是"我要查询"，查询参数是"我要找哪类书"，API Key 是借书证，响应数据就是图书馆管理员给你找出来的书单。每部分各司其职，缺一个都办不成事。
2.2 关键词搜索接口的核心参数
关键词搜索接口的返回结构通常比较规整，但真正决定搜索效果的是请求参数的设置。我根据使用经验，把最核心的参数整理了一下，具体字段名以中项网开放平台文档为准，但逻辑是通用的。
keyword 或者 q，就是你的核心搜索词。这个参数最直接，传什么就搜什么。要注意的是，平台通常是按标题和正文做匹配，不是简单的标题精确匹配，所以参数值的构造很讲究，我在后面专门用一节来讲关键词策略。
page 和 page_size，分别表示页码和每页条数。这是分页参数，API 不会一次性把所有结果返回给你，而是一页一页吐。page_size 一般有上限，常见的是 20 到 50，超过上限会有参数校验错误。
date_range 或者 start_time、end_time，控制返回结果的发布时间范围。这个参数非常关键，尤其在定时增量拉取的场景下，必须靠时间条件来限定"只取最近新增的数据"。如果接口支持相对时间，比如 today、24h、7d，那就更方便。
region 或者 province、city，按地区过滤。这个是招投标行业的刚需，因为我只需要本省的项目，全国的信息对我没有意义。在参数层面多用一次过滤，返回结果的有效率会大幅提升。
type 或者 category，按信息类型过滤。中项网这类平台一般有拟在建项目、招标公告、中标结果、采购信息等几个大类，不同业务阶段关注的信息类型不同，接口通常支持按类型筛选。
2.3 分页、限流与频率控制
分页策略是整个调用过程中最容易踩坑的地方，也是很多人写着写着就把账号封了的原因。说几个我实测下来的结论。
第一，不要一口气把全部分页拉完。有些搜索结果可能有上千条，你写一个循环从第1页拉到第50页，每页间隔不到一秒钟，这种短时间高频请求最容易触发限流。一套理智的做法是：单次搜索只看前 5 到 10 页，因为招投标信息的时效性很强，如果 10 页内还没有你要的东西，说明这条搜索词路径本身有问题，而非信息藏在深处。
第二，每翻一页加一点延时。在循环里装一个 time.sleep(0.5) 或者 1，把请求节奏降下来。有人可能会觉得 0.5 秒太慢，但你想想，一天 500 次请求和一天 5000 次请求，在平台那边的风险画像完全是两回事。在同类平台上我见过不少因为调用过猛导致 API Key 被临时停用的案例，恢复起来很麻烦。
第三，留意接口返回的限流响应头。很多规范一点的 API 都会在响应头里带上 X-RateLimit-Limit、X-RateLimit-Remaining、X-RateLimit-Reset 这几个字段，分别表示周期内总配额、剩余配额、配额重置时间。在代码里读取剩余配额，当值很低时主动降速，比等到被拒绝后再处理要主动得多。
429 和 529 这两个状态码要格外注意。429 表示请求太频繁，已经到了限流阈值；529 表示服务端本身过载，属于平台侧临时性的问题。两者都需要做重试处理，但重试策略不同：429 更适合等较长的时间再继续，529 可以短时间快速重试。我习惯用"递增退避"策略，第一次失败等 2 秒，第二次等 4 秒，第三次等 8 秒，最多退避到 60 秒就不再退了。
3. 实操全流程：从申请凭证到首次搜索
3.1 获取访问凭证
进入中项网开放平台或开发者中心，用平台账号登录，在控制台里找到"应用管理"，创建一个新的应用。创建时一般会让你填写应用名称、使用场景这些基本信息，按实际情况填写就行。创建完成后，系统会生成一对凭证：App Key（或叫 API Key）和 App Secret。
这里有个容易犯的错：以为 API Key 可以直接拿来当密码用。实际上，更规范的多是"密钥对"模式——请求时用 API Key 标识身份，用 App Secret 做签名计算。签名算法的常见做法是：把请求参数按字典序排序，拼接 App Secret 后进行 MD5 或 HMAC-SHA256 计算，最终得到一个 sign 参数传给服务端。如果你的接口文档里有"签名"这两个字，就去文档里找具体的签名算法说明，千万别拿 Secret 明文直接拼到 URL 里，那等于把密码写在门框上。
申请完凭证后，建议先在管理后台确认有没有 IP 白名单功能。如果平台支持白名单，把自己的服务器或本机固定 IP 填进去，能够有效防止凭证泄露后被异地调用。
3.2 构造第一个搜索请求并解析响应
拿到凭证后，我建议先用一个最基础的工具做接口连通性测试，Postman 或者 Apifox 都行，不要一上来就写代码。先把接口地址、请求方法、参数填好，点发送，看看返回什么。这一步可以快速确认三件事：凭证有没有生效、参数格式对不对、返回结构长什么样。
一个典型的请求是这样的：
http复制GET /v1/search?keyword=污水处理&page=1&page_size=20&type=tender HTTP/1.1
Host: api.zhongxiangwan.com
Authorization: Bearer YOUR_API_KEY
响应 JSON 的结构通常是这样的，具体字段名以文档为准：
json复制{
"code": 200,
"message": "success",
"data": {
"total": 86,
"items": [
{
"id": "123456",
"title": "某市污水处理厂一期工程招标公告",
"publish_time": "2025-01-10 09:30:00",
"region": "浙江省",
"type": "tender",
"url": "https://...",
"summary": "项目概况：..."
}
]
}
}
先看最外层的 code 字段，200 表示成功，非 200 就是出错了。出错时 message 字段会给出原因，比如参数校验失败的信息。然后关注 data.total，这是命中结果总数，用来判断关键词设置得宽还是窄。最后解析 data.items 列表，每一条就是一条具体的项目或公告数据。
3.3 写入本地文件或数据库的落库方案
接口调通了之后，下一步就是考虑结果怎么存。如果只是临时查一次，存成 JSON 文件或者 CSV 文件就够了。但如果你的目标是长期监控，我建议直接落数据库，SQLite 就完全够用，不用一上来就上 MySQL 这种重型数据库。
SQLite 的好处是零部署、单文件、随手可用。建一张简单的表，字段对应 API 返回的 id、title、publish_time、region、type、url，再加一个本地的 created_at 写入时间字段。id 字段最好加唯一索引，这是去重的关键，后面细说。
sql复制CREATE TABLE search_results (
id TEXT PRIMARY KEY,
title TEXT,
publish_time TEXT,
region TEXT,
type TEXT,
url TEXT,
summary TEXT,
created_at TEXT DEFAULT (datetime('now', 'localtime'))
);
把第 3.2 节的解析结果循环写入这张表，你会发现一个额外的好处：数据积攒到一定数量后，可以按地区、类型、发布时间做分析，比如哪个月的项目释放最多、哪个地区的成功率更高，这些分析对业务决策很有价值。
3.4 一个完整的 Python 示例
推荐用 Python 做这件事，环境简单、库生态齐全，requests 库就能覆盖绝大部分需求。下面这段代码是我验证过可用的核心逻辑，你根据自己的凭证和字段名调整后就能跑。
python复制import requests
import time
import json
API_KEY = "你的API Key"
BASE_URL = "https://api.zhongxiangwan.com/v1/search"
HEADERS = {
"Authorization": f"Bearer {API_KEY}",
"Content-Type": "application/json",
}
def search_by_keyword(keyword, page=1, page_size=20, date_range="today"):
params = {
"keyword": keyword,
"page": page,
"page_size": page_size,
"date_range": date_range,
}
resp = requests.get(BASE_URL, params=params, headers=HEADERS, timeout=10)
resp.raise_for_status()
return resp.json()
def main():
keywords = ["污水处理", "智慧园区", "光伏发电"]
all_items = []
for kw in keywords:
print(f"正在搜索: {kw}")
data = search_by_keyword(kw)
items = data.get("data", {}).get("items", [])
all_items.extend(items)
time.sleep(0.5) # 控制请求频率
print(f"共获取 {len(all_items)} 条数据")
# 解析入库逻辑省略，可按3.3节建表后写入
if __name__ == "__main__":
main()
这段代码里有两个细节值得注意。第一，time.sleep(0.5) 不是随便加的，是控制请求频率的关键，如果你同时跑很多关键词，这个延时能帮你避免触发限流。第二，resp.raise_for_status() 是用来快速暴露 HTTP 状态码异常的，方便早期排查问题。跑通这个最小流程，后面做定时任务只需要在这个基础上加循环和调度逻辑。
4. 关键词搜索策略与高级用法
4.1 关键词的构造与组合
很多人在 API 调通后，第一个直觉是"把原来网页上搜的词直接搬过来用"，但实际搜索效果往往不尽如人意。原因是网页搜索和 API 搜索虽然核心逻辑一致，但 API 的结果更加原始，没有网页端的智能化扩展和排序优化，所以关键词本身的质量直接决定结果质量。
单一的宽泛词效果通常不好。比如"工程"这个词，命中量会非常大但精准度极低，充斥大量不相关的项目。好的做法是"名词+业务动作"的组合，比如"污水处理+设备采购""光伏+EPC总承包"。"设备采购""EPC总承包"这类业务动作词能把搜索范围收窄到你真实参与的项目阶段。
另外建议维护一组关键词表，不要写在代码里写死。把关键词放在一个文本文件或者数据库表里，程序启动时读取，这样业务人员可以随时增删关键词，而不需要找你改代码。这看起来是小事，但在实际协作中能省很多沟通成本。
4.2 排除词、时间范围与地区过滤
关键词搜索真正的进阶玩法是组合过滤条件。我在实际使用中发现一个规律：加一个地区过滤，结果有效率提升至少 50%。如果你只做本地业务，比如只做浙江省的工程，那在参数里固定 region=浙江省，比之后在结果里人工筛要高效得多。
时间范围参数也值得好好用。在增量监控场景下，不要用"过去一年"这种大范围，而应该用 date_range=24h 或者自定义的 start_time 与 end_time，每次只拉取距上次任务执行之后新增的数据。这样每次返回的数据量小但精准，处理压力也小。
部分平台还支持排除词或者"不含"逻辑，比如你想搜"污水处理"但不想看到"设备维修"类的内容。如果接口文档里没有直接的排除参数，就在本地做一次文本过滤，根据标题或摘要中的关键词做二次筛选。API 负责粗筛，本地负责精筛，这个双层的过滤逻辑是我自己一直沿用的架构，稳定性很好。
4.3 定时轮询与增量更新
接口调通了，关键词也配好了，接下来要做的是让它每天自动跑，而不是手动去执行脚本。在 Linux 服务器上，crontab 是最简单可靠的方案。比如每天早上八点执行一次：
bash复制0 8 * * * cd /opt/search_project && /usr/bin/python3 main.py >> logs/search.log 2>&1
如果你在 Windows 环境，用任务计划程序也能达到同样效果。这里有个小技巧：第一次执行时先把历史数据全量拉一遍，之后每次只增量拉取时间范围内的数据，配合 id 去重，就能做到既不漏数据也不重复入库。
定时轮询的频率怎么定？我的经验是中项网这类平台的招标公告更新高峰集中在工作日的上午九点到十一点、下午两点到四点。如果做当天就需要响应的业务，建议早中晚各跑一次；如果只是做信息归档，一天一次就够。频率太高既增加限流风险，又会给你自己增加处理垃圾数据的负担。
4.4 结果推送与自动化通知
搜索本身不是目的，让相关的人及时看到结果才是。数据入库之后，加一个推送环节，整个流程就闭环了。最推荐的是企业微信机器人或者钉钉自定义机器人，申请一个 Webhook 地址，把新增的高匹配度结果推送到群里，几十行代码就能搞定。
推送消息的格式建议包含标题、发布时间、地区、原文链接四个字段，不要直接把整段摘要丢进去，群里刷屏会被嫌烦。一个参考模板：
code复制【新招标公告】
标题：某市污水处理厂一期工程招标公告
地区：浙江省
时间：2025-01-10 09:30
链接：https://...
抓取后推送的核心逻辑不复杂：先查库里有没有这条记录的 id，没有就入库并推送，有就跳过。这样既不会漏，也不会重复打扰人。推送环节还有个隐身价值：它让这个工具从"被动查询系统"变成了"主动情报系统"，业务的感知度是完全不同的。
5. 常见问题与排查技巧实录
5.1 鉴权失败与凭证管理
接口调不通，十有七八是鉴权环节出的问题。我把遇到过的情况整理一下，最典型的是 401 Unauthorized，原因基本就三类：API Key 填错、API Key 没有放到正确的请求头位置、IP 不在白名单内。
排查时先做一件事：用 Postman 手动发一次请求，确认同样的参数和凭证在独立工具中能否通。能通则说明代码写法有问题，不能通则说明凭证或配置有问题。这个"最小化排除法"能帮你快速锁定问题范围，而不是在代码里瞎改。
还有一个容易被忽视的问题：API Key 过期。平台通常会给凭证设置有效期，到期后表面上请求还在发，但一直返回 401。建议在代码里对 401 做特殊日志记录，并设置告警提示，不然你可能过了很久才发现这个源已经断了。
5.2 请求被限流的应对策略
限流问题几乎是所有 API 对接者都会遇到的，被限流的表现有两种：一种是返回 429 状态码，一种是返回 200 但内容为空或异常提示。后者更容易被忽视，因为它不报错，但数据其实是空的。
我的应对思路是三级防护。第一级是源头控制，所有循环请求之间加合理的延时，把请求频率总体压在平台限值之下。第二级是退避重试，发现 429 后不要立刻重试，用"指数退避"策略，等 2 秒、4 秒、8 秒依次递增。第三级是崩溃兜底，一个关键词组跑完发现某一页一直失败，记录失败位置，跳过但标记为"待重试"，整个任务跑完后再单独重试这些失败项。
5.3 返回数据为空或字段缺失
接口通了，但搜某些关键词返回为空，这时候先别怀疑平台数据不全，大部分原因是你的过滤条件叠加得太严格。比如你同时限制了地区、类型、时间范围，几个条件一叠，命中数自然趋近于零。
排查顺序是：先只传关键词，看返回总量；再加时间范围，看总量变化；再加地区，看总量变化。逐层叠加，找到是哪一层把结果过滤没了。如果某一层的条件确实找不回数据了，适当放宽，比如从"今天"放宽到"近三天"。
字段缺失的问题也很常见，尤其是 summary 或 url 某些记录可能为空。代码里做字段解析时，不要直接用 item["summary"]，要用 item.get("summary", "") 这种带默认值的写法，否则一条空字段就能让你的整个脚本崩掉。
5.4 编码与乱码问题
中文乱码在 API 对接里几乎必现一次。现象是标题和摘要变成了"鍩庡競"这种乱码，原因大概率是 HTTP 响应内容的字符集没有按照 UTF-8 解码。
requests 库的解码逻辑一般是自动的，但如果服务端返回的响应头里没声明 charset，requests 会用默认的 ISO-8859-1，导致中文乱码。解决办法是手动指定编码：
python复制resp.encoding = "utf-8"
这句代码放在 resp.json() 之前，就能解决大部分乱码问题。还有另一种乱码发生在数据入库后再读取，显示正常但写入时已经是错的，这种情况通常是数据库连接参数没指定 charset，尤其是 MySQL 场景，连接串里要显式加上 charset=utf8mb4。
6. 工程化落地与避坑经验
6.1 数据存储与去重的正确姿势
前面提过用 id 做唯一索引去重，这里展开讲讲。API 返回的每条记录都会有一个唯一 id，但这个 id 有可能在不同接口版本中发生变化，所以我的建议是：如果平台的 id 稳定可靠，就用它做唯一键；如果担心 id 不稳定，就用 title + publish_time 做组合唯一键。
去重的完整逻辑是：每次拉取结果后，先按唯一键查库，已存在的记录直接跳过，不存在的记录才入库。这套逻辑写起来不难，但注意要在入库前统一处理，不要入库后再清重，因为后置去重往往要处理大量历史数据，性能差且容易出错。
数据量积累到一定规模后，建议按月份做分区或者定期归档。一条记录 1KB，一年下来可能就几百 MB，单表还能扛住。但如果你读数据做统计的 SQL 越来越慢，就需要考虑归档了。这个节点不用太早来，但心里要有数。
6.2 日志、失败重试与可观测性
任何自动化系统，如果不做日志和重试，都是定时炸弹。我第一次跑定时任务时就没有日志，结果脚本第三天因为一条脏数据崩了，我过了两天才发现数据断更了，这就是没有可观测性的代价。
现在我的做法是给脚本加两层日志：一层是运行时日志，记录每次调用的时间、关键词、返回条数、异常信息；另一层是结果摘要日志，记录每次任务执行完后新增了多少条数据。运行时日志输出到文件和标准输出，摘要日志可以简单写成一个文本追加，或者直接在运行时日志里 grep。
失败重试的粒度也要注意。整个任务失败后整体重跑是最笨的办法，因为可能只是其中一部分请求失败，整体重跑会把大量已成功的数据再拉一遍。更好的做法是把每个关键词的搜索视为独立子任务，单个子任务失败不影响其他子任务，全部执行完后统一收集失败项重试。
6.3 后续可以怎么扩展
这个项目做到"定时搜索、去重入库、推送通知"这个状态，已经是一个可以长期稳定运行的情报工具了。在此基础上，如果你还有余力，有几个方向值得扩展。
一是加一个简单的统计页面，展示每天新增项目数量、各类型占比、各区域分布。这不需要复杂的可视化工具，用 Flask 或者 FastAPI 写一个简化版后端，配合一个前端表格页面就行。二是做竞品监控。把中标结果也接入进来，定期拉取同行的中标信息，可以分析出竞争对手的活跃区域和业务方向。三是尝试接入语义检索。搜索还是关键词匹配的逻辑，但可以在结果入库后做一个分类模型，自动判断这个项目与你业务的相关程度，进一步降低人工筛选成本。
我自己做过的最有价值的扩展就是把推送从"全量推"改成了"分级推"。高相关度项目推送到主群，中相关度项目推送到备份群，低相关度项目只入库不推送。这个分级逻辑加上各类别的评分规则后，每天需要我人工关注的信息量被压缩到了一个非常舒服的范围。
最后再分享一个小技巧：无论你的查询逻辑多完善，都建议在脚本最外层保留一个手动的"强制全量更新"入口。因为总有一些情况需要你重新拉取某段时间的历史数据，比如某天网络异常导致数据有缺口。有这样一个开关，你在排查问题时就不会被迫修改代码逻辑来迁就特殊情况。API 对接这件事，前期最怕想不明白，后期最怕不稳定，把稳健性想在前头，后面能少熬不少夜。