Skip to main content

Crate opencitations_client

Crate opencitations_client 

Source
Expand description

An async client for the OpenCitations REST apis.

OpenCitations answers the question crossref’s public api cannot: which works cite this one. Crossref holds the reference list a publisher deposited – what a work points at – and exposes the number of incoming citations but never the list. OpenCitations inverts those deposited references into a citation index and serves both directions openly, with no account and no credentials.

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

§Everything is addressed by a prefixed identifier

A bare DOI means nothing to OpenCitations; doi: in front of it does. See Identifier, which parses the scheme:value 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);
}

§Nothing found is not an error

Both apis answer an identifier they hold nothing about with 200 and an empty list, so a work nobody has cited, a work OpenCitations has never indexed, and a typo in a DOI are indistinguishable from one another. An empty Vec is the answer to all three; only a malformed identifier fails, as Error::NoSuchOperation.

§Rate

OpenCitations documents 180 requests a minute per address and 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 rather than building several, or they will not queue against one another. An access token from opencitations.net/accesstoken is optional and raises the limit — see OpenCitationsBuilder::token.

Structs§

Citation
One citation: an edge from a citing work to a cited one.
DateParseError
Why a string is not a PartialDate.
Entity
Something Meta names and identifies: an author, an editor, a publisher or a venue.
Filter
A narrowing applied by the api rather than by the caller.
Metadata
A bibliographic record, as OpenCitations Meta holds it.
Oci
An Open Citation Identifier: the citing and cited work’s OMIDs, joined by a -, naming one citation.
OpenCitations
An async client for the OpenCitations Index and Meta apis.
OpenCitationsBuilder
Builds an OpenCitations client.
PartialDate
A publication date, to whatever precision it was recorded at.
RateLimit
How many requests may be sent in a window.
Refine
What to ask of a citation listing beyond the identifier itself.
Sort
The order the api returns a listing in.
Timespan
How long after the cited work the citing work was published, as OpenCitations measures it.
TimespanParseError
Why a string is not a Timespan.

Enums§

Comparison
How a Filter compares a field against its value.
Error
Everything that can go wrong talking to OpenCitations.
Field
A field of a Citation, as the api names it.
Identifier
One identifier of a bibliographic entity, in the scheme:value form OpenCitations writes.
Order
Which way a Sort runs.

Type Aliases§

Result
A type alias for handling errors throughout this crate.