6. 추천 API¶

Base URL: https://api.semanticscholar.org/recommendations/v1

6.1 단일 논문 기반 추천¶

하나의 논문을 기준으로 유사한 논문을 추천받는다.

GET /recommendations/v1/papers/forpaper/{paper_id}

파라미터:

이름	위치	타입	필수	기본값	설명
`paper_id`	path	string	✅		기준 논문 ID
`limit`	query	integer		100	추천 수 (최대 500)
`fields`	query	string			반환할 필드 목록
`from`	query	string		`recent`	추천 풀: `recent` 또는 `all-cs`

추천 풀(from) 옵션:

값	설명
`recent`	최근 논문 풀에서 추천 (기본값)
`all-cs`	전체 CS 분야 논문 풀에서 추천

예시:

curl "https://api.semanticscholar.org/recommendations/v1/papers/forpaper/649def34f8be52c8b66281af98ae884c09aef38b?fields=title,year&limit=5&from=recent"

응답:

{
  "recommendedPapers": [
    { "paperId": "...", "title": "...", "year": 2024 }
  ]
}

hurl 테스트¶

hurl --variable s2_api_key=$S2_API_KEY --variable paper_id=649def34f8be52c8b66281af98ae884c09aef38b api/recommendations/single-paper.hurl

--variable paper_id=...로 기준 논문 ID를 변경할 수 있다. --json 플래그를 추가하면 캡처값(rec_count, first_paper_id)을 JSON으로 출력한다.

6.2 다중 논문 기반 추천 (Positive/Negative)¶

여러 논문을 positive(유사하게)/negative(회피하게) 예시로 제공하여 맞춤 추천을 받는다.

POST /recommendations/v1/papers/

쿼리 파라미터:

이름	타입	필수	기본값	설명
`limit`	integer		100	추천 수 (최대 500)
`fields`	string			반환할 필드 목록

요청 본문:

{
  "positivePaperIds": [
    "649def34f8be52c8b66281af98ae884c09aef38b"
  ],
  "negativePaperIds": [
    "ArXiv:1805.02262"
  ]
}

positivePaperIds: "이런 논문과 비슷한 것을 원해" — 추천의 기준
negativePaperIds: "이런 논문은 원하지 않아" — 추천에서 배제할 방향

참고: Swagger 스키마상 두 필드 모두 선택적(optional)이나, 실질적으로 positivePaperIds에 최소 1개 이상의 논문 ID가 필요하다.

다양한 ID 형식을 혼합 사용 가능 (S2 ID, ArXiv, DOI 등)

응답:

{
  "recommendedPapers": [
    { "paperId": "...", "title": "...", "year": 2024 }
  ]
}

hurl 테스트¶

hurl --variable s2_api_key=$S2_API_KEY api/recommendations/multi-paper.hurl

논문 ID는 hurl 파일의 JSON body에 직접 정의되어 있다. positivePaperIds/negativePaperIds를 변경하려면 api/recommendations/multi-paper.hurl 파일을 편집한다. --json 플래그를 추가하면 캡처값(rec_count, first_paper_id)을 JSON으로 출력한다.