DocsSearch API (检索)

Search API

支持自然语言句子的语义专利检索引擎。一次调用即可同时检索中、韩、美、日、欧五国专利。

检索指南

LLM 自然语言检索方法与基于参数的详细检索组合指南请参阅左侧菜单的检索指南。

认证

除公开统计与健康检查外,所有端点都需要 X-API-Key 请求头。详情请参阅认证。

POST /api/v1/search/semantic

以自然语言检索专利。查询会被嵌入为向量,经 k-NN 匹配后再重排序。支持多语言查询(韩语、英语、日语、中文)。

请求参数 (Request Parameters)

参数	类型	必填	默认值	说明
`query`	string	是	—	自然语言检索查询(句式)
`top_k`	integer	否	10	返回结果数(建议 1–100)
`countries`	string[]	否	全部 5 国	`["KR","US","CN","JP","EP"]` 的子集
`doc_type`	enum	否	`"all"`	`"all"`(公开+授权,去重)/ `"application"` / `"grant"`
`kind_codes`	string[]	否	null	指定的 kind code(例: `["B1","B2"]`)。优先于 `doc_type`
`include_utility_model`	boolean	否	false	是否包含实用新型
`filing_date_from` / `_to`	string	否	null	申请日范围 (`YYYY-MM-DD`)
`publication_date_from` / `_to`	string	否	null	公开日范围
`grant_date_from` / `_to`	string	否	null	授权日范围(仅匹配授权公告)
`priority_date_from` / `_to`	string	否	null	优先日范围
`applicant`	string	否	null	申请人检索词。不区分大小写,支持各国原文输入
`applicant_match`	enum	否	`"contains"`	`"contains"` / `"prefix"` / `"exact"`
`inventor`	string	否	null	发明人检索词(前缀匹配)
`ipc_codes`	string[]	否	null	IPC 代码前缀(例: `["H01M10"]`)
`cpc_codes`	string[]	否	null	CPC 代码前缀
`publication_number`	string	否	null	公开号精确匹配(KIPRIS 格式)
`application_number`	string	否	null	申请号精确匹配
`family_id`	string	否	null	同族 ID 精确匹配

申请人匹配

申请人输入不区分大小写,并支持各国原文输入("삼성전자"、"华为"、"ソニー"、"APPLE")。但单次输入不会自动扩展到五国的所有语言写法 — 如需跨国覆盖,请分别用英文和本国语言检索。

请求示例 (Request Example)

cURL — Semantic search with filters

curl -X POST https://api.findip.ai/api/v1/search/semantic \
-H "X-API-Key: $API_KEY" \
-H "Content-Type: application/json" \
-d '{
  "query": "在全固态电池中抑制锂枝晶生长的固态电解质技术",
  "top_k": 20,
  "countries": ["KR", "US", "JP"],
  "doc_type": "application",
  "applicant": "SAMSUNG",
  "applicant_match": "prefix",
  "filing_date_from": "2022-01-01",
  "filing_date_to": "2024-12-31",
  "ipc_codes": ["H01M10"]
}'

响应 (Response)

响应返回 total(= results.length)与结果数组。

200 OK

{
"total": 20,
"results": [
  {
    "patent_id": "KR1020230012345A",
    "title": "包含固态电解质的二次电池",
    "applicant": "SAMSUNG SDI CO., LTD.",
    "filing_date": "2023-02-10",
    "publication_date": "2024-08-15",
    "ipc_codes": ["H01M10/0525", "H01M4/62"],
    "kind_code": "A",
    "country": "KR",
    "similarity_score": 0.8712,
    "rerank_score": 0.9345,
    "representative_figure": "fig_0001.webp",
    "chunks": [
      {
        "text": "本发明提供一种用于抑制锂枝晶生长的固态电解质 ...",
        "chunk_type": "description",
        "section_name": "详细说明_3",
        "paragraph_numbers": [42, 43],
        "claim_numbers": [],
        "similarity_score": 0.8712,
        "rerank_score": 0.9345
      }
    ]
  }
]
}

结果项字段 — patent_id(公开号,KIPRIS 格式)、title、applicant、filing_date、publication_date、ipc_codes、kind_code、country、similarity_score(0–1,越大越相似)、rerank_score(BGE 重排序器 — 以排序顺序而非绝对值为准)、representative_figure(仅文件名 — 见下方附图)、chunks(匹配片段,按 rerank_score 降序)。

POST /api/v1/search/semantic-analytics

执行相同的向量检索,同时返回统计聚合 + 分页结果,适合仪表盘与态势分析。支持 /semantic 的所有过滤字段,并使用 date_range + date_type 取代各个单独的日期字段。

请求参数(与 /semantic 的差异)

