中项网API关键词搜索自动化实操：从参数构造到批量采集

做招投标与工程信息采集这一行的，对中项网应该都不陌生。它聚合了大量工程拟建项目、招标公告、采购信息、中标结果等数据，算是企业做商机挖掘、市场调研时的高频数据源。但这个平台的信息量一大，问题也跟着来了：每天靠人工在网页上输入关键词、翻页、复制、粘贴，一个关键词可能要刷好几页，几十个关键词轮下来，半天时间就没了，而且很容易漏掉当天的更新。把关键词搜索通过 API 接口程序化、自动化，是很多做信息采集的团队都会走的一条路。

这篇文章就围绕“中项网 API + 关键词搜索”这条主线，从需求拆解、接口准备、实操流程到问题排查，完整过一遍。适合三类人看：一是做招投标信息采集的开发者，二是想给团队搭一套商机监控脚本的运营或产品同学，三是刚开始接触 RESTful 接口、想找个真实场景练手的朋友。文章里所有代码和流程都是基于常见实践整理的，具体字段名、限流参数以你拿到的接口文档为准，但思路和坑位基本通用。

1. 需求拆解：为什么要把关键词搜索搬到 API 上

1.1 中项网数据在业务链条里的位置

中项网这类平台，本质上是一个工程与采购信息的聚合入口。上游是各级业主单位、招标代理机构发布的公告，下游是需要跟踪这些信息的企业——做工程总包的、做设备供应的、做原材料贸易的，都靠这类平台发现新项目、判断市场走向。

在业务链条里，这些信息往往不是“看一次就完”，而是要长期盯。比如一家做钢结构的企业，关心的关键词可能是“钢结构”“厂房”“体育馆”；一家做水处理的企业，关键词可能是“污水处理”“供水工程”“管网改造”。关键词背后是具体的商机，漏掉一条，可能就漏掉一个几十万甚至上百万的潜在项目。

所以，中项网这类平台的角色不是一个“新闻网站”，而是一个商机雷达。雷达能不能全天候开机、能不能按需扫描，直接关系到业务团队能不能比别人早一步发现机会。这就引出了把关键词搜索 API 化的原始动力。

1.2 人工搜索的三个核心痛点

手动搜中项网，短期用没问题，但一旦关键词超过十个，或者要求每天定时跟进，痛点就很明显。

第一是效率低。一个关键词从输入、点击搜索到逐条点开看详情，平均下来至少一两分钟，如果有分页，时间还要翻倍。十个关键词就是半小时起步，而且这半小时里人基本干不了别的。如果还要把结果整理成表格发给同事，时间成本更高。

第二是容易漏。搜索结果每天在变，昨天搜到的和今天搜到的可能完全不同。人工靠记忆去对比“哪些是新出现的”，几乎不可能做到，漏掉一两条关键公告是常有的事。特别是那种正文里才提到关键词、标题看不出来的项目，人工翻页的时候很容易直接略过。

第三是难以沉淀。网页上看到的信息，复制到 Excel 里还能用，但要按项目类型、地区、发布时间做结构化统计，就非常吃力。人工采集的数据格式五花八门，后期清洗成本很高，更别提做趋势分析了。

1.3 API 化之后能换来的实际收益

把搜索流程 API 化，上面三个痛点都能得到比较直接的解决。

程序化搜索，一个关键词的请求耗时通常在几百毫秒到一两秒之间，十个关键词也就是几秒钟的事，而且可以挂在定时任务里每天自动跑。同样的人力，可以覆盖几十倍的关键词量。

程序化对比，更容易实现增量识别。把每次搜索到的项目编号或标题存下来，跟历史结果做差集，新出现的自然就浮出来了。这一步在人工场景下几乎没法做，但在代码里就是一个集合运算的事。

程序化存储，可以让每条数据按统一字段落库。后期要按地区、金额、时间筛选，一个 SQL 就搞定了。积累几个月之后，甚至可以分析出哪些关键词出项目多、哪个地区市场活跃，这些都是人工操作做不到的。

这三条收益，本质上都是把“人盯网页”变成“程序盯接口”，人的精力省下来去做判断和跟进，而不是做复制粘贴。

2. 调用前的准备工作：账号、鉴权与接口约定

2.1 获取 API 凭证与权限开通

中项网的 API 通常不是注册账号就自动有的，一般需要找平台方申请数据接口权限，或者购买相应的数据服务套餐。申请通过后，会拿到一组凭证，最常见的是 app_key / app_secret 或者 token。这两样东西的重要性等同于你账号的钥匙，别往代码仓库里明文提交，也别在群里随手发。

