2. 인증 및 공통사항¶

2.1 API 키¶

API 키 없이도 사용 가능하나, rate limit이 적용된다. API 키를 사용하면 더 높은 처리량을 확보할 수 있다.

x-api-key: YOUR_API_KEY

주의: 헤더 이름 x-api-key는 대소문자를 구분한다.

2.2 공통 요청 형식¶

• Content-Type: application/json
• Accept: application/json
• 모든 특수문자는 URL 인코딩 필수

2.3 fields 파라미터¶

거의 모든 엔드포인트에 공통으로 사용되는 핵심 파라미터다. 쉼표로 구분된 필드 목록을 지정해 응답 크기를 제어한다.

?fields=title,authors,year,citationCount

기본 동작: - fields 생략 시 → 논문: paperId + title, 저자: authorId + name만 반환 - fields는 단일 값 문자열 파라미터 (multi-value가 아님)

중첩 필드(서브필드) 지정:

마침표(.)를 사용해 하위 필드를 지정한다:

예시:

fields=title,url                                    # 기본 필드만
fields=title,embedding.specter_v2                   # SPECTER v2 임베딩
fields=title,authors,citations.title,citations.abstract  # 저자 + 인용논문 제목/초록
fields=url,papers.year,papers.authors               # 저자 API에서 논문 서브필드

주의: /snippet/search의 fields는 snippet.text, snippet.snippetKind 형태로 지정. paper와 score는 항상 반환되므로 지정 불가.

2.4 페이지네이션¶

두 가지 방식이 존재한다:

offset 기반 예시:

GET /paper/search?query=LLM&offset=0&limit=10
GET /paper/search?query=LLM&offset=10&limit=10

token 기반 예시:

GET /paper/search/bulk?query=LLM
→ 응답에 "token": "abc123" 포함
GET /paper/search/bulk?query=LLM&token=abc123

2.5 논문 ID 형식¶

논문을 지정할 때 다양한 외부 ID를 사용할 수 있다:

지원 URL 사이트: semanticscholar.org, arxiv.org, aclweb.org, acm.org, biorxiv.org

2.6 공통 필터 파라미터 상세¶

검색 관련 엔드포인트(/paper/search, /paper/search/bulk, /paper/search/match, /snippet/search)에서 공통으로 사용되는 필터:

publicationDateOrYear¶

날짜 범위 형식: <시작>:<끝> (각각 YYYY-MM-DD 형식, 양쪽 모두 선택적)

정확한 출판일을 모르는 논문은 해당 연도의 1월 1일로 처리된다. publicationDate가 null이어도 year는 항상 존재한다.

year¶

연도 단위 간편 필터:

publicationTypes¶

출판 유형 필터 (쉼표 구분, OR 로직):

예시: publicationTypes=Review,JournalArticle → Review 또는 JournalArticle인 논문

fieldsOfStudy¶

연구 분야 필터 (쉼표 구분, OR 로직):

Computer Science, Medicine, Chemistry, Biology, Materials Science, Physics, Geology, Psychology, Art, History, Geography, Sociology, Business, Political Science, Economics, Philosophy, Mathematics, Engineering, Environmental Science, Agricultural and Food Sciences, Education, Law, Linguistics

예시: fieldsOfStudy=Physics,Mathematics → Physics 또는 Mathematics 분야 논문

venue¶

학회/저널 필터 (쉼표 구분). 정식 명칭과 ISO4 약칭 모두 사용 가능:

예시: venue=Nature,Radiology 또는 venue=N. Engl. J. Med.

openAccessPdf¶

오픈 액세스 PDF가 있는 논문만 필터. 값 없이 파라미터만 포함한다:

?query=LLM&openAccessPdf

minCitationCount¶

최소 인용 수 필터:

?query=LLM&minCitationCount=200

2.7 응답 크기 제한¶

• 모든 엔드포인트의 단일 응답 최대 크기: 10MB
• 초과 시 400 에러: "Response would exceed maximum size..."
• 해결 방법: limit 줄이기, fields 최소화, 배치 분할

2.8 에러 응답¶