If words like "API," "JSON," or "citation graph" feel slippery, this chapter is for you. If you've already wired any HTTP API to a script before, skip ahead to Chapter 03.

"API", "JSON", "citation graph" 같은 단어가 아직 낯설다면 이 챕터부터 읽으세요. HTTP API를 한 번이라도 스크립트로 불러본 경험이 있다면 Chapter 03으로 점프해도 OK.

Where should I start?

어디서부터 읽을까?

What you need before you start

시작 전 준비물

What's an API? — the 60-second version

API가 뭔가요? — 60초 설명

An API (Application Programming Interface) is a structured way for one program to ask another program for data. Think of a vending machine: you press buttons in a defined pattern and the machine returns a defined result. Press "B4" and a chocolate bar drops; send GET /works/W2741809807 to OpenAlex and you get one paper's metadata back.

API (Application Programming Interface)는 한 프로그램이 다른 프로그램한테 데이터를 정해진 방식으로 요청하는 통로입니다. 자판기와 비슷해요. "B4"를 누르면 초콜릿이 나오는 것처럼, OpenAlex에 GET /works/W2741809807를 보내면 그 논문 한 편의 메타데이터가 돌아옵니다.

OpenAlex's API "speaks" via plain URLs over HTTPS. Paste an OpenAlex URL into your browser and you'll get the answer right there as JSON. No special client library needed.

OpenAlex API는 HTTPS 위의 일반 URL로 "말합니다". 브라우저에 OpenAlex URL을 붙여넣으면 바로 그 자리에 JSON으로 답이 나와요. 특별한 클라이언트 라이브러리 필요 없음.

What's JSON?

JSON이란?

JSON (JavaScript Object Notation) is a way to write structured data using nested keys and values. Imagine a spreadsheet whose cells can themselves contain spreadsheets. The OpenAlex response for one paper looks like this (truncated):

JSON (JavaScript Object Notation)은 키와 값을 중첩해서 구조화된 데이터를 표현하는 방식입니다. 셀 안에 다시 표가 들어가는 스프레드시트라고 생각하면 됩니다. OpenAlex가 논문 한 편을 돌려줄 때 이렇게 생겼어요 (일부 생략):

Don't worry about reading every field. The helper script (Pattern B) extracts only the fields you need.

모든 필드를 다 읽을 필요는 없어요. 헬퍼 스크립트 (Pattern B)가 필요한 것만 뽑아냅니다.

What's a "citation graph"?

"인용 그래프"가 뭔가요?

A citation graph is a network where each node is a paper and each edge is "this paper cited that one." OpenAlex stores both directions of every edge:

인용 그래프는 노드가 논문이고 엣지가 "A가 B를 인용했다"인 네트워크입니다. OpenAlex는 모든 엣지를 양방향으로 저장합니다:

• referenced_works — papers this paper cited (looking backward in time)
• cited_by_count + filter cites:W… — papers that cited this one (looking forward in time)

• referenced_works — 이 논문이 인용한 논문들 (과거 방향)
• cited_by_count + 필터 cites:W… — 이 논문을 인용한 논문들 (미래 방향)

Your first OpenAlex call — 30 seconds, no install

첫 OpenAlex 호출 — 30초, 설치 불필요

Paste this URL into any web browser:

아래 URL을 브라우저에 붙여넣으세요:

You should see a wall of JSON. Congratulations — you just used the OpenAlex API. The same URL works from curl, Python, R, or a Claude Code prompt.

JSON 덩어리가 보일 거예요. 축하합니다 — 방금 OpenAlex API를 호출하신 겁니다. 같은 URL이 curl, Python, R, Claude Code 프롬프트 어디서든 작동해요.

Mini glossary — terms you'll hit in this guide

미니 용어집 — 본 가이드에 나올 용어

Open any term to expand its definition. These come back throughout the guide.

아래 용어를 펼쳐 보세요. 가이드 곳곳에서 다시 등장합니다.

Vocabulary in place — head to Chapter 01 to see why this combo matters, or jump to Chapter 03 if you want the technical body.

기본 어휘가 잡혔으면 Chapter 01로 이동해서 왜 이 조합이 중요한지 보거나, 바로 기술적 본체가 보고 싶으면 Chapter 03으로 점프.

Workflows like /research, /content, and /analysis all stand on a single class of question — who, when, what, and how was cited? The conventional answer cycle is: Google Scholar search → grab BibTeX → tidy in Zotero. That's fine once. Repeated across a serious literature scan, it eats hours every week.

