Module: Serrano

Extended by:

Configuration

Defined in:

lib/serrano.rb,
lib/serrano/cn.rb,
lib/serrano/error.rb,
lib/serrano/filters.rb,
lib/serrano/request.rb,
lib/serrano/version.rb,
lib/serrano/cnrequest.rb,
lib/serrano/filterhandler.rb,
lib/serrano/request_cursor.rb

Overview

Serrano::RequestCursor

Class to perform HTTP requests to the Crossref API

Defined Under Namespace

Modules: Filters Classes: BadGateway, BadRequest, CNRequest, ContentNegotiation, Error, GatewayTimeout, InternalServerError, NotFound, Request, RequestCursor, ServiceUnavailable

Constant Summary

VERSION =

"1.6"

Class Method Summary

• .assert_valid_filters(filters) ⇒ Object
• .citation_count(doi:, url: "https://www.crossref.org/openurl/", key: "cboettig@ropensci.org", options: nil) ⇒ Object

  Get a citation count with a DOI.

• .content_negotiation(ids:, format: "bibtex", style: "apa", locale: "en-US") ⇒ Hash

  Get citations in various formats from CrossRef.

• .csl_styles ⇒ Object

  Get csl styles.

• .filters ⇒ Object
• .funders(ids: nil, query: nil, filter: nil, offset: nil, limit: nil, sample: nil, sort: nil, order: nil, facet: nil, select: nil, works: false, options: nil, verbose: false, cursor: nil, cursor_max: 5000, **args) ⇒ Array

  Search the funders route.

• .journals(ids: nil, query: nil, filter: nil, offset: nil, limit: nil, sample: nil, sort: nil, order: nil, facet: nil, select: nil, works: false, options: nil, verbose: false, cursor: nil, cursor_max: 5000, **args) ⇒ Array

  Search the journals route.

• .licenses(query: nil, offset: nil, limit: nil, sample: nil, sort: nil, order: nil, facet: nil, options: nil, verbose: false) ⇒ Array

  Search the licenses route.

• .members(ids: nil, query: nil, filter: nil, offset: nil, limit: nil, sample: nil, sort: nil, order: nil, facet: nil, select: nil, works: false, options: nil, verbose: false, cursor: nil, cursor_max: 5000, **args) ⇒ Array

  Search the members route.

• .prefixes(ids:, filter: nil, offset: nil, limit: nil, sample: nil, sort: nil, order: nil, facet: nil, select: nil, works: false, options: nil, verbose: false, cursor: nil, cursor_max: 5000, **args) ⇒ Array

  Search the prefixes route.

• .random_dois(sample: 10, options: nil, verbose: false) ⇒ Array

  Get a random set of DOI’s.

• .registration_agency(ids:, options: nil, verbose: false) ⇒ Array

  Determine registration agency for DOIs.

• .types(ids: nil, offset: nil, limit: nil, select: nil, works: false, options: nil, verbose: false, cursor: nil, cursor_max: 5000, **args) ⇒ Array

  Search the types route.

• .works(ids: nil, query: nil, filter: nil, offset: nil, limit: nil, sample: nil, sort: nil, order: nil, facet: nil, select: nil, options: nil, verbose: false, cursor: nil, cursor_max: 5000, **args) ⇒ Array

  Search the works route.

Methods included from Configuration

configuration, define_setting

Class Method Details

.assert_valid_filters(filters) ⇒ Object

# File 'lib/serrano.rb', line 665

def self.assert_valid_filters(filters)
  unless filters.is_a? Hash
    raise ArgumentError, "      Filters must be provided as a hash, like:\n\n          Serrano.works(query: \"something\", filters: { has_abstract: true })\n    ERR\n  end\n\n  filters.each do |name, _|\n    filter_strings = Filters.names.map(&:to_s)\n    next if filter_strings.include?(name.to_s)\n\n    raise ArgumentError, <<~ERR\n      The filter \"\#{name}\" is not a valid filter. Please run `Serrano.filters.filters` to see all valid filters.\n    ERR\n  end\nend\n"

.citation_count(doi:, url: "https://www.crossref.org/openurl/", key: "cboettig@ropensci.org", options: nil) ⇒ Object

Get a citation count with a DOI

more info on this Crossref API service.

Examples:

require 'serrano'
Serrano.citation_count(doi: "10.1371/journal.pone.0042793")
Serrano.citation_count(doi: "10.1016/j.fbr.2012.01.001")
# DOI not found
Serrano.citation_count(doi: "10.1016/j.fbr.2012")

Parameters:

• options (Hash) (defaults to: nil) —

  Hash of options for configuring the request, passed on to Faraday.new

  • timeout [Fixnum] open/read timeout Integer in seconds

  • open_timeout [Fixnum] read timeout Integer in seconds

  • proxy [Hash] hash of proxy options

    • uri [String] Proxy Server URI

    • user [String] Proxy server username

    • password [String] Proxy server password

  • params_encoder [Hash] not sure what this is

  • bind [Hash] A hash with host and port values

  • boundary [String] of the boundary value

  • oauth [Hash] A hash with OAuth details

• doi (String) —

  DOI, digital object identifier

• url (String) (defaults to: "https://www.crossref.org/openurl/") —

  the API url for the function (should be left to default)

• key (String) (defaults to: "cboettig@ropensci.org") —

  your API key

See Also:

• for

# File 'lib/serrano.rb', line 644

def self.citation_count(doi:, url: "https://www.crossref.org/openurl/",
  key: "cboettig@ropensci.org", options: nil)
  args = {id: "doi:" + doi, pid: key, noredirect: true}
  opts = args.delete_if { |_k, v| v.nil? }
  conn = Faraday.new(url: url, request: options)
  res = conn.get "", opts
  x = res.body
  oc = REXML::Document.new("<doc>#{x}</doc>")
  REXML::XPath.first(oc, "//query").attributes["fl_count"].to_i
end

.content_negotiation(ids:, format: "bibtex", style: "apa", locale: "en-US") ⇒ Hash

Get citations in various formats from CrossRef

Examples:

require 'serrano'
# By default, you get bibtex, apa format, in en-US locale
Serrano.content_negotiation(ids: '10.1126/science.169.3946.635')

