Journal meta

Paper Metadata Lookup

Resolve one paper identifier into a full metadata record. Primary source is OpenAlex (free, no API key); Crossref is a fallback for DOIs OpenAlex hasn't indexed. The journal name is enriched by delegating to two sibling skills when installed:

• journal-abbrev → ISO-4 / MEDLINE journal abbreviation (JabRef cache, ~25K journals)
• journal-if → curated JCR impact factor

If those skills aren't found, it falls back to AbbrevISO (abbreviation) and OpenAlex 2yr_mean_citedness (approximate IF) automatically.

Critical rule: Always use journal_meta.py. Never fabricate authors, corresponding authors, dates, or impact factors — resolve them.

Quick Reference

User wants...	Command
Metadata from a DOI	python3 journal_meta.py "10.1038/s41586-020-2649-2"
Metadata from a PMID	python3 journal_meta.py 32939066
Metadata from an arXiv id	python3 journal_meta.py 1706.03762
Metadata from a title	python3 journal_meta.py "Attention is all you need"
Process a list	python3 journal_meta.py batch papers.txt
Skip impact-factor lookup	python3 journal_meta.py <id> --no-if
Skip abbreviation lookup	python3 journal_meta.py <id> --no-abbrev
Machine-readable contract	python3 journal_meta.py schema

The subcommand lookup is optional — a bare identifier works. Identifier type (DOI / PMID / arXiv / OpenAlex id / title) is auto-detected.

Output format

Stdout is a stable JSON envelope when piped/captured, and a human key-value view on a TTY. Force it with --format json|human|auto (--json = --format json).

Envelope: { "ok": true, "data": {...}, "meta": { "schema_version", "cli_version", "sources", "latency_ms" } }. meta.sources records where each field came from (e.g. journal-abbrev (JabRef), journal-if (local cache), or a fallback), so you can tell curated data from approximations.

Data fields (data)

title, authors (list), author_count, first_author, corresponding_authors (list; empty if OpenAlex has no corresponding flag for the record), publication_date, year, journal, journal_abbrev, impact_factor, impact_factor_source, impact_factor_year, volume, issue, pages, doi, pmid, openalex, issn, type, is_oa, cited_by_count, abstract.

Exit codes

Code	Meaning
0	success
1	runtime / upstream error (retryable)
2	validation / bad input (missing file, empty query)
3	not found (no paper matched)

Workflow

1. Identify the input. A DOI (10.x/...), PMID (digits), arXiv id (NNNN.NNNNN), OpenAlex id (W...), or a title string — all auto-detected. Prefer a DOI or PMID: title search returns OpenAlex's single top match, which for very common titles can be a preprint or re-indexed copy rather than the version of record. Confirm the returned DOI/year if the user gave a title.
2. Run python3 journal_meta.py <id>.
3. Present the fields the user asked for. For a full citation, use first_author, journal_abbrev, year, volume, issue, pages, doi. State the impact_factor_source when reporting IF — a curated JCR number and an OpenAlex approximation are not the same thing.

Notes & caveats

• Corresponding author comes from OpenAlex's is_corresponding flag, which is only populated when the publisher supplied it. An empty list means "not marked in the metadata," not "there is none" — say so rather than guessing.
• Impact factor from journal-if is curated JCR; the fallback is OpenAlex's 2-year mean citedness, which differs from the official JCR IF. Cite formally only the curated value, and flag approximations.
• arXiv ids resolve via the arXiv DataCite DOI (10.48550/arXiv.<id>); if a preprint isn't indexed there, it falls back to a title search.

Environment variables

Variable	Effect
JOURNAL_META_MAILTO / OPENALEX_MAILTO	Email for OpenAlex's polite pool (faster, recommended).
JOURNAL_ABBREV_CLI	Explicit path to journal-abbrev's jabbrv.py (skips auto-discovery).
JOURNAL_IF_CLI	Explicit path to journal-if's journal_if.py.

If the sibling skills live in a non-standard location, set these so enrichment uses their curated data instead of the built-in fallbacks.

Troubleshooting

Issue	Solution
IF shows "OpenAlex ... (approx)" not JCR	journal-if not found — install it or set JOURNAL_IF_CLI.
Abbreviation looks wrong / same as full name	Single-word titles (Nature, Cell, Science) are not abbreviated per ISO 4. For others, journal-abbrev gives the ISO-4 form.
Title search returned the wrong paper	Use the DOI or PMID instead — title search takes OpenAlex's top hit only.
not_found on a brand-new DOI	OpenAlex indexing lags; the Crossref fallback covers most, but the newest DOIs may need a day.
corresponding_authors is empty	The publisher didn't mark it in the metadata; don't infer one.