DocsSearch API (검색)

Search API

자연어 문장으로 특허를 검색할 수 있는 시맨틱 검색 엔진입니다. 한·미·일·중·유럽·PCT 특허를 한 번에 검색합니다.

검색 가이드

LLM 자연어 검색 방법과 파라미터를 활용한 세부 검색 조합 가이드는 좌측 메뉴의 검색 가이드를 참고하세요.

인증

공개 통계·헬스 체크를 제외한 모든 엔드포인트는 X-API-Key 헤더가 필요합니다. 자세한 내용은 인증을 참고하세요.

POST /api/v1/search/semantic

자연어로 특허를 검색합니다. 쿼리를 벡터로 임베딩한 뒤 k-NN 으로 매칭하고 리랭킹합니다. 다국어 질의를 지원합니다. (한국어, 영어, 일본어, 중국어)

요청 파라미터 (Request Parameters)

파라미터타입필수기본값설명
querystring조건부—자연어 검색 질의 (문장형)
image_urlstring조건부null공개 접근 가능한 이미지 URL. 시각적으로 닮은 도면을 가진 특허를 찾습니다
sequencestring조건부nullDNA·RNA·단백질 서열 원문. 유사한 서열을 담은 특허를 찾습니다
top_kinteger아니오10반환할 결과 개수. 실제 상한은 약 100건이며, 그보다 큰 값을 넣어도 오류 없이 무시됩니다
countriesstring[]아니오전체["KR","US","CN","JP","EP","WO"] 의 부분집합
doc_typeenum아니오"all""all" (공개+등록, 중복 제거) / "application" / "grant"
kind_codesstring[]아니오null특정 kind code (예: ["B1","B2"]). doc_type 보다 우선
include_utility_modelboolean아니오false실용신안 포함 여부. doc_type 이 "application" · "grant" 일 때만 적용됩니다 (아래 참고)
filing_date_from / _tostring아니오null출원일 범위 (YYYY-MM-DD)
publication_date_from / _tostring아니오null공개일 범위
grant_date_from / _tostring아니오null등록일 범위 (등록공보만 매칭됨)
priority_date_from / _tostring아니오null우선일 범위
applicant_entity_idsstring[]아니오null출원인 정확 매칭. 여러 개를 넣으면 OR 조건입니다
inventorstring아니오null발명자 검색어 (prefix 매칭)
ipc_codesstring[]아니오nullIPC 코드. 앞 4자리(서브클래스)로 정규화됨 (예: ["H01M"])
cpc_codesstring[]아니오nullCPC 코드 prefix
publication_numberstring아니오null공개번호 정확 매칭 (KIPRIS 형식)
application_numberstring아니오null출원번호 정확 매칭
family_idstring아니오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": ["홍길동", "김철수"],
    "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_scorefloat0.65유사도 임계값 (best_score >= min_score)
max_resultsinteger10000통계 대상 최대 문서 수. 후보군 자체가 국가당 약 1,000건 (KR·US·JP·CN·EP 합계 약 4,700건) 에서 포화하므로 그보다 큰 값은 효과가 없습니다
date_rangeobjectnull{"from": "YYYY-MM-DD", "to": "YYYY-MM-DD"}
date_typeenum"filing""filing" / "publication" / "grant" / "priority"
stats_group_bystring[]["year","country"]집계 축: "year", "country", "applicant", "ipc"
pageinteger11부터 시작하는 페이지 번호
page_sizeinteger20페이지 크기 (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

하나 이상의 특허에 대한 전체 상세 정보 (마크다운 본문 + 메타데이터) 를 조회합니다. 도면은 마크다운 본문 안에 참조되어 있으므로 아래 도면 규칙으로 이미지 URL 을 조립하세요.

요청 파라미터

파라미터타입필수설명
patent_idsstring[]예공개번호 1–200건 (KIPRIS 형식)
sectionsstring아니오title,abstract,claims,description 중 콤마 분리 선택. 생략 시 전체 마크다운

요청 예시 (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}

특허 도면 이미지를 가져옵니다. 인증이 필요하지 않습니다. 서버는 단기 유효 presigned URL 로 302 redirect 를 반환하며, 브라우저와 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). presigned URL 은 매 요청마다 변경되므로 프런트엔드에서 patent_id/filename 키로 캐싱하는 것을 권장합니다.

GET /api/v1/stats/coverage

공개 커버리지 통계 (국가별 특허 수, 날짜 범위 등) 를 반환합니다. 인증이 필요하지 않습니다. 1시간 캐시되며, 커버리지 문서를 사용할 수 없으면 503 을 반환합니다.

Next: 인증 (Auth)
검색 API 레퍼런스 — 시맨틱 특허 검색 | Findip