# get citeproc-json
Serrano.content_negotiation(ids: '10.1126/science.169.3946.635', format: "citeproc-json")
Serrano.content_negotiation(ids: "10.1126/science.169.3946.635", format: "citeproc-json")

# some other formats
Serrano.content_negotiation(ids: "10.1126/science.169.3946.635", format: "rdf-xml")
Serrano.content_negotiation(ids: "10.1126/science.169.3946.635", format: "crossref-xml")
Serrano.content_negotiation(ids: "10.1126/science.169.3946.635", format: "text")

# return a bibentry type
Serrano.content_negotiation(ids: "10.1126/science.169.3946.635", format: "bibentry")
Serrano.content_negotiation(ids: "10.6084/m9.figshare.97218", format: "bibentry")

# return an apa style citation
Serrano.content_negotiation(ids: "10.1126/science.169.3946.635", format: "text", style: "apa")
Serrano.content_negotiation(ids: "10.1126/science.169.3946.635", format: "text", style: "harvard3")
Serrano.content_negotiation(ids: "10.1126/science.169.3946.635", format: "text", style: "elsevier-harvard")
Serrano.content_negotiation(ids: "10.1126/science.169.3946.635", format: "text", style: "ecoscience")
Serrano.content_negotiation(ids: "10.1126/science.169.3946.635", format: "text", style: "heredity")
Serrano.content_negotiation(ids: "10.1126/science.169.3946.635", format: "text", style: "oikos")

# example with many DOIs
dois = Serrano.random_dois(sample: 2)
Serrano.content_negotiation(ids: dois, format: "text", style: "apa")

# Using DataCite DOIs
doi = "10.1126/science.169.3946.635"
Serrano.content_negotiation(ids: doi, format: "text")
Serrano.content_negotiation(ids: doi, format: "crossref-xml")
Serrano.content_negotiation(ids: doi, format: "crossref-tdm")

## But most do work
Serrano.content_negotiation(ids: doi, format: "datacite-xml")
Serrano.content_negotiation(ids: doi, format: "rdf-xml")
Serrano.content_negotiation(ids: doi, format: "turtle")
Serrano.content_negotiation(ids: doi, format: "citeproc-json")
Serrano.content_negotiation(ids: doi, format: "ris")
Serrano.content_negotiation(ids: doi, format: "bibtex")
Serrano.content_negotiation(ids: doi, format: "bibentry")
Serrano.content_negotiation(ids: doi, format: "bibtex")

# many DOIs
dois = ['10.5167/UZH-30455','10.5167/UZH-49216','10.5167/UZH-503',
 '10.5167/UZH-38402','10.5167/UZH-41217']
x = Serrano.content_negotiation(ids: dois)
puts x

Parameters:

• ids (String) —

  DOIs

• format (String) (defaults to: "bibtex") —

  Format

• style (String) (defaults to: "apa") —

  Style

• locale (String) (defaults to: "en-US") —

  Locale

Returns:

• (Hash) —

  A hash

# File 'lib/serrano.rb', line 623

def self.content_negotiation(ids:, format: "bibtex", style: "apa", locale: "en-US")
  ids = Array(ids).map { |x| ERB::Util.url_encode(x) }
  CNRequest.new(ids, format, style, locale).perform
end

.csl_styles ⇒ Object

Get csl styles

Examples:

Serrano.csl_styles

See Also:

• https://github.com/citation-style-language/styles

# File 'lib/serrano.rb', line 661

def self.csl_styles
  fetch_styles
end

.filters ⇒ Object

# File 'lib/serrano/filters.rb', line 4

def self.filters
  Filters
end

.funders(ids: nil, query: nil, filter: nil, offset: nil, limit: nil, sample: nil, sort: nil, order: nil, facet: nil, select: nil, works: false, options: nil, verbose: false, cursor: nil, cursor_max: 5000, **args) ⇒ Array

Note:

Funders without IDs don’t show up on the /funders route

Search the funders route

Examples:

require 'serrano'
# Search by DOI, one or more
Serrano.funders(ids: 100004410)
Serrano.funders(ids: ['10.13039/100000001','10.13039/100000015'])
# query
Serrano.funders(query: "NSF")
# works
Serrano.funders(ids: '10.13039/100000001', works: true)
# Limit number of results
Serrano.funders(ids: '10.13039/100000001', works: true, limit: 3)
# Sort and order
Serrano.funders(ids: "10.13039/100000001", works: true, sort: 'relevance', order: "asc")

# cursor - deep paging
res = Serrano.funders(ids: '10.13039/100000001', works: true, cursor: "*", cursor_max: 500);
res[0].collect { |x| x['message']['items'].length }.reduce(0, :+)
items = res[0].collect { |x| x['message']['items'] }.flatten;
items.collect{ |z| z['DOI'] }[0,50]

# field queries
## query.title
res = Serrano.funders(ids: "10.13039/100000001", works: true, query_author: 'Simon')
res[0]['message']['items'].collect { |x| x['author'][0]['family'] }

# select certain fields
Serrano.funders(ids: "10.13039/100000001", works: true, select: ['DOI', 'title'], limit: 3)

Parameters:

• offset (Fixnum) (defaults to: nil) —

  Number of record to start at, any non-negative integer up to 10,000

• limit (Fixnum) (defaults to: nil) —

  Number of results to return. Not relavant when searching with specific dois. Default: 20. Max: 1000

• sample (Fixnum) (defaults to: nil) —

  Number of random results to return. when you use the sample parameter, the limit and offset parameters are ignored. This parameter only used when works requested. Max: 100.

• sort (String) (defaults to: nil) —

  Field to sort on, one of score, relevance, updated (date of most recent change to metadata - currently the same as deposited), deposited (time of most recent deposit), indexed (time of most recent index), published (publication date), published-print (print publication date), published-online (online publication date), issued (issued date (earliest known publication date)), is-referenced-by-count (number of times this DOI is referenced by other Crossref DOIs), or references-count (number of references included in the references section of the document identified by this DOI). Note: If the API call includes a query, then the sort order will be by the relevance score. If no query is included, then the sort order will be by DOI update date.

