API 文档

Base URL：https://api.tmsou.com。所有响应为 JSON（UTF-8）。成功响应形如 { data, meta?, source?, request_id }，失败响应形如 { error: { code, message }, request_id }。反馈问题时请附上 request_id。

快速开始

注册账户，在控制台创建 API Key（只显示一次）。
在请求头携带密钥调用：

curl "https://api.tmsou.com/v1/trademarks/search?q=华为&class=9&limit=5" \
  -H "Authorization: Bearer oti_sk_..."

鉴权

使用 Authorization: Bearer <API Key>（或 X-API-Key 请求头）。不支持把密钥放在 URL 查询参数中。密钥以 oti_sk_ 开头，服务端只保存其哈希；泄露后请在控制台撤销并重新创建。

未携带密钥时，检索与详情接口按 IP 提供少量匿名额度（用于网站体验），不建议在程序中依赖。携带无效或已撤销的密钥会返回 401，不会降级为匿名访问。

检索商标

GET /v1/trademarks/search

参数	说明
`q`	商标名称或申请号。排序：申请号精确 > 名称完全一致 > 前缀 > 短语 > 包含全部词
`scope`	`name`（默认，仅名称/申请号）或 `all`（同时匹配申请人与商品服务）
`applicant`	申请人/注册人/共有人名称，短语匹配（筛选）
`goods`	核定商品/服务名称，短语匹配（筛选）
`class`	尼斯分类 1～45
`group`	类似群代码，4 位数字，如 `0901`
`registered`	`true` 仅有注册公告；`false` 仅无注册公告
`date_from` / `date_to`	申请日期范围，`YYYY-MM-DD`
`sort`	`relevance`（默认）或 `newest`（申请日倒序）
`page` / `limit`	页码从 1 开始；`limit` 1～50，默认 20；最多可翻到前 1,000 条

q、applicant、goods 至少提供一个。每次请求计 1 次调用。

{
  "data": [
    {
      "id": "61893719_32",
      "application_number": "61893719",
      "nice_class": 32,
      "mark_name": "…",
      "applicant_name": "…",
      "agent_name": "…",
      "similar_groups": ["3202"],
      "goods_count": 10,
      "application_date": "2022-01-01",
      "trial_ann_issue": "1790", "trial_ann_date": "2022-05-13",
      "reg_ann_issue": "1802",   "reg_ann_date": "2022-08-13",
      "valid_start_date": "2022-08-14", "valid_end_date": "2032-08-13",
      "first_batch": "2022/1", "last_batch": "2026/3",
      "dataset_version": "cnipa-2026-9"
    }
  ],
  "meta": { "total": 1, "total_relation": "eq", "page": 1, "limit": 20, "took_ms": 12, "timed_out": false, "partial": false, "failed_shards": 0, "dataset_version": "cnipa-2026-9" },
  "source": "源于商标数据开放系统，受商标数据开放系统相关协议、条款约束。…",
  "request_id": "…"
}

total_relation 为 gte 时表示命中超过 10,000 条，total 为下限。列表项不含商品明细与说明文字，详情请调用详情接口。

查询窗口满足 page × limit ≤ 1000，例如每页 20 条最多 50 页，每页 10 条最多 100 页。partial=true 表示仅返回部分结果，原因可能是 timed_out=true 或 failed_shards > 0。此时命中数量与排序可能不完整，即使列表为空也不能判断无匹配，请稍后重试。REST 与 MCP 均提供这些标识。

商标详情

GET /v1/trademarks/{id}

id 为 申请号_类别，如 61893719_32。在列表字段之外返回 goods_items（核定商品/服务明细，含类似群 g与官方商品状态码 s）、goods_services、design_desc、color_desc、disclaimer、coowner_names 等。商品项超过 300 项时只返回前 300 项，goods_count 为实际总数。

按申请号查询

GET /v1/trademarks/by-number/{number}

返回同一申请号/注册号下所有类别的记录（列表字段）。上游超时或分片失败时返回 503，不将部分列表视为完整类别列表。

注册风险评估

POST /v1/trademarks/clearance

{
  "name": "念念留声",          // 拟申请文字，必填
  "classes": [9, 41],          // 尼斯分类 1～5 个，必填
  "groups": ["0901", "4101"],  // 可选：类似群，指定后更准确
  "applicant": "…"             // 可选：申请人全称，其自有在先商标不计为冲突
}

在所选类别中检索完全相同、读音相同（含多音字）、包含/被包含、一字之差、读音相近与外文拼写相近的在先商标；每件按相似度 × 商品重合度 × 推断状态 计算权重并生成模型输入。模型可用时 risk = 1 - estimated_success（0～1），否则合并冲突权重给出参考风险。estimated_success为模型给出的参考注册概率，不是个案注册保证：模型用历史申请（按申请日回放、只看当时已存在的在先商标）的真实结果训练，并在未参与训练的申请上检验；calibration 给出估算所在区间在测试集中的样本数与实际注册率，signals 为模型输入。conflicts 给出每件冲突的类型、状态、重合类似群与理由。每次评估计 1 次调用。

