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:
- the Index — the citation
edges.
OpenCitations::citationsfor the works citing something,OpenCitations::referencesfor the works it cites, and the counts of both. - Meta — the bibliographic
record behind an identifier, via
OpenCitations::metadata.
§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.
- Date
Parse Error - 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. - Open
Citations - An async client for the OpenCitations Index and Meta apis.
- Open
Citations Builder - Builds an
OpenCitationsclient. - Partial
Date - A publication date, to whatever precision it was recorded at.
- Rate
Limit - 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.
- Timespan
Parse Error - Why a string is not a
Timespan.
Enums§
- Comparison
- How a
Filtercompares 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:valueform OpenCitations writes. - Order
- Which way a
Sortruns.
Type Aliases§
- Result
- A type alias for handling errors throughout this crate.