• order (String) (defaults to: nil) —

  Sort order, one of ‘asc’ or ‘desc’

• facet (Boolean/String) (defaults to: nil) —

  Include facet results OR a query (e.g., ‘license:*`) to facet by license. Default: false

• select (String/Array(String)) (defaults to: nil) —

  Crossref metadata records can be quite large. Sometimes you just want a few elements from the schema. You can “select” a subset of elements to return. This can make your API calls much more efficient. Not clear yet which fields are allowed here.

• verbose (Boolean) (defaults to: false) —

  Print request headers to stdout. Default: false

• options (Hash) (defaults to: nil) —

  Hash of options for configuring the request, passed on to Faraday.new

  • timeout [Fixnum] open/read timeout Integer in seconds

  • open_timeout [Fixnum] read timeout Integer in seconds

  • proxy [Hash] hash of proxy options

    • uri [String] Proxy Server URI

    • user [String] Proxy server username

    • password [String] Proxy server password

  • params_encoder [Hash] not sure what this is

  • bind [Hash] A hash with host and port values

  • boundary [String] of the boundary value

  • oauth [Hash] A hash with OAuth details

• cursor (String) (defaults to: nil) —

  Cursor character string to do deep paging. Default is ‘nil`. Pass in ’*‘ to start deep paging. Any combination of query, filters and facets may be used with deep paging cursors. While limit may be specified along with cursor, offset and sample cannot be used. See api.crossref.org/

• cursor_max (Fixnum) (defaults to: 5000) —

  Max records to retrieve. Only used when cursor param used. Because deep paging can result in continuous requests until all are retrieved, use this parameter to set a maximum number of records. Of course, if there are less records found than this value, you will get only those found.

• args (Hash<Object>) —

  Field queries, as named parameters. See api.crossref.org/ Field query parameters mut be named, and must start with ‘query_`. Any dashes or periods should be replaced with underscores. The options include:

  • query_container_title: Query container-title aka. publication name

  • query_author: Query author given and family names

  • query_editor: Query editor given and family names

  • query_chair: Query chair given and family names

  • query_translator: Query translator given and family names

  • query_contributor: Query author, editor, chair and translator given and family names

  • query_bibliographic: Query bibliographic information, useful for citation look up. Includes titles, authors, ISSNs and publication years

  • query_affiliation: Query contributor affiliations

• ids (Array) (defaults to: nil) —

  DOIs (digital object identifier) or other identifiers

• query (String) (defaults to: nil) —

  A query string

• filter (Hash) (defaults to: nil) —

  Filter options. See …

• works (Boolean) (defaults to: false) —

  If true, works returned as well. Default: false

Returns:

• (Array) —

  An array of hashes

# File 'lib/serrano.rb', line 382

def self.funders(ids: nil, query: nil, filter: nil, offset: nil,
  limit: nil, sample: nil, sort: nil, order: nil, facet: nil,
  select: nil, works: false, options: nil, verbose: false,
  cursor: nil, cursor_max: 5000, **args)
  assert_valid_filters(filter) if filter
  RequestCursor.new("funders", ids, query, filter, offset,
    limit, sample, sort, order, facet, select, works, nil, options,
    verbose, cursor, cursor_max, args).perform
end

.journals(ids: nil, query: nil, filter: nil, offset: nil, limit: nil, sample: nil, sort: nil, order: nil, facet: nil, select: nil, works: false, options: nil, verbose: false, cursor: nil, cursor_max: 5000, **args) ⇒ Array

Search the journals route

Examples:

require 'serrano'
Serrano.journals(ids: "2167-8359")
Serrano.journals()
Serrano.journals(ids: "2167-8359", works: true)
Serrano.journals(ids: ['1803-2427', '2326-4225'])
Serrano.journals(query: "ecology")
Serrano.journals(query: "peerj")
Serrano.journals(ids: "2167-8359", query: 'ecology', works: true, sort: 'score', order: "asc")
Serrano.journals(ids: "2167-8359", query: 'ecology', works: true, sort: 'score', order: "desc")
Serrano.journals(ids: "2167-8359", works: true, filter: {from_pub_date: '2014-03-03'})
Serrano.journals(ids: '1803-2427', works: true)
Serrano.journals(ids: '1803-2427', works: true)
Serrano.journals(limit: 2)
Serrano.journals(sample: 2)

# cursor - deep paging
res = Serrano.journals(ids: "2167-8359", works: true, cursor: "*", cursor_max: 500);
res[0].collect { |x| x['message']['items'].length }.reduce(0, :+)
items = res[0].collect { |x| x['message']['items'] }.flatten;
items.collect{ |z| z['DOI'] }[0,50]

# field queries
## query.title
res = Serrano.journals(ids: "2167-8359", works: true, query_container_title: 'Advances')
res[0]['message']['items'].collect { |x| x['container-title'] }

# select certain fields
Serrano.journals(ids: "2167-8359", works: true, select: ['DOI', 'title'], limit: 3)

Parameters:

• offset (Fixnum) (defaults to: nil) —

  Number of record to start at, any non-negative integer up to 10,000

• limit (Fixnum) (defaults to: nil) —

  Number of results to return. Not relavant when searching with specific dois. Default: 20. Max: 1000

• sample (Fixnum) (defaults to: nil) —

  Number of random results to return. when you use the sample parameter, the limit and offset parameters are ignored. This parameter only used when works requested. Max: 100.

• sort (String) (defaults to: nil) —

  Field to sort on, one of score, relevance, updated (date of most recent change to metadata - currently the same as deposited), deposited (time of most recent deposit), indexed (time of most recent index), published (publication date), published-print (print publication date), published-online (online publication date), issued (issued date (earliest known publication date)), is-referenced-by-count (number of times this DOI is referenced by other Crossref DOIs), or references-count (number of references included in the references section of the document identified by this DOI). Note: If the API call includes a query, then the sort order will be by the relevance score. If no query is included, then the sort order will be by DOI update date.

• order (String) (defaults to: nil) —

  Sort order, one of ‘asc’ or ‘desc’

• facet (Boolean/String) (defaults to: nil) —

  Include facet results OR a query (e.g., ‘license:*`) to facet by license. Default: false

