Journal Impact Factor Lookup

Look up journal impact factors using a two-source cascade: bundled CSV cache (~200 common journals) → OpenAlex API (approximate 2-year IF for any journal).

Critical rule: Always use

journal_if.py

for lookups. Never guess impact factors — they change yearly and vary by edition.

Quick Reference

User wants...	Tier	Command
Look up IF of a journal	read	`python3 journal_if.py lookup "Nature Medicine"`
Search for a journal	read	`python3 journal_if.py search "cancer immunology"`
Process a list of journals	read	`python3 journal_if.py batch journals.txt`
Cache-only (no network)	read	`python3 journal_if.py --offline lookup "Cell"`
Inspect cache state	read	`python3 journal_if.py cache status`
Refresh upstream CSV	write	`python3 journal_if.py cache update`
Machine-readable CLI contract	read	`python3 journal_if.py schema`
Schema for one subcommand	read	`python3 journal_if.py schema lookup`

Output format

Stdout is a stable JSON envelope when the CLI is not attached to a terminal (piped or captured by an agent), and a human-readable view when run on a TTY. To force a format:

--format json|table|human|auto

--json

is a back-compat alias for

--format json

Envelope shape:

Success:

{ "ok": true, "data": {...}, "meta": { "schema_version", "cli_version", "latency_ms" } }

Partial success (batch):

{ "ok": "partial", "data": { "succeeded": [...], "failed": [...] }, "meta": {...} }

Error:

{ "ok": false, "error": { "code", "message", "retryable", ... }, "meta": {...} }

Exit codes

Code	Meaning
`0`	success (including partial success)
`1`	runtime / upstream error
`2`	validation / bad input (missing file, bad flag)
`3`	not found (no journal matched)

Error codes (inside

error.code

)

Code	Retryable	Exit	Meaning
`not_found`	no	3	Lookup completed but no source matched
`upstream_unavailable`	yes	1	OpenAlex API failed transiently; retry later or use `--offline`
`file_not_found`	no	2	Input file path does not exist
`validation_error`	no	2	Bad argument or flag combination
`runtime_error`	yes	1	Unexpected internal error

Data Sources

Bundled CSV — ~200 top journals across life sciences, medicine, chemistry, physics, and engineering. Curated from JCR data, shipped with the skill. Always available, instant.
OpenAlex API — Free, open API that computes an approximate 2-year impact factor from citation counts. Covers virtually all academic journals. The number differs from the official JCR IF — it's a citation-rate metric computed from the same formula (citations in year Y to items published in Y-1 and Y-2, divided by citable items in those two years) but using OpenAlex's own article classification. Adequate for ranking and comparison; do not cite as "the JCR impact factor" in formal contexts.

When to use which

Scenario	Source
Quick check of a major journal	Bundled CSV (instant)
Niche or newer journal	OpenAlex fallback (automatic)
Formal submission / grant	Note: OpenAlex IF ≠ official JCR IF. Cite only as approximate.
Batch processing many journals	CSV for cached ones, OpenAlex for misses
Offline / air-gapped	`--offline` flag (bundled CSV only)

Workflow

Step 1: Detect Intent

Intent	Action
"What's the IF of Nature?"	`lookup "Nature"`
"Compare IF of Cell and Science"	Run `lookup` twice, compare results
"Which immunology journals have IF > 20?"	`search "immunology"` then filter
"Process this list of journals"	`batch journals.txt`
"Is this a high-impact journal?"	`lookup` then interpret IF in field context

Step 2: Execute

Run the appropriate

journal_if.py

command. The script handles:

Local CSV lookup (instant, ~200 curated journals)
OpenAlex API fallback (automatic, approximate 2-year IF)
Fuzzy matching — catches minor name variations

Step 3: Present Results

Show the journal name, impact factor, and data year
Note the source (CSV cache vs OpenAlex approximate)
For search results: show a table with IF, year, and category

Understanding Impact Factor

IF Range	Typical Tier	Example
> 30	Elite (top 0.1%)	Nature (64.8), Science (56.9), Cell (64.5)
20–30	Exceptional (top 1%)	Cancer Cell (50.3), Immunity (32.4)
10–20	Excellent (top 5%)	Nature Communications (16.6), Sci Adv (13.6)
5–10	Strong (top 15%)	eLife (7.7), Cell Reports (8.8)
2–5	Solid	PLOS ONE (3.7), Sci Rep (4.6)
< 2	Niche / new	Many field-specific and new journals

Caveats:

IF varies dramatically by field — a top mathematics journal may have IF < 5 while a mid-tier oncology journal has IF > 10.
Always compare IF within the same field.
The IF data year matters; values shift annually.
OpenAlex approximate IF differs from official JCR IF; treat as a ranking metric, not a certified number.

Batch Processing

Create a text file with one journal name per line:

Nature Medicine
Journal of Biological Chemistry
Proceedings of the National Academy of Sciences

Then run:

bash

python3 journal_if.py batch journals.txt

Troubleshooting

Issue	Solution
"No data found"	Try a shorter/alternative name; use `search` for fuzzy matching
OpenAlex returns 0 or None IF	The journal may be too new (needs 2+ years of data); use `--offline` to check cache only
OpenAlex IF differs from JCR	Expected — OpenAlex uses its own article classification. Use for ranking, not formal citation.
Cache download fails	Check network; the bundled CSV still works offline
Wrong journal matched	Use more specific name; the fuzzy matcher picks the closest substring match

journal-if

NPX Install

Tags

SKILL.md Content

Journal Impact Factor Lookup

Quick Reference

Output format

Exit codes

Error codes (inside
`error.code`
)

Data Sources

When to use which

Workflow

Step 1: Detect Intent

Step 2: Execute

Step 3: Present Results

Understanding Impact Factor

Batch Processing

Troubleshooting

journal-if

NPX Install

Tags

SKILL.md Content

Journal Impact Factor Lookup

Quick Reference

Output format

Exit codes

Error codes (inside error.code)

Data Sources

When to use which

Workflow

Step 1: Detect Intent

Step 2: Execute

Step 3: Present Results

Understanding Impact Factor

Batch Processing

Troubleshooting

Error codes (inside
`error.code`
)