企业工商信息查询API参数深度解析：请求细节与字段最佳实践
企业工商信息查询接口可以依据企业名称关键词返回匹配的工商登记信息。本文不讨论业务抽象概念只聚焦于参数细节、返回结构和工程落地时容易踩的坑帮助你在 10 分钟内完成接入并在生产环境中稳定运行。适用场景该接口适合需要快速获取企业基本工商信息的系统典型场景包括企业背景调查在合作前核验目标公司是否存续、法定代表人与准备地是否一致。供应链风控对供应商的企业名称做匹配查询确认经营范围是否覆盖所需品类。内部系统补全仅掌握企业简称时通过关键词匹配得到完整企业全称和统一社会信用代码。对账与核验将业务系统中的企业名称与工商登记信息做一致性比对减少手工录入误差。需要特别说明的是该接口一次请求只返回前 5 条最匹配结果适用于“确认已知企业”的场景不适合做全量企业搜索或模糊批量拉取。接口能力边界请求方式GET请求地址https://v1.apizero.cn/api/company-searchQPS 限制5 次/秒超出后可能被限流。数据缓存数据来自天眼查工商数据库接口侧缓存 6 小时因此短时间内反复查询同一关键词返回数据不会实时变化。返回条数最多 5 条按上游匹配评分降序排列。数据覆盖包括企业全称、法人、准备资本、统一社会信用代码、经营范围、准备地、联系方式等核心字段但不含司法风险、经营异常等动态信息。理解这些边界能够帮助你在设计系统时合理预期避免将实时性要求附加在缓存数据上。参数详解与鉴权name查询参数name是唯一必填参数类型为字符串表示企业名称关键词。参数规则如下项目约束参数名name是否必填是类型string长度2~50 个字符示例腾讯科技、阿里巴巴这里有两处容易忽略的细节最短长度是 2如果传入单个字符如“腾”接口会返回参数错误。不要试图用单字做全库匹配。最长长度是 50超过 50 个字符应按规则截断或拒绝。实际调用时建议将输入框长度限制在 50 字符以内并在服务端再做一次校验。此外name参数支持的是关键词匹配并非精确匹配。例如传入“腾讯科技”可能返回“广州腾讯科技有限公司”和“腾讯科技深圳有限公司”等结果需要在业务侧根据name字段再次筛选。X-API-Key请求头X-API-Key是可选请求头用于传递 API Key不传时使用匿名额度适合本地调试。建议在生产环境中显式传入并放在环境变量或密钥管理服务中不要硬编码在代码里。请求头格式X-API-Key: your_api_key_herecurl 请求示例下面是一个完整的 curl 调用将关键词替换为你的目标名称并将YOUR_API_KEY替换为真实 Keycurl -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: servicetencent.com, logo: https://img5.tianyancha.com/logo/lll/..., match_field: 股东信息, history_names: } ] } }响应顶层字段字段类型说明codeint业务状态码0表示成功msgstring状态描述request_idstring请求唯一标识排查问题时需要记录dataobject核心数据data对象字段类型说明keywordstring本次查询的关键词回显方便日志核对totalint上游匹配到的总数但接口只返回前 5 条listarray企业信息列表最多 5 个元素list数组中的核心字段字段类型示例说明idlong1466562059企业唯一标识namestring广州腾讯科技有限公司企业全称english_namestringGuangzhou Tencent Technology Co., Ltd.英文名称可能为空legal_personstring邬红波法定代表人reg_capitalstring7000万人民币准备资本注意是字符串credit_codestring91440101327598294H统一社会信用代码company_org_typestring有限责任公司企业类型reg_statusstring存续登记状态存续/注销/吊销等reg_locationstring广州市海珠区...准备地址establish_timestring2014-12-31成立日期格式为 YYYY-MM-DDbusiness_scopestring电子;通信...经营范围多个条目用分号分隔categorystring研究和试验发展国民经济行业分类citystring广州市城市districtstring海珠区区县phonestring020-81167888联系电话可能为空emailstringservicetencent.com电子邮箱可能为空logostringhttps://...企业 logo 地址可能为空match_fieldstring股东信息命中字段名称用于调试匹配来源history_namesstring空字符串曾用名可能为空对接时注意reg_capital返回的是展示格式的字符串不要直接转成数值establish_time只有日期部分没有时区phone、email、logo等字段可能缺省读取时需要做空值判断。常见错误与处理错误场景表现处理建议name长度小于 2HTTP 400业务 code 非 0前端限制最小输入长度后端再次校验name长度大于 50HTTP 400截断或拒绝请求并返回明确提示关键词无匹配结果HTTP 200total为 0list为空数组换更精确的关键词或用企业全名二次检索请求频率超过 QPS 5 次/秒HTTP 429 或限流提示本地加锁、队列或使用令牌桶平滑请求X-API-Key无效鉴权失败HTTP 401检查密钥是否正确确认在有效期内网络超时请求无响应设置超时时间并实现指数退避重试工程化最佳实践1. 始终对中文关键词做 URL 编码虽然 curl 和现代 HTTP 客户端能自动处理中文但在拼接 URL 时仍建议显式编码。JavaScript 使用encodeURIComponentPython 使用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, headersheaders, paramsparams, timeout10) 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 result3. 控制并发避免击中 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 e5. 记录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
)