• select (String/Array(String)) (defaults to: nil) —

  Crossref metadata records can be quite large. Sometimes you just want a few elements from the schema. You can “select” a subset of elements to return. This can make your API calls much more efficient. Not clear yet which fields are allowed here.

• verbose (Boolean) (defaults to: false) —

  Print request headers to stdout. Default: false

• options (Hash) (defaults to: nil) —

  Hash of options for configuring the request, passed on to Faraday.new

  • timeout [Fixnum] open/read timeout Integer in seconds

  • open_timeout [Fixnum] read timeout Integer in seconds

  • proxy [Hash] hash of proxy options

    • uri [String] Proxy Server URI

    • user [String] Proxy server username

    • password [String] Proxy server password

  • params_encoder [Hash] not sure what this is

  • bind [Hash] A hash with host and port values

  • boundary [String] of the boundary value

  • oauth [Hash] A hash with OAuth details

• cursor (String) (defaults to: nil) —

  Cursor character string to do deep paging. Default is ‘nil`. Pass in ’*‘ to start deep paging. Any combination of query, filters and facets may be used with deep paging cursors. While limit may be specified along with cursor, offset and sample cannot be used. See api.crossref.org/

• cursor_max (Fixnum) (defaults to: 5000) —

  Max records to retrieve. Only used when cursor param used. Because deep paging can result in continuous requests until all are retrieved, use this parameter to set a maximum number of records. Of course, if there are less records found than this value, you will get only those found.

• args (Hash<Object>) —

  Field queries, as named parameters. See api.crossref.org/ Field query parameters mut be named, and must start with ‘query_`. Any dashes or periods should be replaced with underscores. The options include:

  • query_container_title: Query container-title aka. publication name

  • query_author: Query author given and family names

  • query_editor: Query editor given and family names

  • query_chair: Query chair given and family names

  • query_translator: Query translator given and family names

  • query_contributor: Query author, editor, chair and translator given and family names

  • query_bibliographic: Query bibliographic information, useful for citation look up. Includes titles, authors, ISSNs and publication years

  • query_affiliation: Query contributor affiliations

• ids (Array) (defaults to: nil) —

  DOIs (digital object identifier) or other identifiers

• query (String) (defaults to: nil) —

  A query string

• filter (Hash) (defaults to: nil) —

  Filter options. See …

• works (Boolean) (defaults to: false) —

  If true, works returned as well. Default: false

Returns:

• (Array) —

  An array of hashes

# File 'lib/serrano.rb', line 434

def self.journals(ids: nil, query: nil, filter: nil, offset: nil,
  limit: nil, sample: nil, sort: nil, order: nil, facet: nil,
  select: nil, works: false, options: nil, verbose: false,
  cursor: nil, cursor_max: 5000, **args)
  assert_valid_filters(filter) if filter
  RequestCursor.new("journals", ids, query, filter, offset,
    limit, sample, sort, order, facet, select, works, nil, options,
    verbose, cursor, cursor_max, args).perform
end

.licenses(query: nil, offset: nil, limit: nil, sample: nil, sort: nil, order: nil, facet: nil, options: nil, verbose: false) ⇒ Array

Search the licenses route

Examples:

require 'serrano'
Serrano.licenses(query: "creative")
Serrano.licenses()
Serrano.licenses(limit: 3)

Parameters:

• options (Hash) (defaults to: nil) —

  Hash of options for configuring the request, passed on to Faraday.new

  • timeout [Fixnum] open/read timeout Integer in seconds

  • open_timeout [Fixnum] read timeout Integer in seconds

  • proxy [Hash] hash of proxy options

    • uri [String] Proxy Server URI

    • user [String] Proxy server username

    • password [String] Proxy server password

  • params_encoder [Hash] not sure what this is

  • bind [Hash] A hash with host and port values

  • boundary [String] of the boundary value

  • oauth [Hash] A hash with OAuth details

• query (String) (defaults to: nil) —

  A query string

• offset (Fixnum) (defaults to: nil) —

  Number of record to start at, any non-negative integer up to 10,000

• limit (Fixnum) (defaults to: nil) —

  Number of results to return. Not relavant when searching with specific dois. Default: 20. Max: 1000

• sample (Fixnum) (defaults to: nil) —

  Number of random results to return. when you use the sample parameter, the limit and offset parameters are ignored. This parameter only used when works requested. Max: 100.

• sort (String) (defaults to: nil) —

  Field to sort on, one of score, relevance, updated (date of most recent change to metadata - currently the same as deposited), deposited (time of most recent deposit), indexed (time of most recent index), published (publication date), published-print (print publication date), published-online (online publication date), issued (issued date (earliest known publication date)), is-referenced-by-count (number of times this DOI is referenced by other Crossref DOIs), or references-count (number of references included in the references section of the document identified by this DOI). Note: If the API call includes a query, then the sort order will be by the relevance score. If no query is included, then the sort order will be by DOI update date.

• order (String) (defaults to: nil) —

  Sort order, one of ‘asc’ or ‘desc’

