首页/资讯中心/详情

企业工商信息查询API调用限制解析：QPS、缓存与数据边界

企业工商信息查询API调用限制解析：QPS、缓存与数据边界
📅 发布时间：2026/7/21 7:51:50

适用场景与核心能力

企业工商信息查询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为空数组），不代表该企业不存在，可尝试更换关键词或通过统一社会信用代码查询其他接口。

请求参数与鉴权

参数名位置类型必填说明
nameQuerystring是企业名称关键词，2~50字符
X-API-KeyHeaderstring否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": "股东信息" } ] } }

核心字段说明

字段类型含义注意事项
codeint业务状态码，0为成功非0时须根据msg排查
data.totalint该关键词的匹配总数（最大为上游截断值）仅作参考，不代表实际企业数
data.list[].namestring企业全称相对较权威，但存在简称匹配情况
data.list[].credit_codestring统一社会信用代码唯一标识，可用于二次校验
data.list[].legal_personstring法定代表人可能为空（如分公司）
data.list[].reg_capitalstring准备资本，含币种存在“万人民币”“万美元”等格式
data.list[].reg_statusstring经营状态（存续、注销、吊销等）更新频率低，以缓存时间为准
data.list[].match_fieldstring匹配到的字段名帮助理解为何该记录出现在结果中

常见错误与处理

错误现象可能原因处理方法
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为空）上游数据未收录属于正常边界，业务代码应容错

工程化注意事项

  1. 缓存策略：由于API自身有6小时缓存，业务端不宜再长时间缓存同一数据，建议设置TTL为30分钟至1小时，避免数据滞后。

  2. 并发控制：单机多线程/协程场景下，使用带速率限制的HTTP客户端。例如Go中可用rate.Limiter，Python可用requests+time.sleep(0.21)保证每秒<=5请求。

  3. 降级设计：当API出现429或5xx错误时，应退化为本地缓存数据或异步重试队列，避免主流程阻塞。

  4. 数据校验：返回的credit_code可使用国家标准校验位算法（ISO 7064:1983, MOD 11-2）进行初筛，但最终真实性需通过官方渠道确认。

  5. 字段使用基线：reg_capital为字符串，转金额时需去除“万人民币”等后缀并进行标准化转换。establish_time格式为YYYY-MM-DD，可直接解析。

  6. 兼容性：history_names字段可能为空字符串，返回的list长度为0~5，业务代码应优雅处理空数组。

参考文档

  • 企业工商信息查询 API 文档
  • 原始文档

（文中接口地址及参数以官方文档为准，示例数据仅供演示。）