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:
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 |