XzhLoongSkills/skills/academic/paper-lookup/references/crossref.md

Crossref API

Crossref is the DOI registration agency for scholarly content. It provides metadata for 150M+ works including journal articles, books, conference papers, datasets, and preprints.

Base URL

https://api.crossref.org

Authentication

None required. Add mailto=you@example.com to get into the polite pool (2x faster rate limits).

Rate Limits

Pool	Rate	Concurrency
Public (no mailto)	5 req/sec	1 concurrent
Polite (with mailto)	10 req/sec	3 concurrent

HTTP 429 = temporarily blocked.

Key Endpoints

1. Search works

GET /works?query={text}&rows={n}&mailto=you@example.com

Parameter	Default	Description
query	--	Free-text search across all fields
query.author	--	Search author names
query.bibliographic	--	Search titles, authors, ISSNs, years
query.affiliation	--	Search affiliations
query.container-title	--	Search journal names
filter	--	Comma-separated name:value pairs
sort	score	score, published, issued, deposited, updated, is-referenced-by-count, references-count
order	desc	asc or desc
rows	20	Results per page (max 1000)
offset	0	Skip N results (max 10,000)
cursor	--	Use * for cursor-based deep pagination
select	--	Comma-separated field names to return
facet	--	Facet counts, e.g. type-name:10
sample	--	Return N random items (max 100)

Example:

https://api.crossref.org/works?query=CRISPR+gene+therapy&filter=from-pub-date:2024-01-01,type:journal-article,has-abstract:true&rows=5&sort=published&order=desc&mailto=you@example.com

2. Get work by DOI

GET /works/{doi}?mailto=you@example.com

URL-encode the DOI: 10.1038/nature12373 becomes 10.1038%2Fnature12373

Example:

https://api.crossref.org/works/10.1038%2Fnature12373?mailto=you@example.com

3. Journals

GET /journals?query={name}&rows={n}
GET /journals/{issn}
GET /journals/{issn}/works?query={text}&rows={n}

4. Funders

GET /funders?query={name}
GET /funders/{id}
GET /funders/{id}/works?rows={n}

Funder IDs are from the Funder Registry (e.g., 100000001 for NSF).

5. Members (publishers)

GET /members?query={name}
GET /members/{id}/works?rows={n}

Key Filters

Date filters (accept YYYY, YYYY-MM, YYYY-MM-DD)

Filter	Description
from-pub-date / until-pub-date	Publication date
from-print-pub-date / until-print-pub-date	Print publication date
from-online-pub-date / until-online-pub-date	Online publication date
from-posted-date / until-posted-date	Posted date (preprints)

Boolean filters

Filter	Description
has-abstract	Has an abstract
has-orcid	Has ORCID IDs
has-funder	Has funder info
has-full-text	Has full-text links
has-references	Has reference list
has-license	Has license info

Value filters

Filter	Description
type	journal-article, posted-content, book-chapter, proceedings-article, etc.
issn	Journal ISSN
doi	Specific DOI
orcid	Contributor ORCID
funder	Funder Registry ID
member	Crossref member ID
prefix	DOI prefix
license.url	License URL
update-type	correction, retraction

Syntax: filter=name1:value1,name2:value2

Pagination

Offset-based (max 10,000)

/works?query=cancer&rows=100&offset=200

Cursor-based (unlimited)

1. First request: ?cursor=*&rows=100
2. Response includes next-cursor
3. Next request: ?cursor={next-cursor-value}&rows=100
4. Cursors expire after 5 minutes

Response Format

List response

{
  "status": "ok",
  "message-type": "work-list",
  "message": {
    "total-results": 2779116,
    "items-per-page": 20,
    "next-cursor": "...",
    "items": [...]
  }
}

Work object (key fields)

{
  "DOI": "10.1038/nature12373",
  "title": ["Nanometre-scale thermometry in a living cell"],
  "author": [{"given": "G.", "family": "Kucsko", "sequence": "first"}],
  "publisher": "Springer Science and Business Media LLC",
  "type": "journal-article",
  "published": {"date-parts": [[2013, 7, 31]]},
  "container-title": ["Nature"],
  "ISSN": ["0028-0836", "1476-4687"],
  "volume": "500",
  "issue": "7460",
  "page": "54-58",
  "is-referenced-by-count": 1745,
  "references-count": 30,
  "abstract": "<p>Abstract text with HTML tags...</p>",
  "license": [{"URL": "...", "content-version": "vor"}],
  "link": [{"URL": "...", "content-type": "application/pdf"}],
  "reference": [{"key": "...", "doi-asserted-by": "crossref", "DOI": "..."}],
  "subject": ["Multidisciplinary"],
  "language": "en"
}

Note: title and container-title are arrays. published.date-parts is [[year, month, day]]. Abstract may contain HTML tags.