journal-if

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

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

Error codes (inside error.code)

Data Sources

1. Bundled CSV — ~200 top journals across life sciences, medicine, chemistry, physics, and engineering. Curated from JCR data, shipped with the skill. Always available, instant.

1. 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

Workflow

Step 1: Detect Intent

Step 2: Execute

Run the appropriate journal_if.py command. The script handles:

1. Local CSV lookup (instant, ~200 curated journals)
2. OpenAlex API fallback (automatic, approximate 2-year IF)
3. 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

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