pub struct OpenCitations { /* private fields */ }Expand description
An async client for the OpenCitations Index and Meta apis.
Cloning is cheap and shares the connection pool and the rate limiter, so concurrent callers should clone one client rather than build several.
Implementations§
Source§impl OpenCitations
impl OpenCitations
Sourcepub const META_BATCH: usize = 10
pub const META_BATCH: usize = 10
How many identifiers Self::metadata puts in one request.
Meta answers a 500 at fifteen identifiers and succeeds at fourteen,
whichever ids they are — a cap it does not document and does not
mention in the error. Ten leaves room for that edge to move without
this crate finding out from a user.
Sourcepub fn builder() -> OpenCitationsBuilder
pub fn builder() -> OpenCitationsBuilder
Constructs a new OpenCitationsBuilder.
Sourcepub fn base_url(&self) -> &str
pub fn base_url(&self) -> &str
The url every route is appended to, https://api.opencitations.net
unless OpenCitationsBuilder::base_url said otherwise.
Sourcepub fn rate_limit(&self) -> RateLimit
pub fn rate_limit(&self) -> RateLimit
The rate this client is pacing itself at.
OpenCitations reports no budget of its own, so this is whatever the builder was given and never changes.
Sourcepub async fn citations(&self, id: &Identifier) -> Result<Vec<Citation>>
pub async fn citations(&self, id: &Identifier) -> Result<Vec<Citation>>
The works that cite id — the direction crossref cannot answer.
Empty when nothing cites it and when OpenCitations has never indexed
it; the two are not distinguishable. Unpaged, so a heavily cited work
arrives in one large response — narrow it with
OpenCitations::citations_where rather than here.
Sourcepub async fn citations_where(
&self,
id: &Identifier,
refine: &Refine,
) -> Result<Vec<Citation>>
pub async fn citations_where( &self, id: &Identifier, refine: &Refine, ) -> Result<Vec<Citation>>
The works that cite id, narrowed and ordered by the api.
use opencitations_client::{Field, Filter, Identifier, OpenCitations, Refine, Sort};
let recent = Refine::new()
.filter(Filter::greater_than(Field::Creation, "2023"))
.sort(Sort::descending(Field::Creation));
let citations = client
.citations_where(&Identifier::doi("10.1016/j.marpol.2021.104855"), &recent)
.await?;Sourcepub async fn references(&self, id: &Identifier) -> Result<Vec<Citation>>
pub async fn references(&self, id: &Identifier) -> Result<Vec<Citation>>
The works id cites, as OpenCitations indexed them.
This is the same direction as crossref’s reference[] and a useful
cross-check on it: OpenCitations resolves references to identifiers,
where a crossref reference may be an unstructured string.
Sourcepub async fn references_where(
&self,
id: &Identifier,
refine: &Refine,
) -> Result<Vec<Citation>>
pub async fn references_where( &self, id: &Identifier, refine: &Refine, ) -> Result<Vec<Citation>>
The works id cites, narrowed and ordered by the api.
Sourcepub async fn citation(&self, oci: &Oci) -> Result<Option<Citation>>
pub async fn citation(&self, oci: &Oci) -> Result<Option<Citation>>
One citation, by its own identifier.
None when OpenCitations holds no such citation.
Sourcepub async fn citation_count(&self, id: &Identifier) -> Result<u64>
pub async fn citation_count(&self, id: &Identifier) -> Result<u64>
How many works cite id.
Cheaper than counting OpenCitations::citations, which fetches every
edge to do it.
Sourcepub async fn reference_count(&self, id: &Identifier) -> Result<u64>
pub async fn reference_count(&self, id: &Identifier) -> Result<u64>
How many works id cites.
Sourcepub async fn venue_citation_count(&self, issn: &Identifier) -> Result<u64>
pub async fn venue_citation_count(&self, issn: &Identifier) -> Result<u64>
How many citations everything published in a venue has received.
Addressed by ISSN — Identifier::issn("0308-597X").
Sourcepub async fn metadata(&self, ids: &[Identifier]) -> Result<Vec<Metadata>>
pub async fn metadata(&self, ids: &[Identifier]) -> Result<Vec<Metadata>>
The bibliographic records behind any number of identifiers.
Ids are batched rather than asked about one at a time, which is worth
doing: a batch is one slot of the rate limit rather than one each. More
than Self::META_BATCH of them is split across several requests,
paced like any other.
Records come back in whatever order Meta answers in, and an id it holds
nothing about is simply absent — so match the results up by
Metadata::id rather than by position. An empty slice makes no
request.
let records = client
.metadata(&[
Identifier::doi("10.1016/j.marpol.2021.104855"),
Identifier::doi("10.1038/nature12373"),
])
.await?;