2026년 9월 6일 일요일

[바이브 코딩] OpenAlex - API 키 없이 3.2억 편의 논문을 검색하는 학급 논문 탐색기



3.2억 편의 논문 무료 검색 — OpenAlex로 만드는 학급 논문 탐색기

📚 API 키 없이 바로 검색(오늘 실측) — 인류가 쌓아 온 3억 2,400만 편의 논문 메타데이터(제목·저자·저널·피인용 수·DOI)가 CC0 공개 데이터로 열려 있습니다. 다만 2026년 현재 하루 무료 API 사용 예산이 운영되며, 무료 API 키를 발급해 넣으면 예산이 10배가 됩니다. 이번 글에서 실측한 대로 '광합성' 한 번 검색에 약 60만 편, 2024년 + 제목 조건 검색에 약 4.9만 편이 즉시 나옵니다.

논문은 '어른들의 실험 보고서'입니다. 학생이 직접 검색해 보는 경험은 정보 리터러시(출처·인용·DOI)의 첫걸음이자, 과학·사회 탐구 과제의 재료 창고가 됩니다. 학내망 '외부 호출 0' 원칙도 주제 고정 심기(오프라인) 모드로 깔끔하게 지킵니다.

📖 한 줄 정의

심기 모드(데이터 임베딩): API 데이터를 미리 받아 HTML 파일 안 상수로 박아두는 방식(앱 실행 중 외부 통신 0).

학내망 원칙: 학교 배포 웹앱은 개인정보 수집·저장·전송 없음(외부 CDN·API 호출 0, 단일 파일) — 학생은 학내망에서 교사 PC 서버에 접속.

1. 3대 핵심 분석 비교표

무엇이 바뀌었나요? / 영역 초보자를 위한 쉬운 설명 이렇게 한번 써보세요!
규모와 무료 "인류의 실험 보고서 창고." 2026년 9월 5일 실측 기준 논문 3억 2,400만 편, 저자·대학·저널 정보까지 함께. 키 없이 URL만으로 JSON을 돌려주며, 하루 무료 API 예산이 자동으로 주어집니다(무료 키를 넣으면 10배). works 주소 뒤에 ?per-page=1&select=id를 붙이면 → meta.count가 곧 전체 편수!
자원과 검색 주소 = 창고(api.openalex.org) + 자원(works=논문, authors=저자, institutions=기관) + 조건. search=는 제목·초록·본문까지 뒤지는 넓은 검색입니다. ?search=photosynthesis → 실측 599,056편이 한 번에 나열됩니다.
정밀 검색(필터) filter=는 조건을 정확히 걸어줍니다. 조건 여러 개는 쉼표로 이어 붙이면 AND 검색이 됩니다. 실측: 2024년 + 제목에 climate → 49,281편. ?filter=publication_year:2024,title.search:climate → 연도·제목 정밀 검색.
응답 다이어트 논문 1건이 약 17KB나 되는 덩치입니다. select=로 필요한 칸만 고르고 per-page=로 건수를 조절하면(공식 문서 기준 최대 100) 응답이 가벼워집니다 — 실측으로 확인했고, 하루 예산도 아껴집니다. ?select=id,doi,title,publication_year,cited_by_count&per-page=10 → 딱 필요한 목록.
학내망 배포 대응 검색기는 검색어마다 답이 달라져 심기가 까다롭습니다. 해법은 주제 고정 심기: 우리 반 탐구 주제 논문 20편을 미리 받아 슬림 JSON으로 심으면 학생 단말은 통신 0으로 돌아갑니다. fetch 실시간 모드 → 교사 PC 시연용. 심기 모드 → 학내망 배포용. EMBED_DATA 상수 하나로 전환.

2. 핵심 아키텍처 해설 — 논문 창고는 이렇게 생겼다

① URL 해부: search와 filter는 다른 도구

https://api.openalex.org/works?search=photosynthesis&per-page=1

  • api.openalex.org — 논문·저자·기관 데이터 전용 창고. 루트 주소를 열면 "Don't panic"이라는 인사가 나옵니다(문서는 /docs).
  • works — 논문 자원. authors(저자), institutions(기관), sources(저널) 같은 자원도 같은 방식으로 동작합니다.
  • search= — 넓은 검색. 제목+초록+본문을 한꺼번에 뒤집니다(실측: '광합성' 검색이 본문까지 뒤져 59만 편).
  • filter= — 좁은 검색. title.search:(제목만), publication_year:(연도)처럼 칸 단위로 정확히 걸어냅니다.

검색 결과의 meta.count가 곧 '조건에 맞는 전체 편수'입니다 — 몇 편이나 나오는지부터 보여주니 수업에서 '검색 좁히기' 훈련에 딱입니다.

② 데이터 모양: select로 슬림하게 받기

{
  "meta": { "count": 49281 },
  "results": [{
    "id": "https://openalex.org/W1650569836",
    "doi": "https://doi.org/10.1163/9789004322714_cclc_2023-0258-1193",
    "title": "Climate Change 2023 Synthesis Report",
    "publication_year": 2024,
    "cited_by_count": 2377
  }]
}

DOI는 논문의 주민등록번호 같은 세계 공통 주소입니다. cited_by_count(피인용 수)는 '이 보고서가 다른 연구에서 몇 번 인용되었나' — 수업에서 인용 수 순위 매기기를 하면 출처의 힘이 눈에 보입니다.

③ 초록의 함정: abstract_inverted_index

OpenAlex는 초록(요약문)을 문장이 아니라 '단어 → 단어가 등장한 위치 목록' 지도로 저장합니다. 실측 예: "We": [0], "discuss": [1], "the": [2, 29]... — 0번 칸에 We, 1번 칸에 discuss. 이 지도를 위치 순으로 다시 세우면 원문이 됩니다.

function rebuildAbstract(inverted) {
  if (!inverted) return "";
  const words = [];
  for (const word in inverted) {
    for (const pos of inverted[word]) words[pos] = word;
  }
  return words.join(" ");
}

'데이터가 생기는 모양과 사람이 읽는 모양은 다를 수 있다'를 가르치는 최고의 소재입니다.

④ 검색 코드: URLSearchParams로 조립

const API = "https://api.openalex.org/works";

async function searchPapers(topic, year) {
  const qs = new URLSearchParams({
    filter: "title.search:" + topic + ",publication_year:" + year,
    "per-page": 10,
    select: "id,doi,title,publication_year,cited_by_count"
  });
  const res = await fetch(API + "?" + qs);
  const json = await res.json();
  return json;   // json.meta.count = 검색 건수, json.results = 논문 목록
}

⑤ 비용·속도 관리: meta.cost와 429

2026년 현재 OpenAlex에는 하루 무료 API 예산이 있습니다. 오늘 실측에서 논문 조회 1회의 meta.cost는 0.0001~0.001 수준이었으니, 슬림 요청(select·per-page=100)을 쓰면 수업용으로는 예산 안에서 충분히 돌아갑니다. 예산 초과나 초당 100건 초과 시 429(Too Many Requests)가 오는데, 응답 헤더의 X-RateLimit-Remaining으로 남은 예산을 미리 볼 수 있습니다.

{
  "meta": { "count": 324184258, "cost_usd": 0.0001, "per_page": 1 }
}

30~40명이 동시에 쓰는 교실이라면 심기 모드(데이터 임베딩)로 미리 데이터를 심어두는 것이 예의이자 설계의 미덕입니다 — 학생 단말은 통신 0이니 예산도 0입니다.

⑥ 학내망 전략: 주제 고정 심기

탐구 주제가 정해진 수업이라면, 교사가 미리 주제 논문 목록을 받아 EMBED_DATA 상수로 심습니다. 심기 모드(데이터 임베딩)가 무엇인지는 앞의 '📖 한 줄 정의' 박스를 참고하세요 — 파일 상단 EMBED_DATA에 슬림 목록을 넣으면 fetch를 완전히 생략하는 외부 호출 0 모드가 됩니다.

const EMBED_DATA = null;   // null이면 fetch 모드 — 여기에 슬림 논문 목록을 심으면 심기 모드

