Crate crossref

This crate provides a client for interacting with the crossref-api

Crossref API docs Crossref - Crossref search API. The Crossref crate provides methods matching Crossref API routes:

• works - /works route
• members - /members route
• prefixes - /prefixes route
• funders - /funders route
• journals - /journals route
• types - /types route
• agency - /works/{doi}/agency get DOI minting agency

Usage

Create a Crossref client:

let client = Crossref::builder().build()?;

If you have an Authorization token for Crossref's Plus service:

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

Encouraged to use the The Polite Pool:

Good manners = more reliable service

To get into Crossref's polite pool include a email address

let client = Crossref::builder()
    .polite("polite@example.com")
    .token("your token")
    .build()?;

Constructing Queries

Not all components support queries and there are custom available parameters for each route that supports querying. For each resource components that supports querying there exist a Query struct: WorksQuery, MembersQuery, FundersQuery. The WorksQuery also differs from the others by supporting deep paging with cursors and field queries.

Otherwise creating queries works the same for all resource components:

let query = WorksQuery::new("Machine Learning")
// field queries supported for `Works`
.field_query(FieldQuery::author("Some Author"))
// filters are specific for each resource component
.filter(WorksFilter::HasOrcid)
.order(Order::Asc)
.sort(Sort::Score);

Get Records

See this table for a detailed overview of the major components.

There are 3 available targets:

• standalone resource components: /works, /members, etc. that return a list list of the corresponding items and can be specified with queries
• Resource component with identifiers: /works/{doi}?<query>,/members/{member_id}?<query>, etc. that returns a single item if found.
• combined with the works route: The works component can be appended to other resources: /members/{member_id}/works?<query> etc. that returns a list of matching Work items.

This resembles in the enums of the resource components, eg. for Members:

pub enum Members {
    /// target a specific member at `/members/{id}`
    Identifier(String),
    /// target all members that match the query at `/members?query...`
    Query(MembersQuery),
    /// target a `Work` for a specific member at `/members/{id}/works?query..`
    Works(WorksIdentQuery),
}

All options are supported by the client:

Single Item by DOI (ID)

Analogous methods exist for all resource components

let work = client.work("10.1037/0003-066X.59.1.29")?;

let agency = client.work_agency("10.1037/0003-066X.59.1.29")?;

let funder = client.funder("funder_id")?;

let member = client.member("member_id")?;

Query

let query = WorksQuery::new("Machine Learning");

// one page of the matching results
let works = client.works(query)?;

Alternatively insert a free form query term directly

// one page of the matching results
let works = client.works("Machine Learning")?;

Combining Routes with the Works route

For each resource component other than Works there exist methods to append a WorksQuery with the ID option /members/{member_id}/works?<query>?

let works = client.member_works( WorksQuery::new("machine learning")
.sort(Sort::Score).into_ident("member_id"))?;

This would be the same as using the Crossref::works method by supplying the combined type

let works = client.works(WorksQuery::new("machine learning")
    .sort(Sort::Score)
    .into_combined_query::<Members>("member_id"))?;

** Deep paging for Works ** Deep paging results Deep paging is supported for all queries, that return a list of Work, WorkList. This function returns a new iterator over pages of Work, which is returned as bulk of items as a WorkList by crossref. Usually a single page WorkList contains 20 items.

Example

Iterate over all Works linked to search term Machine Learning

use crossref::{Crossref, WorksQuery, Work};
let client = Crossref::builder().build()?;

let all_works: Vec<Work> = client.deep_page(WorksQuery::new("Machine Learning")).flat_map(|x|x.items).collect();

Which can be simplified to

use crossref::{Crossref, WorksQuery, Work};
let client = Crossref::builder().build()?;

let all_works: Vec<Work> = client.deep_page("Machine Learning").into_work_iter().collect();

Example

Iterate over all the pages (WorkList) of the funder with id funder id by using a combined query. A single WorkList usually holds 20 Work items.

use crossref::{Crossref, Funders, WorksQuery, Work, WorkList};
let client = Crossref::builder().build()?;

let all_funder_work_list: Vec<WorkList> = client.deep_page(WorksQuery::default().into_combined_query::<Funders>("funder id")).collect();

Example

Iterate over all Work items of a specfic funder directly.

use crossref::{Crossref, Funders, WorksQuery, Work, WorkList};
let client = Crossref::builder().build()?;

let all_works: Vec<Work> = client.deep_page(WorksQuery::default()
        .into_combined_query::<Funders>("funder id"))
        .into_work_iter()
        .collect();

Re-exports

pub use self::query::Funders;

pub use self::query::Journals;

pub use self::query::Members;

pub use self::query::Prefixes;

pub use self::query::Type;

pub use self::query::Types;

pub use self::response::CrossrefType;

pub use self::response::Funder;

pub use self::response::FunderList;

pub use self::response::Journal;

pub use self::response::JournalList;

pub use self::response::Member;

pub use self::response::MemberList;

pub use self::response::TypeList;

pub use self::response::Work;

pub use self::response::WorkAgency;

pub use self::response::WorkList;

Modules

cn	content negotiation
query	provides types to construct a specific query
response	provides the response types of the crossref api
tdm	textual data mining

Structs

Crossref	Struct for Crossref search API methods
CrossrefBuilder	A CrossrefBuilder can be used to create Crossref with additional config.
Error	An error that can occur while interacting with a crossref index.
FieldQuery	Field queries are available on the /works route and allow for queries that match only particular fields of metadata.
WorkListIterator	Allows iterating of deep page work request
WorksIdentQuery	Target Works as secondary resource component
WorksQuery	Used to construct a query that targets crossref Works elements

Enums

Component	Major resource components supported by the Crossref API
Order	Determines how results should be sorted
Sort	Results from a list response can be sorted by applying the sort and order parameters.
WorkListQuery	Wraps queries that target WorkList, either directly or combined
WorkResultControl	limits from where and how many Work items should be returned
Works	Retrieve a publication by DOI
WorksFilter	Filters allow you to narrow queries. All filter results are lists

Traits

CrossrefQuery	root level trait to construct full crossref api request urls
CrossrefRoute	represents elements that constructs parts of the crossref request url

Type Definitions

Result

A type alias for handling errors throughout crossref.