每条召回通路最多评分 candidate_limit_per_query 件（当前 120 件）；candidates_truncated=true 表示存在更多候选未评分，限制同时写入 flags。上游超时、分片失败或响应不完整时返回 503 incomplete_search，不生成风险概率。候选上限不会提升模型精度，也不代表完整冲突排查。

模型指标（测试集 AUC、分档实际注册率）与方法：GET /v1/clearance/methodology（不计调用）。模型估计与历史实际注册率是不同指标，各档可能存在偏差。名称字段存在缺失，名称检索不能召回无名称记录；状态依据公告日期推断，非官方法律状态。估算不含图形近似、最新未公开申请、在先权利与绝对禁用条款，不构成法律意见。

商品 → 类似群

GET /v1/goods/groups?q=咖啡&class=30

根据现有商标的核定商品明细，返回包含该词的商品主要落在哪些类似群，以及示例商品名。每次请求计 1 次调用。

数据集信息

GET /v1/datasets/current

返回数据版本 version、最新批次 latest_batch、记录总数 doc_count 与构建时间。不计调用次数，无需鉴权。

用量查询

GET /v1/usage

需要鉴权。返回套餐、每日额度、今日已用、剩余以及近 30 天每日调用量。不计调用次数。

MCP 接入

MCP 服务地址：https://api.tmsou.com/mcp（Streamable HTTP，JSON 响应）。提供工具 search_trademarks、get_trademark、assess_trademark_risk、get_dataset_info。每次工具调用计 1 次额度；initialize、tools/list 不计。

方式一：OAuth（推荐，Claude 等支持远程连接器的客户端）

在客户端添加自定义连接器并填入服务地址。客户端会自动发现授权服务器（/.well-known/oauth-protected-resource）、动态注册并打开浏览器，你在 OTI 登录并同意后即完成连接。授权会在控制台显示为一条 “OAuth” 密钥，撤销即断开。

方式二：API Key 请求头

{
  "mcpServers": {
    "oti-trademark": {
      "url": "https://api.tmsou.com/mcp",
      "headers": { "Authorization": "Bearer oti_sk_..." }
    }
  }
}

只支持本地 stdio 的客户端可使用 mcp-remote 桥接：

npx -y mcp-remote https://api.tmsou.com/mcp --header "Authorization: Bearer oti_sk_..."

额度与限流

身份	每日额度	速率
免费账户（API Key / OAuth / 登录后网页）	200 次（账户内所有密钥合计）	3 次/秒，突发 10
匿名（按 IP）	100 次	20 次/分钟

额度按北京时间自然日计算，零点重置。响应头 X-RateLimit-Limit / X-RateLimit-Remaining 给出当日额度与剩余。超出返回 429，速率类错误附带 Retry-After。

错误码

HTTP	code	含义
400	`invalid_argument`	参数不合法，`message` 给出原因
401	`invalid_token` / `unauthorized`	密钥无效、已撤销，或接口需要鉴权
403	`account_suspended`	账户已停用
404	`not_found`	记录或接口不存在
429	`quota_exceeded`	今日账户额度用完
429	`rate_limited`	请求过快
429	`anonymous_quota_exceeded`	匿名额度用完
503	`upstream_unavailable` / `metering_unavailable`	检索或计量服务暂不可用，可稍后重试
503	`incomplete_search`	检索结果不完整，不能据此作完整判断，请稍后重试

数据来源与口径

来源：国家知识产权局商标开放数据，按官方发布的年度/月度 CSV 批次导入。不是实时官方数据，以最新批次为准（见 /v1/datasets/current）。
一条记录对应一个 “申请号 × 尼斯分类”。同一商标在多个批次出现时，按批次先后合并：字段取最新的非空值；申请人、核定商品以最新包含该商标的批次为准。
开放数据没有官方“法律状态”字段。网站上的“已注册公告 / 已初审公告 / 专用期已届满”依据公告与期限日期推断，仅供参考；转让、撤销、无效宣告等流程可能未体现。
图形商标可能没有文字名称。2025 年 9 月起的官方批次不再提供“商标名称”字段，只出现在这些批次中的新申请暂无文字名称，可按申请号、申请人或商品检索。
部分记录（包括一些马德里国际注册）在官方数据中没有申请人明细，这是源数据本身的缺失。
检索结果仅反映数据中的文字记录，不构成法律意见，也不代表某个名称可以或不能注册。

数据声明与再使用要求

数据源于商标数据开放系统，受商标数据开放系统相关协议、条款约束。本服务由 Ouvo 独立提供，与国家知识产权局无隶属关系。含商标数据的响应都带有 source 字段，内容即此声明。
如果你在自己的应用或网站中展示通过本 API / MCP 获得的数据，须同样展示上述声明，并说明该应用是你自己的行为。
数据仅供你自己的查询与分析，不得将全部或部分数据转送、分发给第三方，也不得用于重建或镜像数据库。详见服务条款第 3 条。