/research, /content, /analysis 워크플로는 모두 "누가, 언제, 무엇을, 어떻게 인용했나"라는 질문 위에 서 있습니다. 이 답을 매번 Google Scholar 검색 → BibTeX 긁기 → Zotero 정리로 얻으면 한 번이면 괜찮지만, 자료조사를 본격적으로 시작하면 같은 작업을 수십 번 반복합니다.

OpenAlex collapses that cycle into a single API call. It's an open scholarly metadata graph that integrates Crossref, ORCID, the (former) Microsoft Academic Graph, and ROR — all callable for free without a token. Claude Code is what threads natural-language prompts through OpenAlex API calls, into result parsing, analysis, and visualization, all in one go.

OpenAlex는 이 루프를 API 호출 한 번으로 압축합니다. Crossref + ORCID + (구) Microsoft Academic + ROR을 통합한 오픈 학술 메타데이터 그래프이고, 토큰 없이 무료로 호출할 수 있어요. Claude Code는 자연어 프롬프트를 OpenAlex API 호출 + 결과 파싱 + 분석 + 시각화로 바로 연결해주는 컨트롤러입니다.

• Pull the full publication list of a journal / author / topic in one call
• Walk both directions of a citation graph — what a paper cites, and what cites it
• Build year-by-year, journal-by-journal, author-by-author citation matrices
• Set up review-automation workflows like "five most-cited papers that cited this one"
• Decompose a new research idea into an API sequence so the data flow is designed before the first call

• 특정 저널·저자·토픽의 전체 논문 리스트를 한 번에 받아오기
• 한 논문이 어떤 논문을 인용했고, 어떤 논문에 인용됐는지 양방향으로 따라가기
• 연도별·저널별·저자별 인용 매트릭스 만들기
• "이 논문 인용한 최근 5편" 같은 리뷰 자동화 워크플로 짜기
• 새 연구 아이디어를 API 시퀀스로 분해해서 데이터 흐름을 설계하기

Prerequisites: comfortable enough at a terminal to run a one-line command. Python experience helps but isn't required — every example in this guide is dispatched as a single Claude Code prompt.

필요한 사전 지식: 터미널에서 명령어 한두 줄 실행할 수 있으면 충분합니다. Python 사용 경험은 도움되지만 필수는 아니에요 — 본 가이드의 모든 예시는 Claude Code 프롬프트 한 줄로 처리됩니다.

OpenAlex is run by the non-profit OurResearch. It assumed the role of the discontinued Microsoft Academic Graph (MAG) in 2022. All data is CC0 (public domain), the API is free, and a complete monthly dump (~330 GB) is published.

OpenAlex는 비영리 단체 OurResearch가 운영하는 오픈 학술 그래프입니다. 2022년 Microsoft Academic Graph가 종료되면서 그 역할을 이어받았어요. 모든 데이터는 CC0(퍼블릭 도메인), API는 무료, 다운로드는 매월 전체 덤프(~330GB) 제공.

Entity model — seven endpoints in one diagram

엔티티 모델 — 7가지 endpoint, 한 그림

URL grammar — just five patterns

URL 문법 — 5패턴이면 끝

OpenAlex's API is plain REST URLs — paste one into a browser and it returns JSON. The whole grammar reduces to five patterns.

OpenAlex API는 단순 REST URL이라서 브라우저에 그냥 붙여넣어도 JSON이 떨어집니다. 패턴은 5개로 압축됩니다.

Most real calls are ③ + ④ combined.

대부분의 실전 호출은 ③+④ 조합입니다.

Anatomy of one URL — every piece labeled

URL 한 줄 해부 — 각 부분의 의미

Beginner-friendly tip: the URL is readable. Read it top to bottom — once you can read this, you can write any OpenAlex URL.

초보자용 팁: 이 URL은 위에서 아래로 읽히는 구조라서 직접 조립해도 무리 없어요. 이걸 읽을 수 있으면 어떤 OpenAlex URL이든 쓸 수 있습니다.

30-second signup

30초 가입

1. Go to openalex.org/settings/api and sign in with your email.
2. Copy the API key (a single string).
3. Save it to a shell variable so it stays out of your prompts and files:
   setx OPENALEX_KEY "your-key" (Windows) or echo 'export OPENALEX_KEY="your-key"' >> ~/.bashrc (macOS / Linux).

1. openalex.org/settings/api에 가서 이메일로 로그인.
2. 발급된 API 키 (단일 문자열)를 복사.
3. 프롬프트나 파일에 직접 박지 말고 환경변수로 저장:
   setx OPENALEX_KEY "your-key" (Windows) 또는 echo 'export OPENALEX_KEY="your-key"' >> ~/.bashrc (macOS · Linux).

How it goes into a request

요청에 어떻게 붙는가