从常见实践来看，接口鉴权有两种主流方式：

一种是请求头带 token，调用方通过登录接口换取一个有时效的访问令牌，后续请求都在 Header 里带上，过期后再重新换取。

另一种是签名鉴权，把 app_key、app_secret、时间戳、请求参数按约定规则拼接，做 MD5 或 HMAC 签名，每次请求把签名带过去，服务端校验通过才放行。

这两种方式没有绝对的好坏。token 方式实现简单，适合内部系统；签名方式安全性更高，但需要仔细阅读签名规则。常见的坑是参数排序不一致、时间戳格式不统一，导致签名始终对不上。

2.2 理解接口的通用约定

拿到接口文档后，建议先把几个通用约定过一遍，不要急着写代码：

• 基础地址（Base URL）：所有接口共用的域名前缀，后面跟着具体路径。
• 请求方式：关键词搜索这类查询接口，一般用 GET 或 POST。GET 适合参数简单、长度短的场景，POST 适合参数多、带复杂条件组合的场景。
• 数据格式：目前主流是 JSON，少数老接口是 XML。JSON 的话，需要确认返回嵌套结构，方便后续解析。
• 字符编码：一定要确认是 UTF-8。这一点对中文关键词尤其重要，后面我会专门讲编码踩坑。
• 限流规则：接口通常会限制单位时间内的请求次数，比如每秒几次、每天几次。文档里写的限流阈值就是红线，超了轻则报错，重则封禁 IP 或账号。

建议在正式开发前，先用接口文档里提供的示例请求，用 Postman 或 curl 手动调通一次，确认凭证有效、返回结构符合预期，再开始写代码。这一步能过滤掉大量“代码没问题但权限没开通”的假故障。

2.3 用 Python 搭一个最简请求骨架

环境建议用 Python 3.8+，依赖库用 requests，足够覆盖绝大多数场景。先安装依赖：

bash复制pip install requests

然后写一个最简请求骨架：

python复制import requests
import hashlib
import time

BASE_URL = "https://api.example.com/v1/project/search"
APP_KEY = "your_app_key"
APP_SECRET = "your_app_secret"


def build_sign(params: dict, timestamp: str) -> str:
    # 常见签名规则：参数按 key 排序，拼接后加 secret，再做 MD5
    items = sorted(params.items())
    raw = "&".join(f"{k}={v}" for k, v in items) + "&secret=" + APP_SECRET
    return hashlib.md5(raw.encode("utf-8")).hexdigest()


def search(keyword: str, page: int = 1, page_size: int = 20) -> dict:
    timestamp = str(int(time.time()))
    params = {
        "app_key": APP_KEY,
        "keyword": keyword,
        "page": page,
        "page_size": page_size,
        "timestamp": timestamp,
    }
    params["sign"] = build_sign(params, timestamp)

    resp = requests.get(BASE_URL, params=params, timeout=10)
    resp.raise_for_status()
    return resp.json()


if __name__ == "__main__":
    data = search("污水处理")
    print(data)

这个骨架里，签名函数和搜索函数分开写，后面如果要加新的接口，直接复用 build_sign 就行。有一个细节必须注意：签名时用的参数集合，必须跟实际请求的参数集合完全一致。任何一端多了一个字段或者少了一个字段，签名都会失败，这是新手最容易踩的坑。

3. 关键词搜索的完整实操流程

3.1 构造搜索请求：关键词、分页与筛选条件

搜索接口的核心参数，通常包含这几个维度。

关键词（keyword）是核心入参。这里要特别注意，中项网这类平台的关键词匹配，有的只匹配标题，有的是标题加正文全文匹配，两种模式搜出来的结果数量差异非常大。全文匹配适合找隐蔽信息，但噪音也大；标题匹配比较精准，但可能漏掉一些正文才提到关键词的公告。具体用哪种，看接口文档怎么定义。如果没有明确说明，建议先用一个已知的项目做验证——拿一条确定存在的结果标题，截取其中一段去搜，能搜到就说明匹配逻辑跟你预期一致。

分页参数（page / page_size）控制结果集大小。一次接口请求返回的数据量有限，通常单页 10 到 50 条。page 从 1 开始，page_size 建议不要超过文档允许的最大值，否则可能直接报参数错误。分页还有一个细节：如果搜索结果是按发布时间倒序排列的，那么翻页过程中，新数据可能插入到最前面，导致下一页跟上一页出现重叠或漏项。这个问题的最佳解法不是调分页，而是用时间范围过滤，让每次请求的数据窗口固定下来。

