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 collapse

VERSION = 
"1.4"

Class Method Summary collapse

Methods included from Configuration

configuration, define_setting

Class Method Details

.assert_valid_filters(filters) ⇒ Object 



673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
 
# File 'lib/serrano.rb', line 673

def self.assert_valid_filters(filters)
  unless filters.is_a? Hash
    raise ArgumentError, <<~ERR
      Filters must be provided as a hash, like:

          Serrano.works(query: "something", filters: { has_abstract: true })
    ERR
  end

  filters.each do |name, _|
    filter_strings = Filters.names.map(&:to_s)
    next if filter_strings.include?(name.to_s)

    raise ArgumentError, <<~ERR
      The filter "#{name}" is not a valid filter. Please run `Serrano.filters.filters` to see all valid filters.
    ERR
  end
end

.citation_count(doi:, url: "https://www.crossref.org/openurl/", key: "[email protected]", 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: "[email protected]") —

    your API key

See Also:



651
652
653
654
655
656
657
658
659
660
661
 
# File 'lib/serrano.rb', line 651

def self.citation_count(doi:, url: "https://www.crossref.org/openurl/",
  key: "[email protected]", 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:



630
631
632
633
 
# File 'lib/serrano.rb', line 630

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:



669
670
671
 
# File 'lib/serrano.rb', line 669

def self.csl_styles
  fetch_styles
end

.filters ⇒ Object 



4
5
6
 
# 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



385
386
387
388
389
390
391
392
393
394
 
# File 'lib/serrano.rb', line 385

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



438
439
440
441
442
443
444
445
446
447
 
# File 'lib/serrano.rb', line 438

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



523
524
525
526
527
528
529
 
# File 'lib/serrano.rb', line 523

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



284
285
286
287
288
289
290
291
292
293
 
# File 'lib/serrano.rb', line 284

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



332
333
334
335
336
337
338
339
340
341
 
# File 'lib/serrano.rb', line 332

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



564
565
566
567
568
 
# File 'lib/serrano.rb', line 564

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



542
543
544
545
 
# File 'lib/serrano.rb', line 542

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



483
484
485
486
487
488
489
 
# File 'lib/serrano.rb', line 483

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



227
228
229
230
231
232
233
234
235
236
 
# 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