Append &api_key=YOUR_OPENALEX_KEY to every URL. The helper script (Pattern B) reads the env var OPENALEX_KEY and injects it automatically — you never type the key into a prompt.

모든 URL 끝에 &api_key=YOUR_OPENALEX_KEY를 붙입니다. 헬퍼 스크립트(Pattern B)는 환경변수 OPENALEX_KEY를 읽어 자동 주입하므로 프롬프트에 키를 직접 적을 일이 없어요.

Credit-based rate limits (current model)

크레딧 기반 rate limit (현 모델)

For ordinary research use, the free tier is effectively unlimited. A typical literature scan or one journal-decade pull rarely passes 1,000 list calls, well below the daily $1 budget. See developers.openalex.org/api-reference/authentication for the live numbers.

일반 연구 용도에서는 무료 티어가 사실상 무제한입니다. 자료조사 한 번이나 한 저널의 10년 수집은 list call 1,000회를 거의 안 넘어요 — $1 일일 예산의 한참 아래. 최신 수치는 developers.openalex.org/api-reference/authentication 참조.

There are essentially three ways to use OpenAlex from Claude Code. One-shot questions: A. Repeated use: B. Across many sessions and projects: C. Climb the ladder as the work justifies it.

OpenAlex를 Claude Code에서 쓰는 방법은 본질적으로 3가지입니다. 일회성 답변이면 A, 반복 사용이면 B, 여러 세션·여러 프로젝트면 C로 단계적으로 올라갑니다.

Setup time: zero. Just ask Claude Code in plain language. Claude assembles the URL, fetches with WebFetch / curl, parses the JSON, and answers.

셋업 0분. Claude Code에 그냥 자연어로 부탁하면 Claude가 WebFetch나 Bash + curl로 OpenAlex API를 직접 부르고 결과를 정리합니다.

Step-by-step — running your first prompt

첫 프롬프트 실행 — 단계별로

Claude turns that into:

Claude는 위 프롬프트를 받으면 다음 URL을 만들어 호출합니다:

Drop a small Python helper into the project once; from then on, every Claude Code prompt invokes it via Bash. This is the recommended pattern.

프로젝트마다 작은 Python 헬퍼를 한 번만 깔아두고, Claude Code가 Bash로 호출하게 하는 방식. 가장 권장되는 패턴입니다.

This guide ships openalex_helper.py in the downloads folder. The core functions:

본 가이드는 다운로드에 openalex_helper.py를 동봉합니다. 핵심 함수만 보면:

After that, Claude Code prompts get short:

그 다음부터 Claude Code 프롬프트는 짧아집니다:

Register OpenAlex as a first-class Claude Code tool, callable from every session and project without explicit imports.

OpenAlex를 Claude Code의 1급 도구로 등록하는 방식. 모든 세션·모든 프로젝트에서 별도 import 없이 호출 가능합니다.

There's no official OpenAlex MCP yet (as of 2026-05), but Anthropic's MCP TypeScript SDK lets you build one in roughly 30 minutes. The pattern is: write the tool spec at ~\.claude\mcp_servers\openalex\index.js and register it in ~\.claude\mcp.json.

아직 OpenAlex 공식 MCP는 없지만(2026-05 기준), Anthropic의 MCP TypeScript SDK로 30분이면 만들 수 있어요. 핵심은 ~\.claude\mcp_servers\openalex\index.js에 도구 명세를 적고, ~\.claude\mcp.json에 등록하는 것.

The most important chapter in this guide. Knowing how to decompose an idea matters more than knowing the tool — that's where the time savings come from.

이 가이드의 가장 중요한 챕터입니다. 도구를 아는 것보다 "어떻게 분해할 것인가"를 아는 것이 시간을 아낍니다.

When a research idea arises, jumping straight to the first API call almost always returns the wrong data. Train yourself to decompose it through these five steps.

연구 아이디어가 떠올랐을 때 바로 첫 API 호출로 직진하면 거의 항상 잘못된 데이터를 받습니다. 다음 5단계로 분해하는 습관을 들이세요.

Three core mental tools

핵심 사고 도구 3가지

1. Map cardinality first

1. Cardinality 먼저 그리기

Sketch the structure on paper before the call: "1 author → N papers → M topics." Cardinality determines pagination, memory budget, and total call count.

"1 저자 → N 논문 → M 토픽" 같은 관계를 종이에 먼저 그립니다. 이게 페이지네이션·메모리 예산·총 호출 수를 결정해요.

• 1:1 (one author → one ORCID) → 1 API call
• 1:N, N<200 → 1 call (per_page=200)
• 1:N, N>200 → cursor pagination
• N:M graph → two stages: collect entities, then enrich relations

