专利检索 · 关键词 | TROHUB API 文档

按关键词检索发明专利，同步返回结果（不产生 taskID）。

检索

POST /ip/patent/advanced-search

请求参数

参数	类型	必填	说明
`query`	`string`	✅	关键词（如 `wireless earbuds`）或条件表达式（如 `TI:(dog ADJ bed)`）；不可为空。
`page`	`integer`	❌	页码，从 1 开始。
`pageSize`	`integer`	❌	每页条数，最大 50。
`sort`	`string`	❌	`relevance` 相关度 / `grantDesc` 最新授权 / `grantAsc` 最早授权 / `expiryAsc` 最快到期
`implicitOperator`	`string`	❌	相邻条件之间不写算子时按什么算，默认 `and`（USPTO 官方默认 `or`）。只影响没有显式写算子的地方；显式 `AND` / `OR` / `NOT` 照字面执行，优先级不变（选 `or` 时 `a b AND c` 等于 `a OR (b AND c)`）。
`includeUkSpellings`	`boolean`	❌	英美拼写是否等价（`color` 也能命中 `colour`），默认开；关掉则只匹配用户写的拼法。只影响检索匹配范围，不会改写用户提交的查询。仅对整词与分文字段生效，短语、通配、整串相等、专利号/种类码等字段不受影响。
`recordHistory`	`boolean`	❌	是否记入检索历史，默认 `false`。
`includeDsl`	`boolean`	❌	是否返回解析后的查询语句。
`historyId`	`string`	❌	检索历史 ID；属于本账号的记录不重复计费。

请求示例

{
  "query": "wireless earbuds",
  "page": 1,
  "pageSize": 20,
  "sort": "relevance",
  "implicitOperator": "and",
  "includeUkSpellings": false,
  "recordHistory": false,
  "includeDsl": false,
  "historyId": "3f2b1c4d5e6f47a8b9c0d1e2f3a4b5c6"
}

cURLPython

curl -X POST "https://api.trohub.com/v2/ip/patent/advanced-search" -H "Authorization: Bearer YOUR_API_KEY" -H "Content-Type: application/json" -d '{"query":"wireless earbuds","page":1,"pageSize":20,"sort":"relevance","implicitOperator":"and","includeUkSpellings":false,"recordHistory":false,"includeDsl":false,"historyId":"3f2b1c4d5e6f47a8b9c0d1e2f3a4b5c6"}'

import requests

url = "https://api.trohub.com/v2/ip/patent/advanced-search"
headers = {"Authorization": "Bearer YOUR_API_KEY"}
payload = {
  "query": "wireless earbuds",
  "page": 1,
  "pageSize": 20,
  "sort": "relevance",
  "implicitOperator": "and",
  "includeUkSpellings": false,
  "recordHistory": false,
  "includeDsl": false,
  "historyId": "3f2b1c4d5e6f47a8b9c0d1e2f3a4b5c6"
}

r = requests.post(url, headers={**headers, "Content-Type": "application/json"}, json=payload)
print(r.json())

响应示例

{
  "ok": true,
  "message": "成功",
  "data": {
    "total": 1,
    "totalText": "string",
    "warnings": [
      {
        "kind": "stopwordRequired",
        "word": "string",
        "pos": 0,
        "field": "string",
        "fatal": false,
        "fixedQuery": "string"
      }
    ],
    "relation": "eq",
    "page": 1,
    "pageSize": 20,
    "tookMs": 0,
    "timedOut": false,
    "index": "string",
    "items": [
      {
        "pn": "string",
        "title": "2026 秋季批次 A",
        "abstract": "string",
        "kind": "string",
        "patentType": "string",
        "apn": "string",
        "pubNumber": "string",
        "grant": 0,
        "filling": 0,
        "expiry": 0,
        "terms": 0,
        "assignees": [
          {
            "name": "string",
            "country": "string"
          }
        ],
        "inventors": [
          {
            "name": "string",
            "country": "string"
          }
        ],
        "ipcs": [
          "string"
        ],
        "cpcs": [
          "string"
        ],
        "loc": "string",
        "score": 0,
        "highlights": "string",
        "matchedClaims": [
          {
            "claimNumber": 0,
            "snippet": "string"
          }
        ],
        "matchedNested": "string",
        "imageUrls": [
          "string"
        ],
        "imageCount": 1
      }
    ],
    "dsl": "string",
    "sort": "string",
    "truncatedWindow": false,
    "maxWindow": 0,
    "maxPageSize": 1,
    "suggestions": [
      {
        "kind": "string",
        "query": "wireless earbuds"
      }
    ]
  }
}

响应字段

