Crossref DOI Skill

API Structure

Base URL: https://api.crossref.org/

Core Endpoints

Query Parameters

Filter Parameters

Filters are passed as a comma-separated list in the filter parameter:

Common Work Types

Sort Fields

Workflow

Step 1 -- Resolve Intent

Determine the operation type:

Step 2 -- Build and Execute Request

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]"

Step 3 -- Parse Response

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:

Step 4 -- Format Dates

The date-parts field uses variable-length arrays:

• [[2024, 3, 15]] = March 15, 2024
• [[2024, 3]] = March 2024
• [[2024]] = 2024

Handle all three cases. Use the most specific date available.

Step 5 -- Clean Abstract Text

Abstracts may contain JATS XML tags (<jats:p>, <jats:italic>, etc.). Strip XML tags before display:

echo "$ABSTRACT" | sed 's/<[^>]*>//g'

Step 6 -- Produce Output

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

Pagination

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):

1. First request: &cursor=*&rows=100
2. Response includes next-cursor in message
3. Subsequent request: &cursor=<next-cursor-value>&rows=100
4. Continue until items is empty

Warn the user if total results exceed 1000 and suggest narrowing filters.

Error Handling

Common issues:

• DOI contains special characters: URL-encode the DOI (/ stays as-is in path)
• USGS data DOIs (e.g., 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.
• Abstract contains XML: strip JATS tags before display

Cross-Skill Integration

This skill complements other PNGE data skills:

Workflow for DOI resolution from other skills:

1. Extract DOI from the source API response
2. Call works/{doi} to get full citation metadata
3. If 404 and DOI prefix is 10.5066 or 10.2172, try DataCite instead
4. Present unified citation with DOI link

PNGE Research Queries

Pre-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]"

Caveats and Limitations

• Citation counts (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.
• Coverage gaps: Not all publishers deposit abstracts or references. Some older works have minimal metadata. Conference papers vary widely in coverage.
• USGS/DOE data DOIs (prefixes 10.5066, 10.2172) are registered with DataCite, not Crossref. A 404 for these prefixes is expected — use DataCite API.
• Relevance ranking is opaque. For precise results, use query.bibliographic with specific author + year + title fragments rather than broad query.
• Rate limits: Public pool = ~50 req/sec shared. Polite pool (with mailto) = significantly faster. Always include mailto in production use.
• Abstract XML: Raw abstracts contain JATS markup. Always strip tags.

Implementation Notes

• Use bash_tool with curl + jq for API calls
• Always include mailto parameter for polite pool access
• Use select to minimize payload size when you only need specific fields
• Default to rows=20 for search results; increase to rows=100 if user needs more
• For DOI lookups, URL-encode the DOI but keep / as-is in the path
• See references/api_reference.md for full endpoint documentation
• See references/python_example.py for a stdlib-only Python client