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 =

"0.2.2"

Class Method Summary

• .citation_count(doi:, url: "http://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.

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

  Search the funders route.

• .journals(ids: nil, query: nil, filter: nil, offset: nil, limit: nil, sample: nil, sort: nil, order: nil, facet: nil, works: false, options: nil, verbose: false, cursor: nil, cursor_max: 5000) ⇒ 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, works: false, options: nil, verbose: false, cursor: nil, cursor_max: 5000) ⇒ Array

  Search the members route.

• .prefixes(ids:, filter: nil, offset: nil, limit: nil, sample: nil, sort: nil, order: nil, facet: nil, works: false, options: nil, verbose: false, cursor: nil, cursor_max: 5000) ⇒ 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, works: false, options: nil, verbose: false, cursor: nil, cursor_max: 5000) ⇒ Array

  Search the types route.

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

  Search the works route.

Methods included from Configuration

configuration, define_setting

Class Method Details

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

Get a citation count with a DOI

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: "http://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 more info on this Crossref API service.

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

def self.citation_count(doi:, url: "http://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>")
  value = REXML::XPath.first(oc, '//query').attributes['fl_count'].to_i
  return value
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 an R 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 = cr_r(2)
Serrano.content_negotiation(dois, format: "text", style: "apa")

# Using DataCite DOIs
## some formats don't work
# Serrano.content_negotiation(ids: "10.5284/1011335", format: "text")
# Serrano.content_negotiation(ids: "10.5284/1011335", format: "crossref-xml")
# Serrano.content_negotiation(ids: "10.5284/1011335", format: "crossref-tdm")

## But most do work
Serrano.content_negotiation(ids: "10.5284/1011335", format: "datacite-xml")
Serrano.content_negotiation(ids: "10.5284/1011335", format: "rdf-xml")
Serrano.content_negotiation(ids: "10.5284/1011335", format: "turtle")
Serrano.content_negotiation(ids: "10.5284/1011335", format: "citeproc-json")
Serrano.content_negotiation(ids: "10.5284/1011335", format: "ris")
Serrano.content_negotiation(ids: "10.5284/1011335", format: "bibtex")
Serrano.content_negotiation(ids: "10.5284/1011335", format: "bibentry")
Serrano.content_negotiation(ids: "10.5284/1011335", 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 475

def self.content_negotiation(ids:, format: "bibtex", style: 'apa', locale: "en-US")
  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 513

def self.csl_styles
  get_styles()
end

.funders(ids: nil, query: nil, filter: nil, offset: nil, limit: nil, sample: nil, sort: nil, order: nil, facet: nil, works: false, options: nil, verbose: false, cursor: nil, cursor_max: 5000) ⇒ 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]

Parameters:

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

  Number of record to start at, from 1 to infinity.

• 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.

• 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), or published (publication date). 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) (defaults to: nil) —

  Include facet results. Default: false

• 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 github.com/CrossRef/rest-api-doc/blob/master/rest_api.md#deep-paging-with-cursors

• 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.

• 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 272

def self.funders(ids: nil, query: nil, filter: nil, offset: nil,
  limit: nil, sample: nil, sort: nil, order: nil, facet: nil,
  works: false, options: nil, verbose: false,
  cursor: nil, cursor_max: 5000)

  RequestCursor.new('funders', ids, query, filter, offset,
    limit, sample, sort, order, facet, works, nil, options,
    verbose, cursor, cursor_max).perform
end

.journals(ids: nil, query: nil, filter: nil, offset: nil, limit: nil, sample: nil, sort: nil, order: nil, facet: nil, works: false, options: nil, verbose: false, cursor: nil, cursor_max: 5000) ⇒ 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]

Parameters:

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

  Number of record to start at, from 1 to infinity.

• 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.

• 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), or published (publication date). 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) (defaults to: nil) —

  Include facet results. Default: false

• 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 github.com/CrossRef/rest-api-doc/blob/master/rest_api.md#deep-paging-with-cursors

• 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.

• 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 315

def self.journals(ids: nil, query: nil, filter: nil, offset: nil,
  limit: nil, sample: nil, sort: nil, order: nil, facet: nil,
  works: false, options: nil, verbose: false,
  cursor: nil, cursor_max: 5000)

  RequestCursor.new('journals', ids, query, filter, offset,
    limit, sample, sort, order, facet, works, nil, options,
    verbose, cursor, cursor_max).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:

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

  Number of record to start at, from 1 to infinity.