• 1:1 (한 저자 → 한 ORCID) → API 1회
• 1:N, N<200 → API 1회 (per_page=200)
• 1:N, N>200 → cursor 페이지네이션
• N:M 그래프 → 두 단계: entity 모집 후 관계 enrichment

2. Filter cascade — wide → narrow

2. Filter cascade — 넓→좁

Don't apply every filter at once. Step them in. That way you can verify each intermediate result is reasonably sized before adding the next constraint.

필터를 한 번에 다 거는 게 아니라 단계적으로 좁힙니다. 그래야 중간 결과가 합리적인 크기인지 확인할 수 있어요.

3. One prompt = one step

3. 한 프롬프트 = 한 단계

If you ask Claude to do all 5 steps in one prompt, mistakes from step 1 propagate to step 5 invisibly. Stepping them lets you eyeball the intermediate file (data/sources.json) for one second before moving on. That's the pattern that actually delivers automation ROI.

5단계를 한 번에 시키면 Claude가 1단계에서 잘못 추론한 source_id를 끝까지 끌고 갑니다. 단계별로 끊으면 사용자가 중간 산출물(data/sources.json)을 1초 검수하고 다음 프롬프트로 넘어갈 수 있어요. 이게 자동화 ROI를 만드는 진짜 패턴입니다.

Discourse Lens (Educatian/discourse-lens, MVP 2026-04-29) is a research tool that BERTopic-clusters Learning Sciences ↔ Educational Technology journal abstracts from 2015–2025 and visualizes them with D3. v1 saw only abstract text.

Discourse Lens는 Learning Sciences ↔ Educational Technology 저널 abstract들을 2015–2025년에 걸쳐 BERTopic으로 클러스터링하고 D3로 시각화한 연구 도구입니다 (Educatian/discourse-lens, MVP 2026-04-29). v1은 abstract 텍스트만 봤어요.

v2's new question: "How much, and how, do these two fields cite each other? Has that relation shifted over time?"

v2의 새 질문: "LS와 ET 두 분야는 서로를 얼마나, 어떻게 인용하나? 시간이 지나며 그 관계가 변화했나?"

v1 in your browser — embedded

v1 라이브 임베드

Below is the live Discourse Lens v1 app. Use it to build intuition for what v2's citation layer would augment.

아래는 라이브 v1 앱입니다. v2가 어떤 citation layer를 추가하게 될지 직관을 잡는 용도로.

Plug v2's question into the §9 funnel:

이 질문을 § 9의 5단계 깔때기에 넣어보면:

v2 build-along — 5 prompts

v2 build-along — 5개 프롬프트로

A fuller walkthrough (expected outputs · failure cases · 4 extension ideas) is in the downloadable discourse_lens_v2_recipe.md.

더 자세한 워크스루 (예상 산출물 · 실패 케이스 · 확장 4가지)는 다운로드의 discourse_lens_v2_recipe.md를 보세요.

Copy-paste prompts — just swap topic / DOI / ORCID. Longer version (30+ prompts) in prompts.md.

복사해서 토픽·DOI·ORCID만 바꾸면 바로 쓰는 프롬프트 모음. 더 긴 버전은 prompts.md (30+ 프롬프트).

Author tracking

저자 추적

Citation graph

인용 그래프

Review automation

리뷰 자동화

All bundled in the same folder; self-contained companion files.

모두 같은 폴더에 동봉된 self-contained 보조 자료입니다.

Foundational sources

• Priem, J., Piwowar, H., & Orr, R. (2022). OpenAlex: A fully-open index of scholarly works, authors, venues, institutions, and concepts. arXiv:2205.01833.
• OpenAlex API documentation — developers.openalex.org
• OpenAlex API root — api.openalex.org

Related tooling

• pyalex — Python client. github.com/J535D165/pyalex
• Semantic Scholar API — api.semanticscholar.org
• Crossref REST API — api.crossref.org
• Anthropic MCP TypeScript SDK — github.com/modelcontextprotocol/typescript-sdk

Case study

• Discourse Lens repository — Educatian/discourse-lens (2026-04-29 MVP). Live demo: educatian.github.io/discourse-lens

This guide does not replace OpenAlex's official documentation. It is a practical onboarding guide layered on the foundational sources above. When in doubt, defer to developers.openalex.org's latest spec. The Discourse Lens case study uses synthetic results purely as illustration, not as a real analysis report.

이 가이드는 OpenAlex의 official documentation을 대체하지 않습니다. 본 문서는 practical onboarding guide이고, foundational sources는 위 references입니다. API 동작이 의심스러우면 항상 developers.openalex.org의 최신 명세를 우선하세요. Discourse Lens 케이스 스터디의 합성 결과는 예시일 뿐 실제 분석 보고가 아닙니다.