• facet (Boolean/String) (defaults to: nil) —

  Include facet results OR a query (e.g., ‘license:*`) to facet by license. Default: false

• verbose (Boolean) (defaults to: false) —

  Print request headers to stdout. Default: false

Returns:

• (Array) —

  An array of hashes

# File 'lib/serrano.rb', line 517

def self.licenses(query: nil, offset: nil,
  limit: nil, sample: nil, sort: nil, order: nil,
  facet: nil, options: nil, verbose: false)
  Request.new("licenses", nil, query, nil, offset,
    limit, sample, sort, order, facet, nil, nil, nil, options, verbose).perform
end

.members(ids: nil, query: nil, filter: nil, offset: nil, limit: nil, sample: nil, sort: nil, order: nil, facet: nil, select: nil, works: false, options: nil, verbose: false, cursor: nil, cursor_max: 5000, **args) ⇒ Array

Search the members route

Examples:

require 'serrano'
# Search by DOI, one or more
Serrano.members(ids: 98)
Serrano.members(ids: 340)
Serrano.members(ids: [98, 340, 45])
# query
Serrano.members(query: "ecology")
Serrano.members(query: "hindawi")
# Sort - weird, doesn't work
Serrano.members(query: "ecology", order: "asc")
# Works
Serrano.members(ids: 98, works: true)

# cursor - deep paging
res = Serrano.members(ids: 98, works: true, cursor: "*", cursor_max: 1000);
res[0].collect { |x| x['message']['items'].length }.reduce(0, :+)
items = res[0].collect { |x| x['message']['items'] }.flatten
items.collect{ |z| z['DOI'] }[0,50]

# multiple ids with cursor
res = Serrano.members(ids: [98, 340], works: true, cursor: "*", cursor_max: 300);
res[0].collect { |x| x['message']['items'].length }.reduce(0, :+)
items = res[0].collect { |x| x['message']['items'] }.flatten
items.collect{ |z| z['DOI'] }[0,50]

# field queries
## query.title
res = Serrano.members(ids: 221, works: true, query_container_title: 'Advances')
res[0]['message']['items'].collect { |x| x['container-title'] }

# select certain fields
Serrano.members(ids: 340, works: true, select: ['DOI', 'title'], limit: 3)

Parameters:

• offset (Fixnum) (defaults to: nil) —

  Number of record to start at, any non-negative integer up to 10,000

• limit (Fixnum) (defaults to: nil) —

  Number of results to return. Not relavant when searching with specific dois. Default: 20. Max: 1000

• sample (Fixnum) (defaults to: nil) —

  Number of random results to return. when you use the sample parameter, the limit and offset parameters are ignored. This parameter only used when works requested. Max: 100.

• sort (String) (defaults to: nil) —

  Field to sort on, one of score, relevance, updated (date of most recent change to metadata - currently the same as deposited), deposited (time of most recent deposit), indexed (time of most recent index), published (publication date), published-print (print publication date), published-online (online publication date), issued (issued date (earliest known publication date)), is-referenced-by-count (number of times this DOI is referenced by other Crossref DOIs), or references-count (number of references included in the references section of the document identified by this DOI). Note: If the API call includes a query, then the sort order will be by the relevance score. If no query is included, then the sort order will be by DOI update date.

• order (String) (defaults to: nil) —

  Sort order, one of ‘asc’ or ‘desc’

• facet (Boolean/String) (defaults to: nil) —

  Include facet results OR a query (e.g., ‘license:*`) to facet by license. Default: false

• select (String/Array(String)) (defaults to: nil) —

  Crossref metadata records can be quite large. Sometimes you just want a few elements from the schema. You can “select” a subset of elements to return. This can make your API calls much more efficient. Not clear yet which fields are allowed here.

• verbose (Boolean) (defaults to: false) —

  Print request headers to stdout. Default: false

• options (Hash) (defaults to: nil) —

  Hash of options for configuring the request, passed on to Faraday.new

  • timeout [Fixnum] open/read timeout Integer in seconds

  • open_timeout [Fixnum] read timeout Integer in seconds

  • proxy [Hash] hash of proxy options

    • uri [String] Proxy Server URI

    • user [String] Proxy server username

    • password [String] Proxy server password

  • params_encoder [Hash] not sure what this is

  • bind [Hash] A hash with host and port values

  • boundary [String] of the boundary value

  • oauth [Hash] A hash with OAuth details

• cursor (String) (defaults to: nil) —

  Cursor character string to do deep paging. Default is ‘nil`. Pass in ’*‘ to start deep paging. Any combination of query, filters and facets may be used with deep paging cursors. While limit may be specified along with cursor, offset and sample cannot be used. See api.crossref.org/

• cursor_max (Fixnum) (defaults to: 5000) —

  Max records to retrieve. Only used when cursor param used. Because deep paging can result in continuous requests until all are retrieved, use this parameter to set a maximum number of records. Of course, if there are less records found than this value, you will get only those found.

• args (Hash<Object>) —

  Field queries, as named parameters. See api.crossref.org/ Field query parameters mut be named, and must start with ‘query_`. Any dashes or periods should be replaced with underscores. The options include:

  • query_container_title: Query container-title aka. publication name

  • query_author: Query author given and family names

  • query_editor: Query editor given and family names

  • query_chair: Query chair given and family names

  • query_translator: Query translator given and family names

  • query_contributor: Query author, editor, chair and translator given and family names

  • query_bibliographic: Query bibliographic information, useful for citation look up. Includes titles, authors, ISSNs and publication years

  • query_affiliation: Query contributor affiliations

• ids (Array) (defaults to: nil) —

  DOIs (digital object identifier) or other identifiers

• query (String) (defaults to: nil) —

  A query string

• filter (Hash) (defaults to: nil) —

  Filter options. See …

• works (Boolean) (defaults to: false) —

  If true, works returned as well. Default: false

Returns:

• (Array) —

  An array of hashes

# File 'lib/serrano.rb', line 283

def self.members(ids: nil, query: nil, filter: nil, offset: nil,
  limit: nil, sample: nil, sort: nil, order: nil, facet: nil,
  select: nil, works: false, options: nil, verbose: false,
  cursor: nil, cursor_max: 5000, **args)
  assert_valid_filters(filter) if filter
  RequestCursor.new("members", ids, query, filter, offset,
    limit, sample, sort, order, facet, select, works, nil,
    options, verbose, cursor, cursor_max, args).perform
end

.prefixes(ids:, filter: nil, offset: nil, limit: nil, sample: nil, sort: nil, order: nil, facet: nil, select: nil, works: false, options: nil, verbose: false, cursor: nil, cursor_max: 5000, **args) ⇒ Array

Search the prefixes route

Examples:

require 'serrano'
# Search by DOI, one or more
Serrano.prefixes(ids: "10.1016")
Serrano.prefixes(ids: ['10.1016','10.1371','10.1023','10.4176','10.1093'])
# works
Serrano.prefixes(ids: "10.1016", works: true)
# Limit number of results
Serrano.prefixes(ids: "10.1016", works: true, limit: 3)
# Sort and order
Serrano.prefixes(ids: "10.1016", works: true, sort: 'relevance', order: "asc")

