DocsSearch API (検索)

Search API

自然言語で特許を検索できるセマンティック検索エンジンです。日・韓・米・中・欧・PCT の特許を 1 回の呼び出しで検索できます。

検索ガイド

LLM 自然言語検索のテクニックとパラメータを使った詳細な検索組み合わせガイドは左メニューの検索ガイドをご覧ください。

認証

公開統計・ヘルスチェックを除くすべてのエンドポイントには X-API-Key ヘッダが必要です。詳細は認証をご覧ください。

POST /api/v1/search/semantic

自然言語で特許を検索します。クエリをベクトルに埋め込み、k-NN でマッチングしてリランキングします。多言語クエリに対応(韓国語・英語・日本語・中国語)。

リクエストパラメータ

パラメータ	型	必須	デフォルト	説明
`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	発明者検索語(prefix 一致)
`ipc_codes`	string[]	いいえ	null	IPC コード。先頭 4 文字(サブクラス)に正規化されます(例: `["H01M"]`)
`cpc_codes`	string[]	いいえ	null	CPC コードの prefix
`publication_number`	string	いいえ	null	公開番号の完全一致(KIPRIS 形式)
`application_number`	string	いいえ	null	出願番号の完全一致
`family_id`	string	いいえ	null	ファミリー ID の完全一致(ファミリー全体を取得する照会ではなく、検索結果を絞り込むフィルタです)

query・image_url・sequence のいずれか 1 つは必須

3 つとも指定しない場合、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"])。

1 回の指定ですべての言語表記やグループ会社へ自動展開することはできません — まとめて取得したい場合は該当する識別子をすべて配列に入れてください(OR 条件)。

フィルタはクエリが見つけた候補にのみ適用されます

すべてのフィルタは、クエリで検索した結果を絞り込む形で動作します。そのため family_id のようにピンポイントを狙うフィルタでも、クエリと無関係な文献まで引き寄せることはありません — クエリがその文献を候補として捉えられなければ結果は 0 件です。存在するはずのファミリー ID で 0 件になる場合は、フィルタではなくクエリを広げてください。

番号が分かっていてクエリと無関係に特定の文献を取得したい場合は、publication_number または POST /api/v1/patents/details を使用してください。

リクエスト例

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"]
}'

レスポンス

レスポンスは 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

同じベクトル検索を実行しつつ、統計集計 + ページネーション結果を併せて返します。ダッシュボードや分析 UI に最適です。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 か国あたり約 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)

リクエスト例

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
}'

レスポンス

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

1 件以上の特許について、全体の詳細情報(マークダウン本文 + メタデータ)を取得します。図面はマークダウン本文内に参照されているため、下記の図面ルールで画像 URL を組み立ててください。

リクエストパラメータ

パラメータ	型	必須	説明
`patent_ids`	string[]	はい	公開番号 1–200 件(KIPRIS 形式)
`sections`	string	いいえ	`title,abstract,claims,description` のうちカンマ区切りで選択。省略時は全文マークダウン

リクエスト例

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"
}'

レスポンス

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)

Search API

POST /api/v1/search/semantic

リクエストパラメータ

リクエスト例

レスポンス

POST /api/v1/search/semantic-analytics

リクエストパラメータ(/semantic との差分)

リクエスト例

レスポンス

POST /api/v1/patents/details

リクエストパラメータ

リクエスト例

レスポンス

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

GET /api/v1/stats/coverage

リクエストパラメータ(`/semantic` との差分)