{"id":15555300,"url":"https://github.com/sckott/serrano","last_synced_at":"2025-04-14T10:20:34.558Z","repository":{"id":2014470,"uuid":"42087785","full_name":"sckott/serrano","owner":"sckott","description":"Low level Ruby client for Crossref","archived":false,"fork":false,"pushed_at":"2023-02-02T04:00:36.000Z","size":2026,"stargazers_count":31,"open_issues_count":1,"forks_count":3,"subscribers_count":8,"default_branch":"main","last_synced_at":"2025-04-10T06:02:10.661Z","etag":null,"topics":["api","crossref-api","doi","metadata"],"latest_commit_sha":null,"homepage":"https://rubydoc.info/gems/serrano","language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/sckott.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2015-09-08T03:24:52.000Z","updated_at":"2024-07-31T12:13:10.000Z","dependencies_parsed_at":"2023-02-18T04:00:35.910Z","dependency_job_id":null,"html_url":"https://github.com/sckott/serrano","commit_stats":null,"previous_names":[],"tags_count":16,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sckott%2Fserrano","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sckott%2Fserrano/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sckott%2Fserrano/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sckott%2Fserrano/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/sckott","download_url":"https://codeload.github.com/sckott/serrano/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248860007,"owners_count":21173342,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["api","crossref-api","doi","metadata"],"created_at":"2024-10-02T15:08:08.441Z","updated_at":"2025-04-14T10:20:34.532Z","avatar_url":"https://github.com/sckott.png","language":"Ruby","funding_links":[],"categories":[],"sub_categories":[],"readme":"serrano\n=========\n\n[![gem version](https://img.shields.io/gem/v/serrano.svg)](https://rubygems.org/gems/serrano)\n[![Ruby](https://github.com/sckott/serrano/workflows/Ruby/badge.svg)](https://github.com/sckott/serrano/actions)\n[![codecov.io](https://codecov.io/github/sckott/serrano/coverage.svg?branch=main)](https://codecov.io/github/sckott/serrano?branch=main)\n[![DOI](https://zenodo.org/badge/2600/sckott/serrano.svg)](https://zenodo.org/badge/latestdoi/2600/sckott/serrano)\n[![Ruby Style Guide](https://img.shields.io/badge/code_style-standard-brightgreen.svg)](https://github.com/testdouble/standard)\n\n`serrano` is a low level client for Crossref APIs\n\nDocs: https://www.rubydoc.info/gems/serrano\n\nOther Crossref API clients:\n\n- Python: [habanero](https://github.com/sckott/habanero)\n- R: [rcrossref](https://github.com/ropensci/rcrossref)\n\nCrossref's API issue tracker: https://gitlab.com/crossref/issues\n\n## Changes\n\nFor changes see the [Changelog][changelog]\n\n## API\n\nMethods in relation to [Crossref search API][crapi] routes\n\n* `/works` - `Serrano.works()`\n* `/members` - `Serrano.members()`\n* `/prefixes` - `Serrano.prefixes()`\n* `/funders` - `Serrano.funders()`\n* `/journals` - `Serrano.journals()`\n* `/licenses` - `Serrano.licenses()`\n* `/types` - `Serrano.types()`\n\nAdditional methods built on top of the Crossref search API:\n\n* DOI minting agency - `Serrano.registration_agency()`\n* Get random DOIs - `Serrano.random_dois()`\n\nOther methods:\n\n* [Conent negotiation][cn] - `Serrano.content_negotiation()`\n* [Citation count][ccount] - `Serrano.citation_count()`\n* [get CSL styles][csl] -  `Serrano.csl_styles()`\n\nNote about searching:\n\nYou are using the Crossref search API described at https://api.crossref.org When you search with query terms, on Crossref servers they are not searching full text, or even abstracts of articles, but only what is available in the data that is returned to you. That is, they search article titles, authors, etc. For some discussion on this, see https://gitlab.com/crossref/issues/issues/101\n\nRate limits:\n\nCrossref introduced rate limiting recently. The rate limits apparently vary,\nso we can't give a predictable rate limit. As of this writing, the rate\nlimit is 50 requests per second. Look for the headers `X-Rate-Limit-Limit`\nand `X-Rate-Limit-Interval` in requests to see what the current rate\nlimits are.\n\nThe Polite Pool:\n\nTo get in the polite pool it's a good idea now to include a `mailto` email\naddress. See docs for more information. TLDR: set your email in an env var `CROSSREF_EMAIL`.\n\n\nURL Encoding:\n\nWe do URL encoding of DOIs for you for all methods except `Serrano.citation_count` which doesn't work if you encode DOIs beforehand. We use `ERB::Util.url_encode` to encode.\n\n\n## Install\n\n### Release version\n\n```\ngem install serrano\n```\n\n### Development version\n\n```\ngit clone git@github.com:sckott/serrano.git\ncd serrano\nrake install\n```\n\n## Setup\n\nCrossref's API will likely be used by others in the future, allowing the base URL to be swapped out. You can swap out the base URL by passing named options in a block to `Serrano.configuration`.\n\nThis will also be the way to set up other user options, as needed down the road.\n\n```ruby\nSerrano.configuration do |config|\n  config.base_url = \"https://api.crossref.org\"\nend\n```\n\nWe recommend you set your `mailto` email here so you can get in the \"polite pool\" which gives you faster rate limits:\n\n```ruby\nSerrano.configuration do |config|\n  config.mailto = \"jane@doe.org\"\nend\n```\n\nOr use an env var with name `CROSSREF_EMAIL`\n\n## Examples\n\n### Use in a Ruby repl\n\nSearch works by DOI\n\n```ruby\nrequire 'serrano'\nSerrano.works(ids: '10.1371/journal.pone.0033693')\n```\n\nSearch works by query string\n\n```ruby\nSerrano.works(query: \"ecology\")\n```\n\nSearch works using metadata filters. See [CrossRef filter docs](https://github.com/CrossRef/rest-api-doc#filter-names).\n\n```ruby\nSerrano.works(query: \"ecology\", filter: { has_abstract: true })\n```\n\nSearch journals by publisher name\n\n```ruby\nSerrano.journals(query: \"peerj\")\n```\n\nSearch funding information by DOI\n\n```ruby\nSerrano.funders(ids: ['10.13039/100000001','10.13039/100000015'])\n```\n\nGet agency for a set of DOIs\n\n```ruby\nSerrano.registration_agency(ids: ['10.1007/12080.1874-1746','10.1007/10452.1573-5125'])\n```\n\nGet random set of DOIs\n\n```ruby\nSerrano.random_dois(sample: 100)\n```\n\nContent negotiation\n\n```ruby\nSerrano.content_negotiation(ids: '10.1126/science.169.3946.635', format: \"citeproc-json\")\n```\n\n### Use on the CLI\n\nThe command line tool `serrano` should be available after you install\n\n```\n~$ serrano\nCommands:\n  serrano contneg                   # Content negotiation\n  serrano funders [funder IDs]      # Search for funders by DOI prefix\n  serrano help [COMMAND]            # Describe available commands or one spec...\n  serrano journals [journal ISSNs]  # Search for journals by ISSNs\n  serrano licenses                  # Search for licenses by name\n  serrano members [member IDs]      # Get members by id\n  serrano prefixes [DOI prefixes]   # Search for prefixes by DOI prefix\n  serrano types [type name]         # Search for types by name\n  serrano version                   # Get serrano version\n  serrano works [DOIs]              # Get works by DOIs\n```\n\n```\n# A single DOI\n~$ serrano works 10.1371/journal.pone.0033693\n\n# Many DOIs\n~$ serrano works \"10.1007/12080.1874-1746,10.1007/10452.1573-5125\"\n## if above two dois in a file called dois.txt \n~$ cat dois.txt | xargs -I{} serrano works {}\n\n# output JSON, then parse with e.g., jq\n~$ serrano works --filter=has_orcid:true --json --limit=2 | jq '.message.items[].author[].ORCID | select(. != null)'\n```\n\n## Meta\n\n* Please note that this project is released with a [Contributor Code of Conduct](CONDUCT.md). By participating in this project you agree to abide by its terms.\n* License: MIT\n\n[crapi]: https://api.crossref.org/\n[cn]: https://citation.crosscite.org/docs.html\n[ccount]: https://www.crossref.org/documentation/retrieve-metadata/openurl/\n[csl]: https://github.com/citation-style-language/styles\n[changelog]: https://github.com/sckott/serrano/blob/main/CHANGELOG.md\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsckott%2Fserrano","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsckott%2Fserrano","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsckott%2Fserrano/lists"}