3. 논문 검색 API¶

3.1 Paper Relevance Search¶

논문을 관련도 순으로 검색한다. 가장 기본적인 검색 엔드포인트.

GET /graph/v1/paper/search

파라미터:

응답 스키마:

{
  "total": 1000,
  "offset": 0,
  "next": 10,
  "data": [ { "paperId": "...", "title": "..." } ]
}

제한사항: - 최대 1,000건의 관련도 순위 결과만 반환 가능 - 단일 응답 최대 10MB

예시:

curl "https://api.semanticscholar.org/graph/v1/paper/search?query=transformer+attention&fields=title,year,citationCount&limit=5"

hurl 테스트¶

hurl --variable s2_api_key=$S2_API_KEY --variable query=transformer+attention api/graph/paper-search.hurl

--variable 옵션으로 검색어를 변경할 수 있다. --json 플래그를 추가하면 캡처된 값을 JSON으로 출력한다.

3.2 Paper Bulk Search¶

대량 논문 데이터 조회용. relevance search와 유사하나 검색 관련도 없이 대량 검색에 최적화되어 있다.

GET /graph/v1/paper/search/bulk

특징: - 텍스트 쿼리는 필수이며 불리언 로직 지원 (빈 문자열 허용) - 호출당 최대 1,000건 반환 - 더 많은 결과가 있으면 token이 반환됨 - 최대 10,000,000건까지 페이징 가능 (그 이상은 Datasets API 사용) - 중첩 데이터(citations, references 등)는 이 엔드포인트에서 사용 불가

파라미터:

쿼리 문법 (불리언 검색):

sort 파라미터:

형식: field:order (기본 paperId:asc)

정렬 값이 없는 레코드는 asc/desc 무관하게 마지막에 나타난다. 페이징 중 데이터 변경 시 기본 paperId 정렬이 가장 안정적이다. 동점 시 paperId 기준으로 정렬된다.

응답 스키마:

{
  "total": 50000,
  "token": "NEXT_PAGE_TOKEN",
  "data": [ ... ]
}

relevance search와의 차이:

hurl 테스트¶

hurl --variable s2_api_key=$S2_API_KEY --variable query=transformer+attention api/graph/paper-bulk-search.hurl

--variable 옵션으로 검색어를 변경할 수 있다. --json 플래그를 추가하면 캡처된 값(total, token 등)을 JSON으로 출력한다.

3.3 Paper Title Match¶

제목과 가장 유사한 단일 논문을 찾는다. 이미 제목을 알고 있을 때 해당 논문의 S2 메타데이터를 가져오는 데 적합하다.

GET /graph/v1/paper/search/match

특징: - 항상 단일 결과만 반환 (가장 높은 매칭 점수의 논문 1개) - 응답에 matchScore 필드가 포함됨 - 매칭 실패 시 404 에러: "Title match not found"

파라미터:

예시:

# 제목으로 논문 찾기
curl "https://api.semanticscholar.org/graph/v1/paper/search/match?query=Attention+Is+All+You+Need&fields=title,year,authors"

# 존재하지 않는 제목 → 404
curl "https://api.semanticscholar.org/graph/v1/paper/search/match?query=totalGarbageNonsense"

응답 스키마:

{
  "data": [
    {
      "paperId": "...",
      "title": "...",
      "matchScore": 87.5
    }
  ]
}

data 배열로 감싸져 있지만 항상 0~1개 결과만 포함된다. matchScore는 제목 매칭 신뢰도 점수다.

hurl 테스트¶

hurl --variable s2_api_key=$S2_API_KEY --variable query=Attention+Is+All+You+Need api/graph/paper-title-match.hurl

--variable query=...로 찾고자 하는 논문 제목을 지정한다. --json 플래그를 추가하면 paper_id, match_score 등 캡처된 값을 JSON으로 출력한다.

3.4 Paper Autocomplete¶

인터랙티브 검색 자동완성용. 부분 쿼리에 대해 최소 정보(제목 등)를 빠르게 반환한다.

GET /graph/v1/paper/autocomplete

파라미터:

응답 스키마:

{
  "matches": [
    { "id": "...", "title": "...", "authorsYear": "Beltagy et al., 2019" }
  ]
}

hurl 테스트¶

hurl --variable s2_api_key=$S2_API_KEY --variable query=attention+is+all api/graph/paper-autocomplete.hurl

--variable query=...로 부분 쿼리를 지정한다. --json 플래그를 추가하면 자동완성 결과를 JSON으로 출력한다.

3.5 Snippet Search¶

논문의 본문 텍스트 스니펫을 직접 검색한다. 제목/초록뿐 아니라 본문 내용까지 검색 가능하다. 약 500단어 길이의 발췌문을 반환하며, 그림 캡션과 참고문헌은 제외된다.

GET /graph/v1/snippet/search

제한사항: - query는 필수 - limit 미지정 시 기본 10건 반환 - limit 최대 1,000

파라미터:

authors 필터 상세: - AND 로직: authors=galileo,kepler → 두 저자 모두 포함된 논문 - 퍼지 매칭: 편집 거리 2 이내 유사 이름도 매칭 (keppler → kepler) - OR 검색이 필요하면 각 저자별 별도 검색 수행 - 최대 10명, 초과 시 400 에러

fields 파라미터 (snippet 전용):

paper와 score는 항상 반환. fields로 snippet 하위 필드를 제어한다:

fields=snippet.text                              # 텍스트만
fields=snippet.text,snippet.snippetKind          # 텍스트 + 위치 종류
fields=snippet.annotations.sentences             # 문장 주석만

기본 반환 필드 (fields 미지정 시): - snippet.text, snippet.snippetKind, snippet.section - snippet.snippetOffset (start, end 포함) - snippet.annotations.refMentions (start, end, matchedPaperCorpusId) - snippet.annotations.sentences (start, end)

응답 구조:

각 결과에는 다음이 포함된다:

예시:

curl "https://api.semanticscholar.org/graph/v1/snippet/search?query=The+literature+graph+is+a+property+graph&limit=1"

hurl 테스트¶

hurl --variable s2_api_key=$S2_API_KEY --variable query=literature+graph+property+graph api/graph/snippet-search.hurl

--variable query=...로 검색어를 변경할 수 있다. --json 플래그를 추가하면 스니펫 텍스트와 점수 등 캡처된 값을 JSON으로 출력한다.