筛选条件（region / industry / date_range 等）也很实用。中项网数据通常带有地区、行业、发布时间等属性，按需筛掉不相关的，能显著降低结果噪音。比如你是做浙江市场的，搜索时就加上地区条件过滤掉外省项目，后面清洗数据的成本会小很多。

一个可参考的请求构造示例：

python复制def search_with_filter(keyword: str, region: str = "", date_from: str = "", date_to: str = ""):
    params = {
        "keyword": keyword,
        "page": 1,
        "page_size": 50,
        "region": region,
        "date_from": date_from,
        "date_to": date_to,
    }
    # 拼签名、发请求、返回 JSON
    ...

3.2 响应数据的解析与字段说明

接口返回的 JSON 结构，不同平台差异不小，但大差不差会包含这几层：

json复制{
  "code": 0,
  "message": "success",
  "data": {
    "total": 356,
    "page": 1,
    "page_size": 20,
    "list": [
      {
        "id": "P202501010001",
        "title": "某市污水处理厂扩建工程招标公告",
        "region": "浙江省杭州市",
        "industry": "环保",
        "publish_time": "2025-01-10 09:30:00",
        "url": "https://example.com/detail/xxx",
        "summary": "项目总投资约1.2亿元，建设内容包括..."
      }
    ]
  }
}

写解析代码时，建议把关键字段抽出来转成结构化对象，而不是直接拿原始字典到处用。比如用 dataclass 定义一条项目记录：

python复制from dataclasses import dataclass


@dataclass
class ProjectInfo:
    project_id: str
    title: str
    region: str
    industry: str
    publish_time: str
    url: str
    summary: str

    @classmethod
    def from_dict(cls, item: dict):
        return cls(
            project_id=item.get("id", ""),
            title=item.get("title", ""),
            region=item.get("region", ""),
            industry=item.get("industry", ""),
            publish_time=item.get("publish_time", ""),
            url=item.get("url", ""),
            summary=item.get("summary", ""),
        )

这样做的理由是：接口字段如果后续有调整，只需要改一处映射逻辑；同时程序里其他模块面对的是统一的 ProjectInfo，而不是一堆格式不一的字典。

解析时还要养成一个习惯：所有字段用 .get() 且带默认值，不要直接 item["title"]。因为接口返回偶尔会缺字段，一旦缺了，下标访问直接抛 KeyError，整个循环就崩了。用 .get() 即使字段缺失也只是拿到空字符串，程序还能继续跑，日志里也能记录下来后续排查。

3.3 多关键词批量搜索与去重策略

实际业务里，很少只搜一个关键词。常见做法是维护一个关键词清单，循环调用搜索接口，把结果合并到同一个数据集。这个流程看起来简单，但有两个细节需要处理。

第一个是请求间隔。即使平台的限流阈值比较宽松，也不建议循环里不加任何间隔地猛刷。稳妥的做法是在每次请求之间加一个 0.5 到 1 秒的 sleep，或者用一个简单的令牌桶控制请求速率。宁可慢一点，也不要为了几分钟的提速把账号搭进去。

第二个是去重。同一个项目可能同时命中多个关键词。比如一个污水处理厂项目，既命中“污水处理”，也命中“管网改造”，两个关键词都搜索到它，直接合并就会出现重复记录。去重键建议用项目编号 id，它是唯一标识；如果没有 id，可以用“标题+地区+发布时间”组合作为去重键。

去重逻辑可以很简单，维护一个集合即可：

python复制seen = set()
all_projects = []

for kw in keyword_list:
    page = 1
    while True:
        data = search(kw, page=page, page_size=50)
        items = data["data"]["list"]
        if not items:
            break
        for item in items:
            pid = item["id"]
            if pid in seen:
                continue
            seen.add(pid)
            all_projects.append(ProjectInfo.from_dict(item))
        page += 1
        time.sleep(0.5)

print(f"去重后共 {len(all_projects)} 条项目")

注意这里的翻页终止条件，除了 list 为空之外，还应该判断当前页是否超过总页数。有的接口在超出页码时不是返回空 list，而是返回最后一页的重复数据，这时候就会陷入死循环。安全写法是用 total 和 page_size 计算总页数：

python复制total = data["data"]["total"]
total_pages = (total + page_size - 1) // page_size
if page > total_pages:
    break

这里的除法取整逻辑，是保证任何 total 值下都能正确计算页数的关键，尤其是数据总量不能被 page_size 整除时，最后一页不能丢。

4. 高频问题与排查技巧实录