# cursor - deep paging
res = Serrano.prefixes(ids: "10.1016", works: true, cursor: "*", cursor_max: 1000);
res[0].collect { |x| x['message']['items'].length }.reduce(0, :+)
items = res[0].collect { |x| x['message']['items'] }.flatten;
items.collect{ |z| z['DOI'] }[0,50]

# field queries
## query.bibliographic
res = Serrano.prefixes(ids: "10.1016", works: true, query_bibliographic: 'cell biology')
res[0]['message']['items'].collect { |x| x['title'] }

# select certain fields
Serrano.prefixes(ids: "10.1016", works: true, select: ['DOI', 'title'], limit: 3)

Parameters:

• offset (Fixnum) (defaults to: nil) —

  Number of record to start at, any non-negative integer up to 10,000

• limit (Fixnum) (defaults to: nil) —

  Number of results to return. Not relavant when searching with specific dois. Default: 20. Max: 1000

• sample (Fixnum) (defaults to: nil) —

  Number of random results to return. when you use the sample parameter, the limit and offset parameters are ignored. This parameter only used when works requested. Max: 100.

• sort (String) (defaults to: nil) —

  Field to sort on, one of score, relevance, updated (date of most recent change to metadata - currently the same as deposited), deposited (time of most recent deposit), indexed (time of most recent index), published (publication date), published-print (print publication date), published-online (online publication date), issued (issued date (earliest known publication date)), is-referenced-by-count (number of times this DOI is referenced by other Crossref DOIs), or references-count (number of references included in the references section of the document identified by this DOI). Note: If the API call includes a query, then the sort order will be by the relevance score. If no query is included, then the sort order will be by DOI update date.

• order (String) (defaults to: nil) —

  Sort order, one of ‘asc’ or ‘desc’

