opencitations-client 0.1.0

An async Rust client for the OpenCitations Index and Meta REST APIs
Documentation

opencitations-client - An async Rust client for the OpenCitations REST APIs

Crates.io Documentation

OpenCitations Index API · OpenCitations Meta API

The direction crossref cannot answer. Crossref holds the reference list a publisher deposited — what a work points at — and reports the number of incoming citations, but never the list of them. OpenCitations inverts those same open references into a citation index and serves both directions to anybody, with no account and no credentials.

Crossref does run a forward-citation service of its own, Cited-by, but it lives on a different host, answers XML, and needs Crossref member credentials — a publisher's depositing account. This crate is the open route to the same question.

Two apis sit behind one client, because a citation is only useful alongside what it connects:

  • the Index — the citation edges. citations for the works citing something, references for the works it cites, and the counts of both.
  • Meta — the bibliographic record behind an identifier, via metadata.

Install

As a library

cargo add opencitations-client

As a command line tool

Every release carries a prebuilt opencitations binary, so this needs no rust toolchain. Each archive holds the binary and the two licences, and is named after the platform alone, so these commands always fetch the newest release.

Linux and macOS

# x86_64-unknown-linux-gnu | aarch64-apple-darwin (apple silicon) | x86_64-apple-darwin (intel)
target=x86_64-unknown-linux-gnu

curl -fsSL "https://github.com/EmilLindfors/opencitations-client/releases/latest/download/opencitations-$target.tar.gz" | tar xz
sudo install "opencitations-$target/opencitations" /usr/local/bin/

Windows (PowerShell)

$target = "x86_64-pc-windows-msvc"

Invoke-WebRequest "https://github.com/EmilLindfors/opencitations-client/releases/latest/download/opencitations-$target.zip" -OutFile opencitations.zip
Expand-Archive opencitations.zip -DestinationPath .
# then move opencitations-$target\opencitations.exe somewhere on your PATH

From source, which needs rust 1.85 or newer:

cargo install opencitations-client --features cli

Either way, opencitations --version says which release you ended up with.

Usage

Everything is addressed by a prefixed identifier: a bare 10.1016/… means nothing to OpenCitations, doi:10.1016/… does. Identifier parses that form and refuses a bare one rather than guessing — a guess that picks the wrong scheme comes back as an empty list, which reads exactly like a work nobody has cited.

use opencitations_client::{Identifier, OpenCitations};

let client = OpenCitations::builder().build()?;
let paper = Identifier::doi("10.1016/j.marpol.2021.104855");

for citation in client.citations(&paper).await? {
    println!("{:?} cited it in {:?}", citation.citing_doi(), citation.creation);
}

Everything arrives as a string; nothing stays one

The api's json is stringly typed throughout — "count": "35", "journal_sc": "no", "creation": "2024-04", "timespan": "P2Y3M", and both ends of an edge as a space-separated bag of identifiers. This crate reads all of that once, at the boundary:

let citation = &client.citations(&paper).await?[0];

citation.citing_doi();                      // Option<&str>
citation.creation.unwrap().year();          // i32, from a PartialDate
citation.timespan.unwrap().as_months();     // i64, negative if the citing work came first
citation.author_self_citation;              // bool

PartialDate keeps the precision it was given (2022, 2022-01, 2022-01-15) rather than inventing a first-of-the-month, and Timespan is an ISO-8601 duration because you cannot subtract 2024 from 2024-04 and get a number of days.

Narrow at the api, not here

A listing is unpaged: a well cited work arrives in one large response. Refine renders the api's own filter and sort, so the narrowing happens there.

use opencitations_client::{Field, Filter, Refine, Sort};

let recent = Refine::new()
    .filter(Filter::greater_than(Field::Creation, "2023"))
    .filter(Filter::is(Field::AuthorSelfCitation, "no"))
    .sort(Sort::descending(Field::Creation));

let citations = client.citations_where(&paper, &recent).await?;

Batch the metadata

Several identifiers go in one request, which costs one slot of the rate limit rather than one each. Records come back in no promised order and an id Meta holds nothing about is simply absent, so match them up by Metadata::id:

let records = client.metadata(&[
    Identifier::doi("10.1016/j.marpol.2021.104855"),
    Identifier::doi("10.1038/nature12373"),
]).await?;

Rate

OpenCitations documents 180 requests a minute per ip address and — unlike crossref — reports nothing about the budget on a response. So the client paces itself blindly at that rate and retries a 429. Cloning is cheap and shares the limiter; build one client and clone it, or separate clients will not queue against one another.

An access token is optional, free, and raises the limit:

let client = OpenCitations::builder().token("your token").build()?;

Command Line Application

Usage: opencitations <COMMAND>

Commands:
  citations   The works that cite this one -- the direction crossref cannot answer
  references  The works this one cites
  count       How many works cite this one, without fetching them
  meta        The bibliographic record behind an identifier, from OpenCitations Meta
  citation    One citation, by its own identifier

Options:
      --token <TOKEN>            An access token [env: OPENCITATIONS_TOKEN=]
      --user-agent <USER_AGENT>  The user agent to identify this caller by
      --rate <PER_MINUTE>        Send at most this many requests a minute
  -o, --output <OUTPUT>          output path where the results shall be stored
  -a, --append                   append instead of overwriting the file

Who cites this paper, and how many:

opencitations count doi:10.1016/j.marpol.2021.104855
opencitations citations doi:10.1016/j.marpol.2021.104855 --format text
2024-04  10.1016/j.foodqual.2023.105064
2025-07  10.1016/j.jfutfo.2025.03.003
2025-04-08  10.1007/s11626-025-01040-3  [author self-citation]
-- 35 citations

Narrow it, and hand the answer to something else. --format dois prints bare DOIs, one per line, which is what the next tool wants:

opencitations citations doi:10.1016/j.marpol.2021.104855 \
  --since 2024 --no-author-self-citations --format dois

Which pairs with crossref to turn the citing DOIs into full records — the loop neither tool closes alone:

opencitations citations doi:10.1016/j.marpol.2021.104855 --since 2024 -f dois \
  | while read doi; do crossref works --polite you@example.com --id "$doi"; done

The bibliographic record, without crossref:

opencitations meta doi:10.1016/j.marpol.2021.104855 -f text

Where the apis' own behaviour is written down

The live suite (cargo test --test integration -- --ignored --test-threads 1) asks the apis the same questions and is the fastest way to tell a change on OpenCitations' side from a change on this one.

Things that will catch you out

  • Nothing found is not an error. Both apis answer an identifier they hold nothing about with 200 and an empty list. A work nobody has cited, a work never indexed, and a typo in a DOI are indistinguishable.
  • A venue is indexed under one of its ISSNs, not both. Marine Policy counts 0 under its print ISSN 0308-597X and 86 206 under its electronic 1872-9460. A zero means try the other one.
  • Coverage is publisher-dependent. The index is built from the references publishers chose to open. Elsevier opened theirs late and many older works never had references deposited at all, so absence is weak evidence.
  • A timespan can be negative, when the citing work was published before the work it cites — a preprint cited before its version of record appeared.

License

Licensed under either of these: