企业工商信息查询API调用限制解析：QPS、缓存与数据边界
适用场景与核心能力
企业工商信息查询API通过企业名称关键词返回结构化工商数据，广泛应用于以下场景：
- 客户尽职调查：金融机构在开户、授信环节核实企业主体信息（法人、准备资本、经营状态）。
- 供应链风控：采购方对供应商进行资质核验，对比统一社会信用代码与经营范围。
- 竞品情报分析：批量查询同行业企业的准备地、成立时间等公开数据。
- 内部数据补全：CRM或工单系统中根据企业名称自动填充工商字段。
该接口以https://v1.apizero.cn/api/company-search为入口，采用GET方法，支持按企业名称关键词模糊搜索。上游数据源为天眼查权威数据库，经过6小时缓存周期刷新。
调用限制与用量边界
QPS（每秒请求数）限制
- 接口单用户QPS上限为5次/秒。超过此阈值将返回
429 Too Many Requests错误。 - 建议客户端引入限流机制（如令牌桶），避免突发请求导致熔断。
- 批量查询场景中，若企业名称列表超过100条，推荐分批次、间隔200ms以上发送请求。
关键词长度与匹配范围
- 参数
name长度限制为2~50个字符，必须为UTF-8编码。不足2字符或超长时返回400错误。 - 接口返回前5条最匹配结果，按上游评分降序排列。实际匹配精度受关键词切分影响，“腾讯科技”会比“腾讯”获得更精准的前5条。
数据时效性边界
- 工商数据存在6小时缓存，即API返回结果最多有6小时延迟。对于当日变更的工商信息（如法人变更、准备资本变更），建议结合其他实时渠道验证。
- 上游数据源为天眼查，数据覆盖全国工商准备企业，但偏远地区或非正常经营状态的企业可能存在缺失。返回的
reg_status字段可辅助判断（“存续”、“注销”等）。 - 若某次查询无匹配结果（
list为空数组），不代表该企业不存在，可尝试更换关键词或通过统一社会信用代码查询其他接口。
请求参数与鉴权
| 参数名 | 位置 | 类型 | 必填 | 说明 |
|---|---|---|---|---|
name | Query | string | 是 | 企业名称关键词，2~50字符 |
X-API-Key | Header | string | 否 | API密钥；不传则使用匿名额度（有总量限制，以平台文档为准） |
鉴权说明：
- 推荐在HTTP头中传递
X-API-Key以获得独立配额和更高QPS。 - 匿名请求共享公共额度，每日总量有限，生产环境必须携带合法Key。
curl 请求示例
以下示例使用环境变量$APIZERO_API_KEY传递密钥，查询“广州腾讯科技”：
curl -sS \ -X GET \ -H "X-API-Key: $APIZERO_API_KEY" \ "https://v1.apizero.cn/api/company-search?name=广州腾讯科技"若不携带Key，移除-H参数即可：
curl -sS \ -X GET \ "https://v1.apizero.cn/api/company-search?name=阿里巴巴"注意：实际运行时请将
$APIZERO_API_KEY替换为你的真实Key，或直接写入字符串。
返回字段解读
成功响应的JSON结构如下（截取关键字段）：
{ "code": 0, "msg": "成功", "request_id": "mota...", "data": { "keyword": "广州腾讯科技", "total": 20, "list": [ { "id": 1466562059, "name": "广州腾讯科技有限公司", "legal_person": "邬红波", "credit_code": "91440101327598294H", "reg_capital": "7000万人民币", "reg_status": "存续", "establish_time": "2014-12-31", "city": "广州市", "district": "海珠区", "address": "具体街道信息", "phone": "020-81167888", "email": "service@tencent.com", "business_scope": "电子;通信与自动控制技术研究...", "category": "研究和试验发展", "company_org_type": "有限责任公司", "english_name": "Guangzhou Tencent Technology Co., Ltd.", "logo": "https://img5.tianyancha.com/logo/lll/...", "history_names": "", "match_field": "股东信息" } ] } }核心字段说明
| 字段 | 类型 | 含义 | 注意事项 |
|---|---|---|---|
code | int | 业务状态码，0为成功 | 非0时须根据msg排查 |
data.total | int | 该关键词的匹配总数（最大为上游截断值） | 仅作参考，不代表实际企业数 |
data.list[].name | string | 企业全称 | 相对较权威，但存在简称匹配情况 |
data.list[].credit_code | string | 统一社会信用代码 | 唯一标识，可用于二次校验 |
data.list[].legal_person | string | 法定代表人 | 可能为空（如分公司） |
data.list[].reg_capital | string | 准备资本，含币种 | 存在“万人民币”“万美元”等格式 |
data.list[].reg_status | string | 经营状态（存续、注销、吊销等） | 更新频率低，以缓存时间为准 |
data.list[].match_field | string | 匹配到的字段名 | 帮助理解为何该记录出现在结果中 |
常见错误与处理
| 错误现象 | 可能原因 | 处理方法 |
|---|---|---|
HTTP 400：{"code":101,"msg":"参数错误"} | name为空、超长或含非法字符 | 校验参数长度在2~50，URL编码中文 |
HTTP 429：{"code":102,"msg":"请求过于频繁"} | 超过QPS 5/s | 引入限流队列，降低请求频率 |
HTTP 403：{"code":103,"msg":"无效API Key"} | X-API-Key格式错误或已过期 | 检查Key并参照文档重新生成 |
返回code=0但list为空 | 关键词未匹配到数据 | 尝试更短或更精确的名称，或使用工商准备号查询 |
返回字段缺失（如phone为空） | 上游数据未收录 | 属于正常边界，业务代码应容错 |
工程化注意事项
缓存策略：由于API自身有6小时缓存，业务端不宜再长时间缓存同一数据，建议设置TTL为30分钟至1小时，避免数据滞后。
并发控制：单机多线程/协程场景下，使用带速率限制的HTTP客户端。例如Go中可用
rate.Limiter，Python可用requests+time.sleep(0.21)保证每秒<=5请求。降级设计：当API出现429或5xx错误时，应退化为本地缓存数据或异步重试队列，避免主流程阻塞。
数据校验：返回的
credit_code可使用国家标准校验位算法（ISO 7064:1983, MOD 11-2）进行初筛，但最终真实性需通过官方渠道确认。字段使用基线：
reg_capital为字符串，转金额时需去除“万人民币”等后缀并进行标准化转换。establish_time格式为YYYY-MM-DD，可直接解析。兼容性：
history_names字段可能为空字符串，返回的list长度为0~5，业务代码应优雅处理空数组。
参考文档
- 企业工商信息查询 API 文档
- 原始文档
（文中接口地址及参数以官方文档为准，示例数据仅供演示。）