• facet (Boolean/String) (defaults to: nil) —

  Include facet results OR a query (e.g., ‘license:*`) to facet by license. Default: false

• select (String/Array(String)) (defaults to: nil) —

  Crossref metadata records can be quite large. Sometimes you just want a few elements from the schema. You can “select” a subset of elements to return. This can make your API calls much more efficient. Not clear yet which fields are allowed here.

• verbose (Boolean) (defaults to: false) —

  Print request headers to stdout. Default: false

• options (Hash) (defaults to: nil) —

  Hash of options for configuring the request, passed on to Faraday.new

  • timeout [Fixnum] open/read timeout Integer in seconds

  • open_timeout [Fixnum] read timeout Integer in seconds

  • proxy [Hash] hash of proxy options

    • uri [String] Proxy Server URI

    • user [String] Proxy server username

    • password [String] Proxy server password

  • params_encoder [Hash] not sure what this is

  • bind [Hash] A hash with host and port values

  • boundary [String] of the boundary value

  • oauth [Hash] A hash with OAuth details

• cursor (String) (defaults to: nil) —

  Cursor character string to do deep paging. Default is ‘nil`. Pass in ’*‘ to start deep paging. Any combination of query, filters and facets may be used with deep paging cursors. While limit may be specified along with cursor, offset and sample cannot be used. See api.crossref.org/

• cursor_max (Fixnum) (defaults to: 5000) —

  Max records to retrieve. Only used when cursor param used. Because deep paging can result in continuous requests until all are retrieved, use this parameter to set a maximum number of records. Of course, if there are less records found than this value, you will get only those found.

• args (Hash<Object>) —

  Field queries, as named parameters. See api.crossref.org/ Field query parameters mut be named, and must start with ‘query_`. Any dashes or periods should be replaced with underscores. The options include:

  • query_container_title: Query container-title aka. publication name

  • query_author: Query author given and family names

  • query_editor: Query editor given and family names

  • query_chair: Query chair given and family names

  • query_translator: Query translator given and family names

  • query_contributor: Query author, editor, chair and translator given and family names

  • query_bibliographic: Query bibliographic information, useful for citation look up. Includes titles, authors, ISSNs and publication years

  • query_affiliation: Query contributor affiliations

• ids (Array) —

  DOIs (digital object identifier) or other identifiers

• filter (Hash) (defaults to: nil) —

  Filter options. See …

• works (Boolean) (defaults to: false) —

  If true, works returned as well. Default: false

Returns:

• (Array) —

  An array of hashes

# File 'lib/serrano.rb', line 330

def self.prefixes(ids:, filter: nil, offset: nil,
  limit: nil, sample: nil, sort: nil, order: nil, facet: nil,
  select: nil, works: false, options: nil, verbose: false,
  cursor: nil, cursor_max: 5000, **args)
  assert_valid_filters(filter) if filter
  RequestCursor.new("prefixes", ids, nil, filter, offset,
    limit, sample, sort, order, facet, select, works, nil,
    options, verbose, cursor, cursor_max, args).perform
end

.random_dois(sample: 10, options: nil, verbose: false) ⇒ Array

Note:

This method uses works internally, but doesn’t allow you to pass on

Get a random set of DOI’s

arguments to that method.

Examples:

require 'serrano'
# by default, gives 10
Serrano.random_dois()
Serrano.random_dois(sample: 1)
Serrano.random_dois(sample: 10)
Serrano.random_dois(sample: 100)

Parameters:

• options (Hash) (defaults to: nil) —

  Hash of options for configuring the request, passed on to Faraday.new

  • timeout [Fixnum] open/read timeout Integer in seconds

  • open_timeout [Fixnum] read timeout Integer in seconds

  • proxy [Hash] hash of proxy options

    • uri [String] Proxy Server URI

    • user [String] Proxy server username

    • password [String] Proxy server password

  • params_encoder [Hash] not sure what this is

  • bind [Hash] A hash with host and port values

  • boundary [String] of the boundary value

  • oauth [Hash] A hash with OAuth details

• sample (Fixnum) (defaults to: 10) —

  Number of random DOIs to return. Max: 100. Default: 10

• verbose (Boolean) (defaults to: false) —

  Print request headers to stdout. Default: false

Returns:

• (Array) —

  A list of strings, each a DOI

# File 'lib/serrano.rb', line 557

def self.random_dois(sample: 10, options: nil, verbose: false)
  tmp = Request.new("works", nil, nil, nil, nil,
    nil, sample, nil, nil, nil, nil, false, nil, options, verbose).perform
  tmp["message"]["items"].collect { |x| x["DOI"] }
end

.registration_agency(ids:, options: nil, verbose: false) ⇒ Array

Determine registration agency for DOIs

Examples:

require 'serrano'
Serrano.registration_agency(ids: '10.1371/journal.pone.0033693')
Serrano.registration_agency(ids: ['10.1007/12080.1874-1746','10.1007/10452.1573-5125', '10.1111/(issn)1442-9993'])

Parameters:

• options (Hash) (defaults to: nil) —

  Hash of options for configuring the request, passed on to Faraday.new

  • timeout [Fixnum] open/read timeout Integer in seconds

  • open_timeout [Fixnum] read timeout Integer in seconds

  • proxy [Hash] hash of proxy options

    • uri [String] Proxy Server URI

    • user [String] Proxy server username

    • password [String] Proxy server password

  • params_encoder [Hash] not sure what this is

  • bind [Hash] A hash with host and port values

  • boundary [String] of the boundary value

  • oauth [Hash] A hash with OAuth details

• ids (Array) —

  DOIs (digital object identifier) or other identifiers

Returns:

• (Array) —

  An array of hashes

# File 'lib/serrano.rb', line 535

def self.registration_agency(ids:, options: nil, verbose: false)
  Request.new("works", ids, nil, nil, nil,
    nil, nil, nil, nil, nil, nil, false, true, options, verbose).perform
end

.types(ids: nil, offset: nil, limit: nil, select: nil, works: false, options: nil, verbose: false, cursor: nil, cursor_max: 5000, **args) ⇒ Array

Search the types route

Examples:

require 'serrano'
Serrano.types()
Serrano.types(ids: "journal")
Serrano.types(ids: ["journal", "dissertation"])
Serrano.types(ids: "journal", works: true)

# cursor - deep paging
res = Serrano.types(ids: "journal", works: true, cursor: "*", cursor_max: 500);
res[0].collect { |x| x['message']['items'].length }.reduce(0, :+)
items = res[0].collect { |x| x['message']['items'] }.flatten;
items.collect{ |z| z['DOI'] }[0,50]

# field queries
## query.title
res = Serrano.types(ids: "journal", works: true, query_container_title: 'Advances')
res[0]['message']['items'].collect { |x| x['container-title'] }

# select certain fields
Serrano.types(ids: "journal", works: true, select: ['DOI', 'title'], limit: 3)

Parameters:

• options (Hash) (defaults to: nil) —

  Hash of options for configuring the request, passed on to Faraday.new

  • timeout [Fixnum] open/read timeout Integer in seconds

  • open_timeout [Fixnum] read timeout Integer in seconds

  • proxy [Hash] hash of proxy options

    • uri [String] Proxy Server URI

    • user [String] Proxy server username

    • password [String] Proxy server password

  • params_encoder [Hash] not sure what this is

  • bind [Hash] A hash with host and port values

  • boundary [String] of the boundary value

  • oauth [Hash] A hash with OAuth details

• cursor (String) (defaults to: nil) —

  Cursor character string to do deep paging. Default is ‘nil`. Pass in ’*‘ to start deep paging. Any combination of query, filters and facets may be used with deep paging cursors. While limit may be specified along with cursor, offset and sample cannot be used. See api.crossref.org/

• cursor_max (Fixnum) (defaults to: 5000) —

  Max records to retrieve. Only used when cursor param used. Because deep paging can result in continuous requests until all are retrieved, use this parameter to set a maximum number of records. Of course, if there are less records found than this value, you will get only those found.

• args (Hash<Object>) —

  Field queries, as named parameters. See api.crossref.org/ Field query parameters mut be named, and must start with ‘query_`. Any dashes or periods should be replaced with underscores. The options include:

  • query_container_title: Query container-title aka. publication name

  • query_author: Query author given and family names

  • query_editor: Query editor given and family names

  • query_chair: Query chair given and family names

  • query_translator: Query translator given and family names

  • query_contributor: Query author, editor, chair and translator given and family names

  • query_bibliographic: Query bibliographic information, useful for citation look up. Includes titles, authors, ISSNs and publication years

  • query_affiliation: Query contributor affiliations

• ids (Array) (defaults to: nil) —

  DOIs (digital object identifier) or other identifiers

• works (Boolean) (defaults to: false) —

  If true, works returned as well. Default: false

• select (String/Array(String)) (defaults to: nil) —

  Crossref metadata records can be quite large. Sometimes you just want a few elements from the schema. You can “select” a subset of elements to return. This can make your API calls much more efficient. Not clear yet which fields are allowed here.

Returns:

• (Array) —

  An array of hashes

# File 'lib/serrano.rb', line 478

def self.types(ids: nil, offset: nil, limit: nil, select: nil, works: false,
  options: nil, verbose: false, cursor: nil, cursor_max: 5000, **args)
  RequestCursor.new("types", ids, nil, nil, offset,
    limit, nil, nil, nil, nil, select, works, nil, options,
    verbose, cursor, cursor_max, args).perform
end

.works(ids: nil, query: nil, filter: nil, offset: nil, limit: nil, sample: nil, sort: nil, order: nil, facet: nil, select: nil, options: nil, verbose: false, cursor: nil, cursor_max: 5000, **args) ⇒ Array

Search the works route

Examples:

require 'serrano'
# Search by DOI, one or more
Serrano.works(ids: '10.5555/515151')
Serrano.works(ids: '10.1371/journal.pone.0033693')
Serrano.works(ids: ['10.1007/12080.1874-1746','10.1007/10452.1573-5125', '10.1111/(issn)1442-9993'])
Serrano.works(ids: ["10.1016/0304-4009(81)90025-5", "10.1016/0304-4009(83)90036-0"])

# query
Serrano.works(query: "ecology")
Serrano.works(query: "renear+-ontologies")

# Sort
Serrano.works(query: "ecology", sort: 'relevance', order: "asc")

# Filters
Serrano.works(filter: {has_full_text: true})
res = Serrano.works(filter: {has_full_text: true})
Serrano.works(filter: {has_funder: true, has_full_text: true})
Serrano.works(filter: {award_number: 'CBET-0756451', award_funder: '10.13039/100000001'})
Serrano.works(filter: {has_abstract: true})
Serrano.works(filter: {has_clinical_trial_number: true})

# Curl options
## set a request timeout and an open timeout
Serrano.works(ids: '10.1371/journal.pone.0033693', options: {timeout: 3, open_timeout: 2})
## log request details - uses Faraday middleware
Serrano.works(ids: '10.1371/journal.pone.0033693', verbose: true)

# facets
Serrano.works(facet: 'license:*', limit: 0, filter: {has_full_text: true})

# sample
Serrano.works(sample: 2)

# select - pass an array or a comma separated string
Serrano.works(query: "ecology", select: "DOI,title", limit: 30)
Serrano.works(query: "ecology", select: ["DOI","title"], limit: 30)

# cursor for deep paging
Serrano.works(query: "widget", cursor: "*", limit: 100, cursor_max: 1000)
# another query, more results this time
res = Serrano.works(query: "science", cursor: "*", limit: 250, cursor_max: 1000);
res.collect { |x| x['message']['items'].length }.reduce(0, :+)
# another query
res = Serrano.works(query: "ecology", cursor: "*", limit: 1000, cursor_max: 10000);
res.collect { |x| x['message']['items'].length }.reduce(0, :+)
items = res.collect {|x| x['message']['items']}.flatten
items.collect { |x| x['DOI'] }[0,20]

# field queries
## query.author
res = Serrano.works(query: "ecology", query_author: 'Boettiger')
res['message']['items'].collect { |x| x['author'][0]['family'] }

## query.container-title
res = Serrano.works(query: "ecology", query_container_title: 'Ecology')
res['message']['items'].collect { |x| x['container-title'] }

# select certain fields
Serrano.works(select: ['DOI', 'title'], limit: 3)

Parameters:

• offset (Fixnum) (defaults to: nil) —

  Number of record to start at, any non-negative integer up to 10,000

• limit (Fixnum) (defaults to: nil) —

  Number of results to return. Not relavant when searching with specific dois. Default: 20. Max: 1000

• sample (Fixnum) (defaults to: nil) —

  Number of random results to return. when you use the sample parameter, the limit and offset parameters are ignored. This parameter only used when works requested. Max: 100.

• sort (String) (defaults to: nil) —

  Field to sort on, one of score, relevance, updated (date of most recent change to metadata - currently the same as deposited), deposited (time of most recent deposit), indexed (time of most recent index), published (publication date), published-print (print publication date), published-online (online publication date), issued (issued date (earliest known publication date)), is-referenced-by-count (number of times this DOI is referenced by other Crossref DOIs), or references-count (number of references included in the references section of the document identified by this DOI). Note: If the API call includes a query, then the sort order will be by the relevance score. If no query is included, then the sort order will be by DOI update date.

• order (String) (defaults to: nil) —

  Sort order, one of ‘asc’ or ‘desc’

• facet (Boolean/String) (defaults to: nil) —

  Include facet results OR a query (e.g., ‘license:*`) to facet by license. Default: false