4.1 鉴权失败、限流与封禁

鉴权失败是最常见的第一道坎。症状通常是返回 code 为 401 或类似“sign error”“invalid token”的提示。排查路径从三个方向入手。

第一，确认 app_key 和 app_secret 有没有复制完整。很多平台生成的 secret 末尾有特殊字符，复制时容易丢，尤其是从 PDF 文档里复制，格式更容易出问题。

第二，核对签名规则。常见坑是参数集合不一致、排序规则不对、secret 拼接位置不对。建议把参与签名的原始字符串打出来，人工一行行对。我自己的习惯是先在代码里 print 原始拼接串，确认无误后再测正式请求。

第三，确认时间戳。很多签名算法会把时间戳纳入计算，并且只允许几分钟内的偏差。如果服务器时间不准，或者时间戳单位是毫秒但算法要求秒，都会导致签名校验失败。这种情况下，先 date 看一下系统时间，再用在线时间戳工具核对一下。

限流和封禁是另一个高频问题。请求过于频繁，接口会返回 429 或者提示“请求过于频繁”。这时候不要继续重试，先停下来，等限流窗口过去。持续硬顶的话，可能触发更严格的封禁策略，那就得不偿失了。

我的建议是，把接口返回的状态码和响应体完整记录到日志里。排查问题时，日志里有没有请求记录、服务端返回了什么，往往比代码逻辑更容易定位问题。

4.2 中文编码与关键词匹配的坑

中文关键词搜索，最经典的坑有两个。

一个是请求编码。虽然接口约定是 UTF-8，但某些平台的服务端仍可能存在兼容问题，对 GET 请求的中文参数处理得不规范。如果直接传中文发现搜不到结果，试试把 keyword 做一次 URL 编码再传，或者改用 POST + JSON body 的方式提交。用 requests 库时，GET 请求的 params 里的中文会自动编码，一般没问题，但如果你是自己拼 URL，就一定要用 urllib.parse.quote 处理。

另一个是关键词本身的选择。我们以为的关键词跟平台索引里的分词方式可能不一样。比如你搜“钢结构厂房”，平台可能是按“钢结构”“厂房”两个词分别匹配，也可能只能匹配完整短语。验证方法很简单：先用一个确定存在的结果标题，截取其中几个词分别搜索，看哪个词能搜到，就能反推平台的匹配规则。实测下来，很多平台的标题搜索对短语的匹配支持并不好，拆成短词搜反而更稳，代价是需要在前端做一次结果合并。

4.3 网络超时、连接中断与重试策略

调用外部 API 一定会遇到网络问题，这不是代码写得对不对的问题，而是概率问题。中项网接口偶尔也会出现响应慢、超时的情况，所以请求必须设置 timeout，不能无限等下去。

推荐的写法是：连接超时 5 秒，读取超时 10 秒，总共 15 秒内没响应就放弃本次。同时加一个指数退避重试，第一次重试等 2 秒，第二次 4 秒，第三次 8 秒，最多重试三次。超过三次还失败，就把任务标记为失败，等下一轮定时任务再处理，而不是卡在那里反复请求。

python复制import time
import requests
from requests.adapters import HTTPAdapter


def request_with_retry(url, params, max_retries=3):
    session = requests.Session()
    session.mount("https://", HTTPAdapter(max_retries=0))

    for attempt in range(max_retries):
        try:
            resp = session.get(url, params=params, timeout=(5, 10))
            resp.raise_for_status()
            return resp.json()
        except (requests.Timeout, requests.ConnectionError) as e:
            wait = 2 ** attempt
            print(f"第 {attempt + 1} 次请求失败，{wait} 秒后重试：{e}")
            time.sleep(wait)

    raise RuntimeError("重试三次仍失败")

这里要特别提醒一点：重试只对“连接失败”“超时”这类异常生效。如果接口正常返回了业务错误码，比如参数错误、鉴权失败，那就不要重试，重试一万次结果也一样。把业务错误和网络错误分开处理，是很重要的一个习惯。

4.4 数据完整性校验

搜索做完、数据落库之后，还有一个容易被忽略的环节：校验数据完整性。接口返回的 total 和实际拉取到的条数是否一致，是判断有没有漏数据的直接指标。

实操中我会在每次批量搜索结束后，把每个关键词的 total、实际获取条数、去重后的条数都打印出来，对比一下。如果某个关键词的 total 是 300 条，但程序只拉到 200 条就停下来了，说明翻页逻辑有问题。最常见的两种情况：一是 page_size 超过接口上限被静默截断，二是翻页时上一页和下一页之间有间隙，这通常是因为搜索结果在翻页过程中发生了变化。解决办法就是我前面说的时间窗口固定法，让搜索结果在一个确定的时间范围内保持稳定。

