Resolve DOIs and search scholarly metadata via the Crossref REST API. Use this skill whenever the user asks to look up a DOI, find citation metadata, search for journal articles or conference papers, retrieve author lists, citation counts, publication dates, or abstracts for academic works. Trigger for phrases like "look up this DOI", "find papers about lithium extraction", "who wrote this paper", "citation count for DOI", "search Crossref for produced water brine", "journal articles on DLE", "recent publications on magnesium recovery", "resolve DOI metadata", or any request involving scholarly publication lookup. Pairs with usgs-pubs and doe-osti skills to resolve DOIs returned by those sources. Covers 140M+ DOI-registered works across all disciplines. No API key required — uses the Crossref polite pool via mailto parameter for faster rate limits.
Resolves DOIs and searches scholarly publication metadata via the Crossref REST API (api.crossref.org). Covers 140M+ DOI-registered works including journal articles, conference proceedings, books, datasets, and reports.
No API key required. Add [email protected] to all requests
for access to the polite pool (faster rate limits, priority routing).
Resolution order for the mailto address:
~/.config/crossref/credentials — parse [email protected]CROSSREF_MAILTO env var — fallbackReading the credentials file (bash):
MAILTO=$(grep '^mailto=' ~/.config/crossref/credentials 2>/dev/null | cut -d= -f2)
[ -z "$MAILTO" ] && MAILTO="${CROSSREF_MAILTO}"
This is not a secret credential — it is a contact email sent in the clear so Crossref can reach you if your usage is problematic. Any valid email works.
Base URL: https://api.crossref.org/
| Endpoint | Description |
|---|---|
works/{doi} | Get metadata for a specific DOI |
works?query=... | Full-text search across all metadata fields |
works?query.bibliographic=... | Bibliographic-style search (title + author + year) |
works?query.title=... | Title-only search |
works?query.author=... | Author-only search |
types | List all work types (journal-article, proceedings-article, etc.) |
journals/{issn} | Journal metadata by ISSN |
journals/{issn}/works | Works published in a specific journal |
prefixes/{prefix} | Publisher info by DOI prefix |
members/{id} | Publisher/member metadata |
funders/{id} | Funder metadata |
funders/{id}/works | Works funded by a specific funder |
| Parameter | Example | Notes |
|---|---|---|
query | query=lithium+brine | Full-text search across all fields |
query.bibliographic | query.bibliographic=Smith+2023+lithium | Simulates bibliographic lookup |
query.title | query.title=direct+lithium+extraction | Title search only |
query.author | query.author=Stringfellow | Author name search |
filter | filter=from-pub-date:2023-01-01 | Comma-separated filter list |
select | select=DOI,title,author,type | Return only specified fields (reduces payload) |
rows | rows=20 | Results per page (default 20, max 1000) |
offset | offset=20 | Pagination offset (max 10000) |
cursor | cursor=* | Deep paging cursor (use for offset beyond 10000) |
sort | sort=relevance | Sort field |
order | order=desc | Sort direction |
mailto | [email protected] | Polite pool access (faster rate limits) |
Filters are passed as a comma-separated list in the filter parameter:
| Filter | Example | Description |
|---|---|---|
from-pub-date | from-pub-date:2023-01-01 | Published on or after date |
until-pub-date | until-pub-date:2024-12-31 | Published on or before date |
type | type:journal-article | Work type |
has-abstract | has-abstract:true | Only works with abstracts |
has-orcid | has-orcid:true | Authors with ORCID IDs |
has-references | has-references:true | Works with reference lists |
has-full-text | has-full-text:true | Works with full-text links |
is-update | is-update:false | Exclude corrections/errata |
funder | funder:10.13039/100000015 | DOE funder ID |
container-title | container-title:Water+Resources+Research | Journal name |
doi | doi:10.1021/acs.est.2c03513 | Exact DOI match |
issn | issn:0043-1397 | Filter by journal ISSN |
| Type | Description |
|---|---|
journal-article | Peer-reviewed journal article |
proceedings-article | Conference paper |
book-chapter | Chapter in an edited volume |
dataset | Data publication |
report | Technical report |
posted-content | Preprint |
monograph | Book/monograph |
| Sort | Description |
|---|---|
relevance | Default — Crossref relevance score |
published | Publication date |
indexed | Date indexed in Crossref |
is-referenced-by-count | Citation count (descending = most cited) |
references-count | Number of references in bibliography |
score | Internal relevance score |
Determine the operation type:
| User Intent | Endpoint | Key Parameters |
|---|---|---|
| "Look up DOI 10.xxxx/yyyy" | works/{doi} | Direct DOI lookup |
| "Find papers about X" | works?query=X | Keyword search |
| "Papers by Author on X" | works?query=X&query.author=Author | Combined search |
| "Recent journal articles on X" | works?query=X&filter=type:journal-article,from-pub-date:YYYY | Filtered search |
| "Most cited papers on X" | works?query=X&sort=is-referenced-by-count&order=desc | Sorted search |
| "Resolve DOI from USGS/OSTI" | works/{doi} | Cross-skill DOI resolution |
Single DOI lookup:
DOI="10.2118/1011-0046-jpt"
MAILTO="[email protected]"
curl -s "https://api.crossref.org/works/${DOI}?mailto=${MAILTO}"
Keyword search with filters:
curl -s "https://api.crossref.org/works?query=lithium+produced+water+brine\
&filter=from-pub-date:2020-01-01,has-abstract:true,type:journal-article\
&rows=20\
&select=DOI,title,author,type,published-print,container-title,is-referenced-by-count,abstract\
&sort=relevance\
&[email protected]"
Bibliographic search (best for matching a citation string):
curl -s "https://api.crossref.org/works?query.bibliographic=Stringfellow+2014+lithium+oilfield+brine\
&rows=5\
&select=DOI,title,author,published-print,container-title\
&[email protected]"
Single work response (works/{doi}):
{
"status": "ok",
"message-type": "work",
"message": {
"DOI": "10.2118/1011-0046-jpt",
"title": ["Brine Management: Produced Water and Frac Flowback Brine"],
"author": [{"given": "David", "family": "Burnett", "affiliation": [...]}],
"container-title": ["Journal of Petroleum Technology"],
"type": "journal-article",
"published-print": {"date-parts": [[2011, 10, 1]]},
"is-referenced-by-count": 1,
"abstract": "...",
"link": [{"URL": "...", "content-type": "...", "intended-application": "..."}]
}
}
Search response (works?query=...):
{
"status": "ok",
"message-type": "work-list",
"message": {
"total-results": 2171593,
"items-per-page": 20,
"query": {"start-index": 0, "search-terms": "lithium produced water brine"},
"items": [
{ "DOI": "...", "title": [...], "author": [...], ... }
],
"next-cursor": "AoJ/..."
}
}
Key fields to extract per work:
| Field | Type | Notes |
|---|---|---|
DOI | string | The DOI |
title | array of strings | Usually one element |
author | array of objects | Each has given, family, affiliation, optional ORCID |
container-title | array of strings | Journal or proceedings name |
type | string | journal-article, proceedings-article, etc. |
published-print | object | date-parts: [[year, month, day]] |
published-online | object | Same structure as published-print |
is-referenced-by-count | integer | Citation count (Crossref-tracked) |
abstract | string | May contain JATS XML markup |
link | array of objects | Full-text links with content-type |
reference | array of objects | Bibliography entries (if has-references) |
funder | array of objects | Funding sources with name, DOI, award |
subject | array of strings | Subject categories |
The date-parts field uses variable-length arrays:
[[2024, 3, 15]] = March 15, 2024[[2024, 3]] = March 2024[[2024]] = 2024Handle all three cases. Use the most specific date available.
Abstracts may contain JATS XML tags (<jats:p>, <jats:italic>, etc.).
Strip XML tags before display:
echo "$ABSTRACT" | sed 's/<[^>]*>//g'
Format: Metadata Table + Narrative
For a single DOI lookup:
## DOI: 10.2118/1011-0046-jpt
| Field | Value |
|-------|-------|
| Title | Brine Management: Produced Water and Frac Flowback Brine |
| Authors | David Burnett (Texas A&M University) |
| Journal | Journal of Petroleum Technology |
| Date | October 2011 |
| Type | journal-article |
| Citations | 1 |
| DOI Link | https://doi.org/10.2118/1011-0046-jpt |
**Abstract:** R&D Grand Challenges - This is the third in a series...
For a search:
## Crossref Search: "lithium produced water brine" (2020--present, journal articles)
Found 847 results. Showing top 10 by relevance:
| # | Year | Title | Journal | Citations | DOI |
|---|------|-------|---------|-----------|-----|
| 1 | 2023 | Direct Lithium Extraction from... | Minerals | 8 | 10.3390/... |
| 2 | 2024 | Effect of buffer on direct... | New J Chem | 3 | 10.1039/... |
| ... | ... | ... | ... | ... | ... |
**Summary:** Search returned 847 journal articles published since 2020
matching "lithium produced water brine". The most-cited result (8 citations)
covers DLE technology assessment for seawater brine. Results span journals
including Minerals, Water Research, and ACS ES&T...
Offset-based (for small result sets, offset max 10000):
&offset=0&rows=20 (page 1)
&offset=20&rows=20 (page 2)
Cursor-based (for deep paging beyond 10000):
&cursor=*&rows=100next-cursor in message&cursor=<next-cursor-value>&rows=100items is emptyWarn the user if total results exceed 1000 and suggest narrowing filters.
| HTTP Code | Meaning | Action |
|---|---|---|
| 200 | Success | Parse normally |
| 404 | DOI not found | Report DOI not in Crossref; suggest checking doi.org directly |
| 400 | Bad request | Check filter syntax, invalid field names |
| 429 | Rate limited | Wait and retry; suggest adding mailto for polite pool |
| 503 | Service unavailable | Retry after 5 seconds |
Common issues:
/ stays as-is in path)10.5066/...) may not be in Crossref — they use DataCite.
If a 10.5066 DOI returns 404, suggest querying https://api.datacite.org/dois/{doi} instead.This skill complements other PNGE data skills:
| Source Skill | How to Use Crossref |
|---|---|
usgs-produced-waters | Resolve the dataset DOI (10.5066/P9DSRCZJ) — note: USGS DOIs may be DataCite |
usgs-minerals | Look up publication DOIs from MCS data releases |
usgs-pubs | Resolve DOIs returned by USGS Publications Warehouse |
doe-osti | Resolve DOIs from OSTI technical report records |
netl-edx | Resolve DOIs linked in EDX dataset metadata |
Workflow for DOI resolution from other skills:
works/{doi} to get full citation metadata10.5066 or 10.2172, try DataCite insteadPre-built searches for common lithium/magnesium research topics:
Lithium from produced water:
curl -s "https://api.crossref.org/works?\
query=lithium+extraction+produced+water+oilfield+brine\
&filter=from-pub-date:2020-01-01,has-abstract:true,type:journal-article\
&rows=20&sort=is-referenced-by-count&order=desc\
&select=DOI,title,author,published-print,container-title,is-referenced-by-count\
&[email protected]"
Direct lithium extraction (DLE) technology:
curl -s "https://api.crossref.org/works?\
query=direct+lithium+extraction+DLE+brine\
&filter=from-pub-date:2020-01-01,type:journal-article\
&rows=20&sort=is-referenced-by-count&order=desc\
&select=DOI,title,author,published-print,container-title,is-referenced-by-count\
&[email protected]"
Magnesium recovery from brine:
curl -s "https://api.crossref.org/works?\
query=magnesium+recovery+brine+produced+water\
&filter=from-pub-date:2018-01-01,type:journal-article\
&rows=20&sort=is-referenced-by-count&order=desc\
&select=DOI,title,author,published-print,container-title,is-referenced-by-count\
&[email protected]"
Appalachian Basin produced water geochemistry:
curl -s "https://api.crossref.org/works?\
query=Appalachian+Marcellus+produced+water+geochemistry\
&filter=from-pub-date:2015-01-01,type:journal-article\
&rows=20&sort=is-referenced-by-count&order=desc\
&select=DOI,title,author,published-print,container-title,is-referenced-by-count\
&[email protected]"
is-referenced-by-count) are Crossref-tracked only. They
undercount compared to Google Scholar or Scopus because they only include
references deposited by publishers who participate in Crossref Cited-by.10.5066, 10.2172) are registered with
DataCite, not Crossref. A 404 for these prefixes is expected — use DataCite API.query.bibliographic
with specific author + year + title fragments rather than broad query.mailto in production use.bash_tool with curl + jq for API callsmailto parameter for polite pool accessselect to minimize payload size when you only need specific fieldsrows=20 for search results; increase to rows=100 if user needs more/ as-is in the pathreferences/api_reference.md for full endpoint documentationreferences/python_example.py for a stdlib-only Python client