Crossref Works & DOI Metadata

Crossref works scraper returns publication and DOI metadata from Crossref. Crossref API searches can also return journal and funder records with source links.

Build status: Unpublished draft. Python tests, the local actor run and the required CLI schema command are blocked by this session's process-access error. Read REPORT.md before publishing.

What it returns

The default dataset uses one row per successful metadata record or input/source error. recordType distinguishes works, journals and funders. Missing counts remain null.

Field	Type	Example value
recordType	string	"work"
status	string	"ok"
doi	string	"10.1038/nphys1170"
title	string	"Measured measurement"
url	nullable / see code	null
sourceUrl	nullable / see code	null
fetchedAt	nullable / see code	null
errors	nullable / see code	null
workType	nullable / see code	null
publisher	nullable / see code	null
containerTitle	nullable / see code	null
publishedDate	nullable / see code	null
citationCount	integer	11
referenceCount	integer	10
issn	nullable / see code	null
isbn	nullable / see code	null
language	nullable / see code	null
authors	nullable / see code	null
licenses	nullable / see code	null
funders	nullable / see code	null
abstract	nullable / see code	null
references	nullable / see code	null
totalDois	nullable / see code	null
currentDois	nullable / see code	null
backfileDois	nullable / see code	null
subjects	nullable / see code	null
funderId	nullable / see code	null
location	nullable / see code	null
alternateNames	nullable / see code	null
input	nullable / see code	null
httpStatus	nullable / see code	null

Licence metadata can describe text/data mining rights. A listed licence URL does not itself establish that an article is open access.

Input example

{
  "mode": "doi",
  "dois": [
    "10.1038/nphys1170"
  ],
  "maxItems": 1
}

Use the input schema for the remaining filters and defaults.

Output example and provenance

An actual actor-output sample is pending the local run. tests/fixtures/work.json is a saved real Crossref response, with this exact excerpt from its message:

{
  "DOI": "10.1038/nphys1170",
  "title": ["Measured measurement"],
  "is-referenced-by-count": 11,
  "reference-count": 10
}

The mapping uses doi, title, citationCount and referenceCount for these fields. The local acceptance script writes sample_output.json from the actual default dataset after it can run.

Proposed pricing

Custom work event: $0.0005 per successful metadata row, or $0.50 per 1,000. The same event covers successful work/DOI, journal and funder results. Error rows are uncharged. Duplicate DOI inputs are removed before retrieval. No actor-start event or reference/licence surcharge is proposed.

The most-used Crossref comparator in the returned API cohort by observed total users charged $0.002 per paper on the 2026-10-05 Store API observation. See PRICING.md and its timestamped receipt. The owner must configure monetization before publishing. Platform resource costs depend on Console settings.

Limits

• maxItems defaults to 100 and accepts 1–10,000. The cap includes error rows and applies to rows emitted by this invocation.
• concurrency controls 1–3 DOI tasks. HTTP requests remain serial in both pools; rate-limit headers can increase pacing.
• pageSize accepts 1–1,000. Works use cursor pagination; journals and funders use offsets.
• maxRetries accepts 0–5; its default is 3. Timeouts, 429 and selected 5xx responses use backoff. Retry-After waits longer than 120 seconds produce an error row.
• Crossref search can change during pagination. Source failures leave explicit partial-result errors when there is room within maxItems.
• Only Crossref-registered DOI metadata is supported. DOI resolution does not fetch full text or other registration agencies.
• Counts, references, abstracts and licences reflect publisher deposits; completeness varies.
• Dataset writes and manual event charges are separate operations. A storage failure or interrupted run can leave a charge without a saved row. Automatic migration/restart deduplication is not implemented.
• The source is the public official API, without login or paid Crossref Plus access.

FAQ

What limits the output? The maxItems input caps output rows; its schema maximum is 10,000. Source availability and errors may yield fewer rows.

Does it need a proxy, login, or API key? The actor calls public Crossref endpoints without an API key. The optional mailto input identifies the client.

How is it priced? PRICING.md proposes $0.0005 per successful metadata row and no custom charge for error rows. The proposal is not published.

What happens on rate limits? The client learns Crossref rate-limit headers and waits between requests; it retries throttling and transient failures.

How fresh is the data? Metadata reflects Crossref at retrieval; fetchedAt is retrieval time, while publication dates come from deposited metadata.

Does a licence field grant reuse rights? Read the deposited licence URL and its terms; the actor only supplies metadata.

Use with AI agents / MCP

An AI agent can call a published actor through the Apify MCP server or Apify API, pass the JSON input, then read the run’s default dataset. Check the actor’s published identifier and permissions in your Apify account.

After publication, an AI agent can invoke the actor through Apify's API or Apify MCP server. Give the agent an operation, a query or DOI list, maxItems and a run budget. Retain sourceUrl and fetchedAt in any cited answer. A compact request is {"mode":"doi","dois":["10.1038/nphys1170"],"maxItems":1}. MCP connects an agent to external tools; here it would call this actor. The package does not include a separate MCP server.

Local development and verification

Use the existing project Python. Runtime dependencies are Apify and httpx, already present in the designated environment. These required acceptance commands have not yet run successfully in this session:

& C:/GritWork/earn/.venv/Scripts/python.exe -m pytest tests -m "not live" -q
& C:/GritWork/earn/.venv/Scripts/python.exe -m pytest tests -m live -q
apify validate-schema
& C:/GritWork/earn/.venv/Scripts/python.exe tests/verify_behavior.py

For a manual local run, storage/key_value_stores/default/INPUT.json already contains the sample input:

$env:APIFY_LOCAL_STORAGE_DIR = "$PWD/storage"
$env:ACTOR_TEST_PAY_PER_EVENT = "true"
& C:/GritWork/earn/.venv/Scripts/python.exe -m src

The behavior verifier varies inputs, inspects saved results and simulated charges, and writes real sample_output.json plus evidence/behavior-proof.json. Its local simulated prices do not represent actual Store charges.