参数	类型	默认值	说明
`min_score`	float	0.5	相似度阈值(`best_score >= min_score`)
`max_results`	integer	10000	参与统计的最大文档数
`date_range`	object	null	`{"from": "YYYY-MM-DD", "to": "YYYY-MM-DD"}`
`date_type`	enum	`"filing"`	`"filing"` / `"publication"` / `"grant"` / `"priority"`
`stats_group_by`	string[]	`["year","country"]`	聚合维度: `"year"`、`"country"`、`"applicant"`、`"ipc"`
`page`	integer	1	从 1 开始的页码
`page_size`	integer	20	每页大小 (1–100)

请求示例 (Request Example)

cURL — Search with statistics

curl -X POST https://api.findip.ai/api/v1/search/semantic-analytics \
-H "X-API-Key: $API_KEY" \
-H "Content-Type: application/json" \
-d '{
  "query": "5G 波束成形天线阵列",
  "min_score": 0.6,
  "max_results": 5000,
  "countries": ["KR", "US"],
  "date_range": {"from": "2020-01-01", "to": "2024-12-31"},
  "date_type": "filing",
  "stats_group_by": ["year", "country", "applicant", "ipc"],
  "page": 1,
  "page_size": 20
}'

响应 (Response)

200 OK

{
"query": "5G 波束成形天线阵列",
"total_matched": 412,
"min_score_used": 0.6,
"page": 1,
"page_size": 20,
"total_pages": 21,
"stats": {
  "by_year": { "2020": 142, "2021": 180 },
  "by_country": { "KR": 230, "US": 182 },
  "top_applicants": [{ "name": "SAMSUNG ELECTRONICS CO., LTD.", "count": 58 }],
  "top_ipc": [{ "code": "H01Q", "count": 96 }]
},
"results": [
  {
    "patent_id": "KR1020210099999A",
    "title": "用于 5G 基站的波束成形天线阵列",
    "applicant": "SAMSUNG ELECTRONICS CO., LTD.",
    "country": "KR",
    "kind_code": "A",
    "filing_date": "2021-03-04",
    "publication_date": "2022-09-10",
    "ipc_codes": ["H01Q3/26"],
    "similarity_score": 0.7321,
    "chunk_text": "用于自适应波束成形的天线阵列 ..."
  }
]
}

stats 对象根据请求的 stats_group_by 维度,包含 by_year、by_country、top_applicants(最多 20 项)与 top_ipc(最多 20 项)。

POST /api/v1/patents/details

获取一个或多个专利的完整详情(Markdown 正文 + 元数据)。附图引用在 Markdown 正文内,请用下方附图规则组装图片 URL。

请求参数

参数	类型	必填	说明
`patent_ids`	string[]	是	公开号 1–200 件(KIPRIS 格式)
`sections`	string	否	从 `title,abstract,claims,description` 中以逗号分隔选择。省略时返回完整 Markdown

请求示例 (Request Example)

cURL — Document details

curl -X POST https://api.findip.ai/api/v1/patents/details \
-H "X-API-Key: $API_KEY" \
-H "Content-Type: application/json" \
-d '{
  "patent_ids": ["KR1020230012345A", "US20230123456A1"],
  "sections": "title,abstract,claims"
}'

响应 (Response)

200 OK

{
"patents": [
  {
    "patent_id": "KR1020230012345A",
    "metadata": {
      "title": "包含固态电解质的二次电池",
      "applicant": "SAMSUNG SDI CO., LTD.",
      "filing_date": "2023-02-10",
      "publication_date": "2024-08-15",
      "ipc_codes": ["H01M10/0525"],
      "kind_code": "A",
      "country": "KR"
    },
    "content": "# Title\n\n## Abstract\n\n...",
    "representative_figure": "fig_0001.webp"
  },
  {
    "patent_id": "US99999999B2",
    "error": "not_found"
  }
]
}

每个条目按请求的 ID 分别返回。若某专利无法找到,则该条目以 {"patent_id": "...", "error": "not_found"} 取代元数据,整体响应仍为 200 OK。

GET /api/v1/drawings/{publication_id}/{filename}

获取专利附图图片。无需认证。 服务器返回指向短期有效预签名 URL 的 302 重定向,浏览器与 fetch 会自动跟随,因此可直接用于 <img src="...">。

检索与详情响应中的 representative_figure 字段仅返回文件名。请按如下方式组装图片 URL。

URL assembly

patent_id              = "KR1020240116067A"
representative_figure  = "pat00012.webp"

→ https://api.findip.ai/api/v1/drawings/KR1020240116067A/pat00012.webp

允许的扩展名: .webp、.jpg、.jpeg、.png(其他返回 400)。由于预签名 URL 每次请求都会变化,建议在前端以 patent_id/filename 为键进行缓存。

GET /api/v1/stats/coverage

返回公开覆盖统计(各国专利数、日期范围等)。无需认证。 缓存 1 小时,若覆盖文档不可用则返回 503。

技术趋势·组合 Next: 认证 (Auth)