文档 / REST API

REST API

所有端点使用 HTTPS + Authorization: Bearer <KEY>；请求与响应均为 JSON（图搜为 multipart）。

端点

方法	路径	说明
POST	`/api/trademark/search`	文字检索
GET	`/api/trademark/search/modes`	支持的检索模式与策略
GET	`/api/trademark/data/detail`	单品详情（app_num + ipoffice）
POST	`/api/image/search`	图形近似检索（multipart）
GET	`/api/trademark/commercial/tools`	工具目录与用量口径
GET	`/api/trademark/commercial/balance`	额度余额
GET	`/api/trademark/commercial/usage`	用量明细
POST	`/api/trademark/commercial/keys/rotate`	Key 轮换

检索参数

字段	类型	说明
`mark`	string	商标名称（必填；中文/英文均可）
`mode`	string	17 种：smart / exact / contains / match / fuzzy / phrase / same / insert / reduce / change / order / reverse / yintong / xingtong / neihanqita / hanyuqita / repeat。未知值 REST 会静默降级，MCP 层直接拒绝。
`ipOffice`	string	局代码，如 US、BR、AU；多个用逗号分隔（如 `"US,JP"`；传数组会导致上游 400）
`niceCode`	string	尼斯分类，逗号分隔字符串，如 "09"、"25,28"（勿传数组）
`status`	string	LIVE / DEAD / OTHER
`appDate`	string	申请日范围，如 2020-01-01:2024-12-31
`page` / `size`	int	页码（从 1 开始，默认 1）/ 每页条数（默认 10，上限 100）；`page × size ≤ 10000`（超出返回 10006）
`sortOrder`	string	ASC / DESC（按申请日；默认 DESC）

响应结构

jsonsearch-response.json

{
  "code": 200,
  "message": "请求成功",
  "data": {
    "totalHits": 10000, "totalPages": 1000, "currentPage": 1, "pageSize": 10,
    "searchMode": "smart", "enhanced": true,
    "appliedQueries": ["HUAWEI", "HU AWEI", "..."],
    "hits": [{
      "mark": "HUAWEI", "appNum": "501734182", "ipOffice": "BR",
      "applicant": ["HUAWEI TECHNOLOGIES CO., LTD."],
      "niceCode": ["12"], "status": "Live", "statusCategory": "live",
      "appDate": "20230329", "score": 10500, "officialPage": "https://..."
    }]
  }
}

totalHits 口径

近似模式（smart 等）totalHits 为上限值 10000，contains/match/phrase 为 1000；仅 exact 可得到精确计数。页面与 MCP 结果均以「约/上限」标注，不得当作精确命中数。

错误码

code	含义	可重试
`200`	成功（业务结果以 body.code 判定；HTTP 200 不代表成功）	—
`400`	参数类型错误（如 ipOffice 传数组）	否
`410`	详情记录不存在	否
`10005`	服务端错误（详情缺参时也会返回；HTTP 常为 200）	是
`10006`	翻页或查询总量过大（size>100 或 page×size>10000）	否
`10007`	查询参数设置不正确（page<1）	否
`10010`	法律状态错误（仅支持 LIVE / DEAD / OTHER）	否
`10035`	该局暂未开放详情（详情端点）	否
`500`	服务异常 / Token 未初始化	是（退避）

图搜错误使用 { "success": false, "error": "..." } 形态（400/413/502 等），详见错误与限流。

← 快速开始 MCP →