• select (String/Array(String)) (defaults to: nil) —

  Crossref metadata records can be quite large. Sometimes you just want a few elements from the schema. You can “select” a subset of elements to return. This can make your API calls much more efficient. Not clear yet which fields are allowed here.

• verbose (Boolean) (defaults to: false) —

  Print request headers to stdout. Default: false

• options (Hash) (defaults to: nil) —

  Hash of options for configuring the request, passed on to Faraday.new

  • timeout [Fixnum] open/read timeout Integer in seconds

  • open_timeout [Fixnum] read timeout Integer in seconds

  • proxy [Hash] hash of proxy options

    • uri [String] Proxy Server URI

    • user [String] Proxy server username

    • password [String] Proxy server password

  • params_encoder [Hash] not sure what this is

  • bind [Hash] A hash with host and port values

  • boundary [String] of the boundary value

  • oauth [Hash] A hash with OAuth details

• cursor (String) (defaults to: nil) —

  Cursor character string to do deep paging. Default is ‘nil`. Pass in ’*‘ to start deep paging. Any combination of query, filters and facets may be used with deep paging cursors. While limit may be specified along with cursor, offset and sample cannot be used. See api.crossref.org/

• cursor_max (Fixnum) (defaults to: 5000) —

  Max records to retrieve. Only used when cursor param used. Because deep paging can result in continuous requests until all are retrieved, use this parameter to set a maximum number of records. Of course, if there are less records found than this value, you will get only those found.

• args (Hash<Object>) —

  Field queries, as named parameters. See api.crossref.org/ Field query parameters mut be named, and must start with ‘query_`. Any dashes or periods should be replaced with underscores. The options include:

  • query_container_title: Query container-title aka. publication name

  • query_author: Query author given and family names

  • query_editor: Query editor given and family names

  • query_chair: Query chair given and family names

  • query_translator: Query translator given and family names

  • query_contributor: Query author, editor, chair and translator given and family names

  • query_bibliographic: Query bibliographic information, useful for citation look up. Includes titles, authors, ISSNs and publication years

  • query_affiliation: Query contributor affiliations

• ids (Array) (defaults to: nil) —

  DOIs (digital object identifier) or other identifiers

• query (String) (defaults to: nil) —

  A query string

• filter (Hash) (defaults to: nil) —

  Filter options. See …

Returns:

• (Array) —

  An array of hashes

# File 'lib/serrano.rb', line 227

def self.works(ids: nil, query: nil, filter: nil, offset: nil,
  limit: nil, sample: nil, sort: nil, order: nil, facet: nil,
  select: nil, options: nil, verbose: false, cursor: nil,
  cursor_max: 5000, **args)
  assert_valid_filters(filter) if filter
  RequestCursor.new("works", ids, query, filter, offset,
    limit, sample, sort, order, facet, select, nil, nil, options,
    verbose, cursor, cursor_max, args).perform
end