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 [email protected] to get into the polite pool (higher list and single-record limits).
Rate Limits
| Pool | Single record | List/search | Concurrency | |------|---------------|-------------|-------------| | Public (no mailto) | 5 req/sec | 1 req/sec | 1 | | Polite (with mailto) | 10 req/sec | 3 req/sec | 3 |
These limits took effect 2025-12-01. Inspect rate-limit headers and honor Retry-After; HTTP 429 is a throttle, not an empty search.
Key Endpoints
1. Search works
GET /works?query={text}&rows={n}&[email protected]
| 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&[email protected]
2. Get work by DOI
GET /works/{doi}[email protected]
URL-encode the DOI: 10.1038/nature12373 becomes 10.1038%2Fnature12373
Example:
https://api.crossref.org/works/10.1038%[email protected]
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)
- First request:
?cursor=*&rows=100 - Response includes
next-cursor - Next request:
?cursor={next-cursor-value}&rows=100 - Stop when
message.itemsis shorter than requestedrows(or empty). A cursor can remain present on the last page; its presence alone does not mean more records. - 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.
Official sources reviewed 2026-09-30
- https://www.crossref.org/documentation/retrieve-metadata/rest-api/
- https://github.com/CrossRef/rest-api-doc
- https://www.crossref.org/blog/announcing-changes-to-rest-api-rate-limits/