opencitations-client - An async Rust client for the OpenCitations REST APIs
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.
citationsfor the works citing something,referencesfor 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 ;
let client = builder.build?;
let paper = doi;
for citation in client.citations.await?
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.await?;
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 ;
let recent = new
.filter
.filter
.sort;
let citations = client.citations_where.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.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 = builder.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 Index api and the Meta api — the routes and their parameters, as the apis report them today.
- OpenCitations' documentation — what the index is built from and what it does and does not cover.
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
200and 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 Policycounts0under its print ISSN0308-597Xand86 206under its electronic1872-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:
- Apache License, Version 2.0, (LICENSE-APACHE or https://www.apache.org/licenses/LICENSE-2.0)
- MIT license (LICENSE-MIT or https://opensource.org/licenses/MIT)