3. 초보자를 위한 바이브 코딩 실전 사용 예시

  1. 프롬프트 복사 — 아래 '제미나이 전용 에러 제로 프롬프트' 전체를 복사해 Gemini에 붙여넣습니다.
  2. 역질문 답변 — Gemini가 던지는 질문 3가지(기본 주제·연도, 데이터 모드, 화면 톤)에 답하면 설계가 확정됩니다.
  3. HTML 파일 실행 — 완성 코드를 '논문탐색기.html'로 저장 후 더블클릭. 심기 모드 파일이면 곧 학내망 배포본입니다.

제미나이 전용 에러 제로 프롬프트

[🚨 에러 방지 기본 안전장치]
1. 결과물은 외부 라이브러리·프레임워크·웹폰트 없이 단일 HTML 파일로 완성한다. (OpenAlex 데이터 fetch는 유일한 외부 통신 예외)
2. 사운드는 Web Audio API로 직접 합성한다: 검색 성공 시 부드러운 '똑' 소리, 결과 0건·통신 실패 시 '삑' 경고음. 오디오 파일·CDN 사운드 사용 금지.
3. 모바일 터치 대응: 뷰포트 메타 태그 필수, 버튼 최소 44×44px, 입력 필드 font-size 16px 이상, 360px 화면에서 가로 스크롤 금지.
4. 데이터 주소는 https://api.openalex.org/works 이며, 요청에는 반드시 per-page(10 이내)와 select(제목·연도·피인용 수 등 필요한 칸만)를 붙여 응답을 슬림하게 유지한다.
5. 초록 표시에는 반드시 abstract_inverted_index를 위치 순으로 재조립하는 함수를 쓴다(원문 지도를 그대로 화면에 뿌리지 않는다).
6. 파일 상단 EMBED_DATA 상수에 슬림 논문 목록이 심어져 있으면 fetch를 완전히 생략한다(학내망 배포용 외부 호출 0 모드). 검색 건수(meta.count)도 함께 표시한다.
7. OpenAlex는 하루 무료 API 예산이 있으므로, 429 응답 시 '오늘의 무료 예산을 다 썼어요 — 내일 다시 검색해 보자'라는 친절한 안내 화면을 보여준다.
8. // TODO, /* 생략 */ 같은 미완성 코드는 절대 넣지 말고 끝까지 완성한다.

[❓ 역질문 유도]
코드를 바로 만들지 말고, 아래 3가지를 먼저 나에게 질문한 뒤 내 답변으로 설계를 확정한다.
Q1. 기본으로 띄울 탐구 주제와 연도는 무엇으로 할까? (예: 광합성, 2024년)
Q2. 데이터 모드는 무엇으로 할까? (A: 실시간 fetch 모드 / B: 학내망용 주제 고정 심기 모드)
Q3. 화면 톤은? (카드 목록 / 피인용 수 순 정렬 토글 포함)

🎯 에디터 한줄평

'논문'이라는 단어에 겁먹은 학생에게 3억 편의 창고를 열어주는 일 — 이 API의 진짜 힘은 규모가 아니라 meta.count로 '검색을 좁히는 감각'을 훈련시킨다는 점입니다. 인용 수 순위 매기기, DOI 따라가 보기 같은 놀이가 그대로 정보 리터러시 수업이 됩니다. 초록이 단어 위치 지도로 저장되어 있다는 함정은 '데이터를 복원하는 코드'를 짜는 즐거움으로 바꿔줍니다. 학내망 원칙까지 주제 고정 심기로 깔끔하게 통과한 설계도 훌륭합니다.

📚 기술·교육 참고 링크

  • OpenAlex 공식 헬프센터 : 자원·필터·페이지네이션 전체 정리(2026-09 개편)
  • API 키·속도 제한 안내 : 무료 예산 10배, 429 응답 읽는 법
  • 의미 검색(시맨틱 서치) : 문단으로 질문하는 AI 임베딩 검색 — '임베딩'이라는 단어의 또 다른 쓰임
  • OpenAlex 웹 탐색기 : API 없이 웹에서 데이터 탐색 연습
  • API 루트 : 접속하면 "Don't panic" 인사 — 서버 상태 확인용
  • 교육과정 연계: 정보(정보 판별·출처 확인), 과학·사회 탐구(보고서 재료 찾기), 국어(요약문 구조 이해)와 함께 활용
By 시간: