DocsSearch API (检索)

Search API

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

检索指南

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

认证

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

POST /api/v1/search/semantic

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

请求参数 (Request Parameters)

参数	类型	必填	默认值	说明
`query`	string	条件必填	—	自然语言检索查询(句式)
`image_url`	string	条件必填	null	可公开访问的图像 URL。检索附图在视觉上相似的专利
`sequence`	string	条件必填	null	DNA／RNA／蛋白质序列原文。检索包含相似序列的专利
`top_k`	integer	否	10	返回结果数。实际上限约为 100 条,超出的取值不会报错,而是被忽略
`countries`	string[]	否	全部	`["KR","US","CN","JP","EP","WO"]` 的子集
`doc_type`	enum	否	`"all"`	`"all"`(公开+授权,去重)/ `"application"` / `"grant"`
`kind_codes`	string[]	否	null	指定的 kind code(例: `["B1","B2"]`)。优先于 `doc_type`
`include_utility_model`	boolean	否	false	是否包含实用新型。仅当 `doc_type` 为 `"application"`／`"grant"` 时生效(见下文)
`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_entity_ids`	string[]	否	null	申请人精确匹配。指定多个时按 OR 处理
`inventor`	string	否	null	发明人检索词(前缀匹配)
`ipc_codes`	string[]	否	null	IPC 代码。归一化为前 4 个字符(小类),例: `["H01M"]`
`cpc_codes`	string[]	否	null	CPC 代码前缀
`publication_number`	string	否	null	公开号精确匹配(KIPRIS 格式)
`application_number`	string	否	null	申请号精确匹配
`family_id`	string	否	null	同族 ID 精确匹配(这是收窄检索结果的过滤条件,并非返回整个同族的查询)

query、image_url、sequence 三者必居其一

三者都不提供时，接口返回 400 及 query·image·sequence 중 하나가 필요합니다。也可以组合使用 —— 在 image_url 或 sequence 之外再加 query，会把视觉或序列上相似的专利按主题进一步收窄并重新排序。

检索点数方面，仅文本检索为 1；使用 image_url 或 sequence 时扣除 2（参见认证）。

IPC 代码归一化

无论传入什么，ipc_codes 都会被截断为前 4 个字符处理。因此 "H01M10" 与 "H01M10/0525" 的行为与 "H01M" 完全相同，无法收窄到大组或小组级别。少于 4 个字符将返回 400(classification code too short)。

实用新型的纳入规则

include_utility_model 仅在 doc_type 为 "application" 或 "grant" 时生效。在默认的 doc_type: "all" 下,无论该值如何,实用新型始终会被包含。

在指定了 doc_type 的前提下将其设为 true,公开侧会加入韩国、中国、日本的实用新型(U),授权侧会加入韩国的授权实用新型(Y1)。美国与欧洲没有实用新型制度,因此不会有变化。

申请人匹配

申请人过滤通过 applicant_entity_ids 指定,只匹配完全一致的申请人标识。匹配区分大小写且不支持部分字符串,请直接使用检索响应中 applicants_harmonized 里实际出现的写法(例: ["SAMSUNG ELECTRONICS CO LTD"])。

单次指定不会自动扩展到各国语言写法或关联公司 — 如需一并命中,请把相关标识全部放进数组(OR 条件)。

过滤条件只作用于检索已找到的候选

所有过滤条件都是在查询检索到的结果之上做收窄。因此即便是 family_id 这类精确定位的过滤条件,也不会把查询本身没有命中的文献拉进来 —— 如果查询没有把该文献纳入候选,结果就是 0 条。当一个确实存在的同族 ID 返回 0 条时,应当放宽查询而不是过滤条件。

若已知号码,想不受查询影响地取回特定文献,请使用 publication_number 或 POST /api/v1/patents/details。

请求示例 (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_entity_ids": ["SAMSUNG SDI CO LTD"],
  "filing_date_from": "2022-01-01",
  "filing_date_to": "2024-12-31",
  "ipc_codes": ["H01M"]
}'

响应 (Response)

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

200 OK

{
"total": 20,
"results": [
  {
    "patent_id": "KR1020230012345A",
    "title": "包含固态电解质的二次电池",
    "applicants": ["삼성에스디아이 주식회사"],
    "applicants_harmonized": ["SAMSUNG SDI CO LTD"],
    "inventors": ["HONG GILDONG", "KIM CHULSOO"],
    "inventors_harmonized": [],
    "application_number": "KR1020230012345",
    "family_id": "u:KR1020230012345A",
    "filing_date": "2023-02-10",
    "publication_date": "2024-08-15",
    "priority_date": "2022-02-10",
    "ipc_codes": ["H01M 10/0525", "H01M 4/62"],
    "kind_code": "A",
    "country": "KR",
    "legal_status": "PUBLISHED",
    "similarity_score": 0.7632,
    "rerank_score": 0.9468,
    "representative_figure": "112025002489408-pat00002.webp",
    "chunks": [
      {
        "text": "本发明提供一种用于抑制锂枝晶生长的固态电解质 ...",
        "chunk_type": "description",
        "section_name": "背景技术_0",
        "paragraph_numbers": [3, 4],
        "claim_numbers": [],
        "similarity_score": 0.7632,
        "rerank_score": 0.9468
      }
    ],
    "family_member_count": 1
  }
]
}

结果项字段 — patent_id(公开号,KIPRIS 格式)、title、applicants(各国原文申请人数组)、applicants_harmonized(标准化申请人数组)、inventors / inventors_harmonized、application_number、family_id、filing_date、publication_date、grant_date(仅授权公报)、priority_date、ipc_codes、kind_code、country、legal_status(GRANTED / PUBLISHED)、similarity_score(0–1,越大越相似)、rerank_score(重排序器 — 以排序顺序而非绝对值为准)、representative_figure(仅文件名 — 见下方附图)、chunks(匹配片段,按 rerank_score 降序)、family_member_count。

关于响应字段

若某条记录没有对应取值，该字段可能会从响应中省略。请勿假设所有字段始终存在。

image_url 检索会在每条结果中额外返回 image_score 与 matched_drawing；sequence 检索则额外返回 sequence_score 与 matched_seqs。

POST /api/v1/search/semantic-analytics

执行相同的向量检索,同时返回统计聚合 + 分页结果,适合仪表盘与态势分析。支持 countries、doc_type、kind_codes、include_utility_model、applicant_entity_ids、inventor、ipc_codes、cpc_codes 过滤条件,并使用 date_range + date_type 取代各个单独的日期字段。

publication_number、application_number、family_id 在本端点不受支持 —— 指定后不会报错而是被忽略,如需按号码定位特定文献,请使用 /semantic。

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

参数	类型	默认值	说明
`min_score`	float	0.65	相似度阈值(`best_score >= min_score`)
`max_results`	integer	10000	参与统计的最大文档数。候选集本身在每国约 1,000 条(KR、US、JP、CN、EP 合计约 4,700 条)时即饱和,超出的取值不会产生效果
`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,
"score_distribution": {
  "candidates_total": 658,
  "candidates_above_min_score": 651,
  "min": 0.3141,
  "p25": 0.5341,
  "median": 0.5757,
  "p75": 0.6108,
  "max": 0.7852
},
"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 基站的波束成形天线阵列",
    "applicants": ["삼성전자주식회사"],
    "applicants_harmonized": ["SAMSUNG ELECTRONICS CO LTD"],
    "country": "KR",
    "legal_status": "PUBLISHED",
    "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 项)。响应中还会附带用于诊断的 timing 对象。

调整 min_score

默认值 0.65 相当严格。在过滤条件较窄时按默认值调用，total_matched 经常返回 0，因此请依据响应中的 score_distribution 进行调整。下调至 median 附近通常能得到合适的规模；若混入无关文献，则向 p75 方向上调。

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": "包含固态电解质的二次电池",
      "applicants": ["삼성에스디아이 주식회사"],
      "applicants_harmonized": ["SAMSUNG SDI CO LTD"],
      "inventors": ["HONG GILDONG"],
      "application_number": "KR1020230012345",
      "family_id": "u:KR1020230012345A",
      "filing_date": "2023-02-10",
      "publication_date": "2024-08-15",
      "priority_date": "2022-02-10",
      "ipc_codes": ["H01M 10/0525"],
      "kind_code": "A",
      "country": "KR",
      "legal_status": "PUBLISHED",
      "family_member_count": 1
    },
    "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)