5. 进阶扩展：从单次搜索到可持续监控

5.1 定时任务与增量更新

关键词搜索接口化之后，最自然的下一步是做成每天的定时任务。比如每天上午 9 点跑一次，把前一天到当天的增量数据拉下来。

增量更新的核心是时间边界。建议在请求参数里固定传入 date_from 和 date_to，让每次请求的数据窗口是确定且不重叠的。比如当天跑的脚本，date_from 设为昨天 00:00:00，date_to 设为当前时间，这样即使某个时段漏跑了，补跑也只是重放一个固定窗口，不会重复太多。

定时任务本身，Linux 上用 crontab 就够了，没必要一上来就上 Celery 或 Airflow 这类重框架。一个简单的 crontab 配置例子：

bash复制0 9 * * * cd /opt/project-scraper && /usr/bin/python3 run_daily.py >> logs/run.log 2>&1

等业务复杂度上来，比如需要多任务编排、失败重试、任务状态可视化，再考虑上调度平台也不迟。前期用最简单的方案跑起来，比前期搭一个大而全的架构实际得多。

5.2 结果推送与告警

数据拉下来了，怎么让人及时看到？常见做法有三种。

邮件推送：把当天新增的项目整理成表格或 HTML 邮件，定时发给业务同事。适合需要完整明细的场景。

群机器人推送：通过群机器人 webhook 推送新增项目摘要，适合需要快速响应的团队。每天新增项目数量超过阈值时推送到群，完整明细每天一封邮件归档，这样群里不会太吵，邮件又有据可查。

数据库加报表：存入数据库，业务人员通过报表工具自己查，适合做长期统计分析。

推送内容里，除了标题和链接，最好带上项目编号。业务同事在群里看到编号，就能快速回到平台核对，效率会高很多。推送格式上，我习惯把地区、发布时间、标题、链接放在一条消息里，超过五条就截断，提醒去看完整邮件。

5.3 数据质量维护与长期运营

接口搜索做得再顺，也要考虑长期运营中的数据质量问题。

第一个是关键词库的维护。关键词不是一成不变的，业务方向调整、市场热点变化，都会产生新的关键词。建议把关键词清单单独存成配置文件或数据库表，而不是硬编码在脚本里。这样运营同事也可以自己维护，不用每次都找开发改代码。关键词表里除了关键词本身，还可以加一个启用状态、最后搜索时间、命中数量等字段，方便监控每个关键词的产出。

第二个是历史数据的回溯。如果发现某个关键词漏跑了一段时间，需要回溯补数据，可以把 date_from 的窗口调大，重新跑一遍。注意补数据期间，新增量的处理要错开时间窗口，避免重复。

第三个是接口字段变化。平台升级接口、调整字段名，是早晚的事。建议在解析层做一层适配，并定期检查接口返回的字段是否跟预期一致。这个适配层其实就是前面说的 ProjectInfo.from_dict，接口变一次，改一处，比全文搜索替换舒服太多。

第四个是存储与保留策略。搜索到的数据会越积越多，数据库不能只进不出。建议按项目发布时间做分区或者定期归档，半年以上的数据可以挪到冷存储，避免主表越来越大、查询越来越慢。对于已经确认不感兴趣的项目类型，也可以打标记，后续搜索直接过滤，减少噪音。

写在最后的实操体会

最后说点实际体会。中项网 API 关键词搜索这个需求，技术难度其实不高，本质上就是“请求-解析-存储-推送”的常规流程。但真正让这套东西值钱的，不是代码写得有多花哨，而是关键词选得准不准、增量判断得对不对、推送及时不及时。

我自己踩过最大的坑，是在一开始把大量时间花在了“接口怎么调”上，等接口跑通了才发现，真正费劲的是后面的去重逻辑和关键词维护。所以给刚开始做这件事的朋友一个建议：先把一个关键词的完整链路走通——搜索、解析、入库、推送，再考虑扩展成几十个关键词的批量任务。链路通了，剩下的都是复制和优化。

另一个体会是，接口文档里如果写了限流规则，一定要当回事。我见过有团队为了赶数据，把请求频率调到文档上限的两倍，结果账号被封了两天，业务同事天天来问数据为什么断了。稳一点，慢一点，跑得久才是王道。做信息采集这行，拼的从来不是一时的速度，而是能不能稳定地把数据喂给业务。