参数	类型	必填	说明
`total`	`integer`	❌	命中总数。`relation` 为 `eq` 时为精确值
`totalText`	`string`	❌	`total` 的显示字符串：不超过 1000 时为精确值（如 `921`、`1,000`），超过 1000 时按千位向下取整加 `+`（如 9,021 → `9,000+`、428,713 → `428,000+`）。千分位用逗号。展示命中数请直接用这个字段；`total` 保持精确值，用于分页计算。
`warnings`	`array<object>`	❌	查询能执行、但结果可能和预期不一样的提醒。目前只有英文停用词：全文索引（english 分析器）会忽略 `for`、`the` 这类词，单独检索它们不会有任何命中。不会阻止查询，结果照常返回；`fatal` 为 `true` 表示它受 AND 约束，整条查询会返回 0 条。
`warnings[].kind`	`string`	❌	`stopwordRequired` 必需条件里的停用词（整条查询会 0 条）/ `stopwordIgnored` 可选位置或短语/邻近里的停用词（条件被忽略）
`warnings[].word`	`string`	❌	出问题的词；整条短语都是停用词时是那句短语
`warnings[].pos`	`integer`	❌	在查询串里的字符位置（从 0 开始）
`warnings[].field`	`string`	❌	命中的字段；为空表示没写字段限定（默认多字段检索）
`warnings[].fatal`	`boolean`	❌	是否会让整条查询返回 0 条
`warnings[].fixedQuery`	`string`	❌	只删掉这一项之后的查询（可直接执行）；为空表示删不掉（整条查询就它一个词）
`relation`	`string`	❌	`total` 的精度：`eq` 表示精确值；`gte` 表示未能精确计数，此时 `total` 为下限（实际命中数不少于该值）
`page`	`integer`	❌	—
`pageSize`	`integer`	❌	—
`tookMs`	`integer`	❌	检索耗时（毫秒）
`timedOut`	`boolean`	❌	检索是否超时。为 `true` 时，返回结果可能不完整
`index`	`string`	❌	本次查询所使用的数据集标识
`items`	`array<UtilityAdvancedSearchItem>`	❌	—
`items[].pn`	`string`	❌	—
`items[].title`	`string`	❌	—
`items[].abstract`	`string`	❌	—
`items[].kind`	`string`	❌	文献种类代码，如 `B2`
`items[].patentType`	`string`	❌	—
`items[].apn`	`string`	❌	—
`items[].pubNumber`	`string`	❌	—
`items[].grant`	`integer`	❌	授权日，`YYYYMMDD` 整数
`items[].filling`	`integer`	❌	申请日，`YYYYMMDD` 整数
`items[].expiry`	`integer`	❌	到期日，`YYYYMMDD` 整数
`items[].terms`	`integer`	❌	专利期限（年）
`items[].assignees`	`array<UtilityAdvancedParty>`	❌	—
`items[].assignees[].name`	`string`	❌	—
`items[].assignees[].country`	`string`	❌	国家代码（ISO 3166-1 alpha-2）
`items[].inventors`	`array<UtilityAdvancedParty>`	❌	—
`items[].inventors[].name`	`string`	❌	—
`items[].inventors[].country`	`string`	❌	国家代码（ISO 3166-1 alpha-2）
`items[].ipcs`	`array<string>`	❌	—
`items[].cpcs`	`array<string>`	❌	—
`items[].loc`	`string`	❌	洛迦诺分类号（仅外观设计专利具有）
`items[].score`	`number`	❌	相关度得分。按日期排序时同样返回，可用于判断结果与检索条件的匹配程度
`items[].highlights`	`object`	❌	各字段的高亮片段，key 为字段名（如 `title`、`abstract`）
`items[].matchedClaims`	`array<object>`	❌	命中的权利要求（最多 3 条）
`items[].matchedClaims[].claimNumber`	`integer`	❌	—
`items[].matchedClaims[].snippet`	`string`	❌	—
`items[].matchedNested`	`object`	❌	其他字段的命中片段（如权利人、发明人姓名命中）
`items[].imageUrls`	`array<string>`	❌	附图地址（最多 5 张，原图不缩放）；无附图时不返回。须原样请求（`.TIF` 实际返回 PNG，改扩展名/查询串会 404）。
`items[].imageCount`	`integer`	❌	附图总张数（本接口最多给 5 张，全量用 `POST /ip/patent/detail`）。
`dsl`	`object`	❌	系统解析后的查询语句（仅当请求中 `includeDsl=true` 时返回）
`sort`	`string`	❌	—
`truncatedWindow`	`boolean`	❌	命中数超过跨页可查看的上限，仅可查看前 `maxWindow` 条结果
`maxWindow`	`integer`	❌	—
`maxPageSize`	`integer`	❌	—
`suggestions`	`array<UtilityAdvancedSearchSuggestion>`	❌	无结果时的查询改写建议（目前仅提供“放宽邻近算符”一种）
`suggestions[].kind`	`string`	❌	建议类型（目前仅有“放宽邻近算符”）
`suggestions[].query`	`string`	❌	改写后的查询串，可用于重新发起查询

可能的错误

HTTP	错误码	说明
400	`VALIDATION_*`（见 message）	请求数据无效（HTTP 400）
401	`UNAUTHORIZED_AUTH_REQUIRED`	缺少 API Key、Key 无效或被封禁（HTTP 401），错误码 `UNAUTHORIZED_AUTH_REQUIRED`。
403	`BUSINESS_INSUFFICIENT_QUOTA`	积分不足（HTTP 403），错误码 `BUSINESS_INSUFFICIENT_QUOTA`。提交类接口在扣减积分前校验余额。
429	`BUSINESS_RATE_LIMIT_EXCEEDED` / `RATE_LIMITER_UNAVAILABLE`	请求频率或并发数超限（HTTP 429），错误码 `BUSINESS_RATE_LIMIT_EXCEEDED`。限流校验不可用时返回 503（`RATE_LIMITER_UNAVAILABLE`）。限流是动态的：额度由「你的 API 档位 × 接口所属的桶」决定，所以同一个接口对不同调用者可能是不同的数值，这里不给出固定数字。两处可以看到实际生效值： 1. 每次响应的 `X-RateLimit-` 响应头（当次生效的次数、窗口、命中哪一档额度）； 2. `GET /v2/quota/mine`（带 API Key，返回你每个额度的生效值）；另有 `GET /v2/quota/config`（公开）给出未分档的基线额度。计数口径：按账号计* —— 同一账号下的所有 API Key 共享同一份额度，多开一个 Key 不会获得额外配额。接口桶是分开计数的（例如「提交检测」与「轮询结果」是两个桶），所以轮询不会吃掉提交的额度。
500	`INTERNAL_ERROR_UNKNOWN`	服务器内部错误（HTTP 500），错误码 `INTERNAL_ERROR_UNKNOWN`