企业工商信息查询API参数深度解析：请求细节与字段最佳实践

企业工商信息查询接口可以依据企业名称关键词返回匹配的工商登记信息。本文不讨论业务抽象概念，只聚焦于参数细节、返回结构和工程落地时容易踩的坑，帮助你在 10 分钟内完成接入并在生产环境中稳定运行。

适用场景

该接口适合需要快速获取企业基本工商信息的系统，典型场景包括：

• 企业背景调查：在合作前核验目标公司是否存续、法定代表人与准备地是否一致。
• 供应链风控：对供应商的企业名称做匹配查询，确认经营范围是否覆盖所需品类。
• 内部系统补全：仅掌握企业简称时，通过关键词匹配得到完整企业全称和统一社会信用代码。
• 对账与核验：将业务系统中的企业名称与工商登记信息做一致性比对，减少手工录入误差。

需要特别说明的是：该接口一次请求只返回前 5 条最匹配结果，适用于“确认已知企业”的场景，不适合做全量企业搜索或模糊批量拉取。

接口能力边界

• 请求方式：GET
• 请求地址：https://v1.apizero.cn/api/company-search
• QPS 限制：5 次/秒，超出后可能被限流。
• 数据缓存：数据来自天眼查工商数据库，接口侧缓存 6 小时，因此短时间内反复查询同一关键词，返回数据不会实时变化。
• 返回条数：最多 5 条，按上游匹配评分降序排列。
• 数据覆盖：包括企业全称、法人、准备资本、统一社会信用代码、经营范围、准备地、联系方式等核心字段，但不含司法风险、经营异常等动态信息。

理解这些边界能够帮助你在设计系统时合理预期，避免将实时性要求附加在缓存数据上。

参数详解与鉴权

name查询参数

name是唯一必填参数，类型为字符串，表示企业名称关键词。

参数规则如下：

这里有两处容易忽略的细节：

1. 最短长度是 2：如果传入单个字符（如“腾”），接口会返回参数错误。不要试图用单字做全库匹配。
2. 最长长度是 50：超过 50 个字符应按规则截断或拒绝。实际调用时，建议将输入框长度限制在 50 字符以内，并在服务端再做一次校验。

此外，name参数支持的是关键词匹配，并非精确匹配。例如传入“腾讯科技”，可能返回“广州腾讯科技有限公司”和“腾讯科技（深圳）有限公司”等结果，需要在业务侧根据name字段再次筛选。

X-API-Key请求头

X-API-Key是可选请求头，用于传递 API Key：

• 不传时使用匿名额度，适合本地调试。
• 建议在生产环境中显式传入，并放在环境变量或密钥管理服务中，不要硬编码在代码里。

请求头格式：

X-API-Key: your_api_key_here

curl 请求示例

下面是一个完整的 curl 调用，将关键词替换为你的目标名称，并将YOUR_API_KEY替换为真实 Key：

curl -sS \ -X GET \ -H "X-API-Key: YOUR_API_KEY" \ "https://v1.apizero.cn/api/company-search?name=腾讯科技"

如果暂时不传 API Key，也可以直接执行：

curl -sS "https://v1.apizero.cn/api/company-search?name=腾讯科技"

注意：curl 命令中的中文参数需要确保终端编码为 UTF-8。在大多数现代终端中可直接使用，但如果在 Windows cmd 下遇到乱码，建议先用工具或脚本进行 URL 编码。

URL 编码后的形式如下：

curl -sS "https://v1.apizero.cn/api/company-search?name=%E8%85%BE%E8%AE%AF%E7%A7%91%E6%8A%80"

返回数据解读

接口返回一个 JSON 数组，其中每个元素对应一种响应状态。正常情况下的示例响应如下：

{ "code": 0, "msg": "成功", "request_id": "mota...", "data": { "keyword": "腾讯科技", "total": 20, "list": [ { "id": 1466562059, "name": "广州腾讯科技有限公司", "english_name": "Guangzhou Tencent Technology Co., Ltd.", "legal_person": "邬红波", "reg_capital": "7000万人民币", "credit_code": "91440101327598294H", "company_org_type": "有限责任公司", "reg_status": "存续", "reg_location": "广州市海珠区新港中路397号...", "establish_time": "2014-12-31", "business_scope": "电子;通信与自动控制技术研究...", "category": "研究和试验发展", "city": "广州市", "district": "海珠区", "phone": "020-81167888", "email": "service@tencent.com", "logo": "https://img5.tianyancha.com/logo/lll/...", "match_field": "股东信息", "history_names": "" } ] } }

响应顶层字段

data对象

list数组中的核心字段

对接时注意：reg_capital返回的是展示格式的字符串，不要直接转成数值；establish_time只有日期部分，没有时区；phone、email、logo等字段可能缺省，读取时需要做空值判断。

常见错误与处理

工程化最佳实践

1. 始终对中文关键词做 URL 编码

虽然 curl 和现代 HTTP 客户端能自动处理中文，但在拼接 URL 时仍建议显式编码。JavaScript 使用encodeURIComponent，Python 使用urllib.parse.quote。

Python 示例：

import requests from urllib.parse import quote url = "https://v1.apizero.cn/api/company-search" headers = {"X-API-Key": "YOUR_API_KEY"} params = {"name": quote("腾讯科技")} resp = requests.get(url, headers=headers, params=params, timeout=10) data = resp.json()

注意：requests库的params参数会自动编码，但如果你直接拼 URL，务必手动编码，否则中文会被浏览器或代理二次解码导致请求失败。

2. 本地缓存优先于重复请求

接口数据有 6 小时缓存，意味着同一关键词在 6 小时内返回结果不会变。在服务端实现一个内存或 Redis 缓存，键为企业名称，值为响应数据，TTL 设为 5 小时，可以显著降低 QPS 压力。

# 简单内存缓存示例 cache = {} def search_company(name): if name in cache: return cache[name] # 调用接口... result = do_request(name) cache[name] = result return result

3. 控制并发，避免击中 QPS 上限

接口 QPS 为 5，如果多个业务线程同时发起请求，很容易触发限流。建议使用信号量或令牌桶：

import threading semaphore = threading.Semaphore(4) # 最多同时 4 个请求 def limited_request(name): with semaphore: return do_request(name)

对于大批量查询需求，应设计为队列逐一消费，而不是并发一次性打满。

4. 设置超时与重试策略

网络问题不可避免，建议将超时设为 5~10 秒，并实现最多 3 次重试。但不要让重试加剧限流，采用指数退避：

import time def request_with_retry(): for i in range(3): try: return do_request() except Exception as e: time.sleep(0.5 * (2 ** i)) raise e

5. 记录request_id便于联调

每次响应的request_id是排查服务器端问题的关键索引。将请求参数、响应code、request_id和耗时写入结构化日志，可以快速定位是参数问题、限流问题还是数据缺失问题。

6. 对返回字段做兼容处理

字段可能缺省或为null，特别是phone、email、logo、history_names。在处理时不要直接访问，应使用 getter 或做空值判断，避免KeyError或空指针异常。

7. 明确匹配字段的业务含义

match_field表示当前企业是通过哪个字段命中的，例如“股东信息”“企业名称”“曾用名”等。在展示给用户时，可以提示”根据股东信息匹配“，增加结果可信度；在调试时也能帮助理解关键词命中逻辑。

参考文档

• 接口文档：https://apizero.cn/aidocs/company-search
• 原始文档：https://apizero.cn/aidocs/company-search/raw.md