• 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.

• 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), or published (publication date). 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) (defaults to: nil) —

  Include facet results. Default: false

• 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

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

  A query string

Returns:

• (Array) —

  An array of hashes

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

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, options, verbose).perform
end

.members(ids: nil, query: nil, filter: nil, offset: nil, limit: nil, sample: nil, sort: nil, order: nil, facet: nil, works: false, options: nil, verbose: false, cursor: nil, cursor_max: 5000) ⇒ 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]

Parameters:

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

  Number of record to start at, from 1 to infinity.

• 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.

• 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), or published (publication date). 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) (defaults to: nil) —

  Include facet results. Default: false

• 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 github.com/CrossRef/rest-api-doc/blob/master/rest_api.md#deep-paging-with-cursors

• 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.

• 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 191

def self.members(ids: nil, query: nil, filter: nil, offset: nil,
  limit: nil, sample: nil, sort: nil, order: nil, facet: nil,
  works: false, options: nil, verbose: false,
  cursor: nil, cursor_max: 5000)

  RequestCursor.new('members', ids, query, filter, offset,
    limit, sample, sort, order, facet, works, nil, options,
    verbose, cursor, cursor_max).perform
end

.prefixes(ids:, filter: nil, offset: nil, limit: nil, sample: nil, sort: nil, order: nil, facet: nil, works: false, options: nil, verbose: false, cursor: nil, cursor_max: 5000) ⇒ 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]

Parameters:

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

  Number of record to start at, from 1 to infinity.

• 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.

• 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), or published (publication date). 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) (defaults to: nil) —

  Include facet results. Default: false

• 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 github.com/CrossRef/rest-api-doc/blob/master/rest_api.md#deep-paging-with-cursors

• 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.

• 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 229

def self.prefixes(ids:, filter: nil, offset: nil,
  limit: nil, sample: nil, sort: nil, order: nil, facet: nil,
  works: false, options: nil, verbose: false,
  cursor: nil, cursor_max: 5000)

  RequestCursor.new('prefixes', ids, nil, filter, offset,
    limit, sample, sort, order, facet, works, nil, options,
    verbose, cursor, cursor_max).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

• 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 409

def self.random_dois(sample: 10, options: nil, verbose: false)

  tmp = Request.new('works', nil, nil, nil, nil,
    nil, sample, 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 386

def self.registration_agency(ids:, options: nil, verbose: false)

  Request.new('works', ids, nil, nil, nil,
    nil, nil, nil, nil, nil, false, true, options, verbose).perform
end

.types(ids: nil, offset: nil, limit: nil, works: false, options: nil, verbose: false, cursor: nil, cursor_max: 5000) ⇒ 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]

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 github.com/CrossRef/rest-api-doc/blob/master/rest_api.md#deep-paging-with-cursors

• 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.

• 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

Returns:

• (Array) —

  An array of hashes

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

def self.types(ids: nil, offset: nil, limit: nil, works: false,
  options: nil, verbose: false, cursor: nil, cursor_max: 5000)

  RequestCursor.new('types', ids, nil, nil, offset,
    limit, nil, nil, nil, nil, works, nil, options,
    verbose, cursor, cursor_max).perform
end

.works(ids: nil, query: nil, filter: nil, offset: nil, limit: nil, sample: nil, sort: nil, order: nil, facet: nil, options: nil, verbose: false, cursor: nil, cursor_max: 5000) ⇒ 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'})

# 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)

# cursor for deep paging
Serrano.works(query: "widget", cursor: "*", limit: 100)
# 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]

Parameters:

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

  Number of record to start at, from 1 to infinity.

• 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.

• 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), or published (publication date). 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) (defaults to: nil) —

  Include facet results. Default: false

• 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 github.com/CrossRef/rest-api-doc/blob/master/rest_api.md#deep-paging-with-cursors

• 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.

• 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 145

def self.works(ids: nil, query: nil, filter: nil, offset: nil,
  limit: nil, sample: nil, sort: nil, order: nil, facet: nil,
  options: nil, verbose: false, cursor: nil, cursor_max: 5000)

  RequestCursor.new('works', ids, query, filter, offset,
    limit, sample, sort, order, facet, nil, nil, options,
    verbose, cursor, cursor_max).perform
end