{"id":26662834,"url":"https://github.com/speciesfilegroup/colrapi","last_synced_at":"2025-04-11T18:24:06.199Z","repository":{"id":44677162,"uuid":"450231152","full_name":"SpeciesFileGroup/colrapi","owner":"SpeciesFileGroup","description":"A low level Catalogue of Life/ChecklistBank Ruby API wrapper","archived":false,"fork":false,"pushed_at":"2025-04-01T22:03:20.000Z","size":196,"stargazers_count":2,"open_issues_count":0,"forks_count":1,"subscribers_count":4,"default_branch":"main","last_synced_at":"2025-04-11T18:23:14.388Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","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/SpeciesFileGroup.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2022-01-20T19:28:48.000Z","updated_at":"2025-04-01T22:03:16.000Z","dependencies_parsed_at":"2025-01-28T18:40:57.883Z","dependency_job_id":null,"html_url":"https://github.com/SpeciesFileGroup/colrapi","commit_stats":{"total_commits":68,"total_committers":3,"mean_commits":"22.666666666666668","dds":0.05882352941176472,"last_synced_commit":"c3f50c594cb4b1e08b9a487b34e67c534db0276e"},"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SpeciesFileGroup%2Fcolrapi","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SpeciesFileGroup%2Fcolrapi/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SpeciesFileGroup%2Fcolrapi/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SpeciesFileGroup%2Fcolrapi/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/SpeciesFileGroup","download_url":"https://codeload.github.com/SpeciesFileGroup/colrapi/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248456382,"owners_count":21106607,"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":[],"created_at":"2025-03-25T14:18:41.102Z","updated_at":"2025-04-11T18:24:06.164Z","avatar_url":"https://github.com/SpeciesFileGroup.png","language":"Ruby","funding_links":[],"categories":[],"sub_categories":[],"readme":"# colrapi\n\nThis is a wrapper on the Catalogue of Life API. Code follow the spirit/approach of the Gem [serrano](https://github.com/sckott/serrano), and indeed much of the wrapping utility is copied 1:1 from that repo, thanks [@sckott](https://github.com/sckott).\n\n## Installation\n\nAdd this line to your application's Gemfile:\n\n```ruby\ngem 'colrapi'\n```\n\nAnd then execute:\n\n    $ bundle install\n\nOr install it yourself as:\n\n    $ gem install colrapi\n\n\n## Documentation\n\nMost of the [ChecklistBank/Catalogue of Life API](https://api.checklistbank.org) is wrapped by the Colrapi gem, but not everything is documented yet. Looking through the [tests](https://github.com/SpeciesFileGroup/colrapi/tree/main/test) is a good way to see examples and learn how to use the Ruby gem. If you need something documented, please [open an issue](https://github.com/SpeciesFileGroup/colrapi/issues/new) ticket.\n\nThe Colrapi Ruby gem uses dataset_id to access information scoped within a dataset. There are [4 types of datasets](https://api.checklistbank.org/vocab/datasetorigin) in ChecklistBank: `external`, `project`, `release`, and `xrelease`. Most datasets are `external`, maintained outside of ChecklistBank and imported. A `project` is a draft version of a dataset assembled inside ChecklistBank from `external` datasets (e.g., [Catalogue of Life](https://www.checklistbank.org/dataset/3/about)). A `release` is a published dataset released from a `project` (e.g., [Catalogue of Life 2024 Annual Checklist](https://www.checklistbank.org/dataset/COL24/about)). An `xrelease` is a published dataset in which automated tools were used to extend a `release` dataset with additional information to fill in data gaps and have less editorial scrutiny. For example, this can mean that a very carefully scrutinized `external` dataset can be assembled into a project, published with some editorial decisions as a `release` and also extended to include missing names that a taxonomic expert might have deliberately excluded from their taxonomic database for various reasons in an `xrelease`. `xrelease` datasets aim to meet the use case of being able to attach occurrences and other data to a (nearly) complete list of scientific names. If you want the more expert scrutinized version of COL, then use a `release`. If you want to attach data to a complete list of scientific names and are less concerned about taxonomic scrutiny, then use an `xrelease`. (There may be no public COL `xrelease` datasets yet as the feature is currently under development.)\n\nCatalogue of Life has dataset_id=3, but you should almost never use dataset_id=3 because it is a draft unreleased version of COL and can have errors while the releases are being produced. Instead use 3LR to get the COL latest release, or 3LXR to get the COL latest extended release. COL releases new editions each month and the monthly releases are eventually deleted. If you need stable data that will be persistently accessible, then use the dataset_id=COLYY, where YY is the Annual Checklist year (e.g. COL24 to get the 2024 Annual Checklist). COL aims to keep the annual checklists permanently accessible, but the best practice is to download a copy of the data and archive it permanently with any research papers that use COL. Download a copy here, replacing {dataset_id} with the dataset_id: https://www.checklistbank.org/dataset/{dataset_id}/download\n\n### Dataset\n\nGet a list of external datasets in ChecklistBank:\n```ruby\nColrapi.dataset(origin: 'external')\n```\n\n#### [/dataset](http://api.checklistbank.org/#/default/search)\nGet a list of projects in ChecklistBank:\n```ruby\nColrapi.dataset(origin: 'project')\n```\n\nGet a list of releases in ChecklistBank released from Catalogue of Life:\n```ruby\nColrapi.dataset(origin: 'release', released_from: 3)\n```\n\nGet a list of xreleases in ChecklistBank released from Catalogue of Life:\n```ruby\nColrapi.dataset(origin: 'xrelease', released_from: 3)\n```\n\nGet a list of datasets that contribute to Catalogue of Life:\n```ruby\nColrapi.dataset(contributes_to: 3)\n```\n\nGet a list of datasets under a specific [license](https://api.checklistbank.org/vocab/license):\n```ruby\nColrapi.dataset(license: 'cc by')\n```\n\n### Names\n\n\n\n\n### Metadata\n\nGet metadata by dataset_id:\n```ruby\nColrapi.dataset(dataset_id: 'COL24')\n```\n\n\n### Name usage search\n\nThere are a two ways to conduct name usage search in ChecklistBank/Catalogue of Life: 1) using Elasticsearch or 2) querying PostgreSQL directly. Elasticsearch offers more advanced search functionality and parameters while PostgreSQL might perform faster.\n\n#### 1) Elasticsearch \n##### [/nameusage/search](http://api.checklistbank.org/#/default/search_4) or [/dataset/{dataset_id}/nameusage/search](http://api.checklistbank.org/#/default/searchDataset)\n\nElasticsearch all of ChecklistBank:\n```ruby\nColrapi.nameusage_search(q: 'Homo sapiens') #  =\u003e MultiJson object\n```\n\nElasticsearch the Catalogue of Life latest release:\n```ruby\nColrapi.nameusage_search(dataset_id: '3LR', q: 'Homo sapiens') #  =\u003e MultiJson object\n```\n\nElasticsearch the Catalogue of Life 2024 Annual Checklist:\n```ruby\nColrapi.nameusage_search(dataset_id: 'COL24', q: 'Homo sapiens') #  =\u003e MultiJson object\n```\n\nElasticsearch Orthoptera Species File:\n```ruby\nColrapi.nameusage_search(dataset_id: 1021, q: 'Cyphoderris strepitans') #  =\u003e MultiJson object\n```\n\n#### 2) PostgreSQL Search\n##### [/dataset/{dataset_id}/nameusage](https://api.checklistbank.org/#/default/list_3)\nQuery PostgreSQL directly for *Homo sapiens* in the Catalogue of Life latest release:\n```ruby\nColrapi.nameusage('3LR', q: 'Homo sapiens') #  =\u003e MultiJson object\n```\n\nQuery PostgreSQL directly for *Homo sapiens* in the Catalogue of Life 2024 Annual Checklist:\n```ruby\nColrapi.nameusage('COL24', q: 'Homo sapiens') #  =\u003e MultiJson object\n```\n\nQuery PostgreSQL directly for *Cyphoderris strepitans* in Orthoptera Species File\n```ruby\nColrapi.nameusage(1021, q: 'Cyphoderris strepitans') #  =\u003e MultiJson object\n```\n\n## Taxon\nGet a taxon from the Catalogue of Life latest release by taxon ID:\n```ruby\nColrapi.taxon('3LR', taxon_id: 'BHC3') #  =\u003e MultiJson object\n```\n\nGet the higher classification for a taxon from the Catalogue of Life latest release by taxon ID:\n```ruby\nColrapi.taxon('3LR', taxon_id: 'BHC3', subresource: 'classification') #  =\u003e MultiJson object\n```\n\nGet the distribution for a taxon from the Catalogue of Life latest release by taxon ID:\n```ruby\nColrapi.taxon('3LR', taxon_id: 'BHC3', subresource: 'distribution') #  =\u003e MultiJson object\n```\n\nGet additional info about a taxon from the Catalogue of Life latest release by taxon ID:\n```ruby\nColrapi.taxon('3LR', taxon_id: 'BHC3', subresource: 'info') #  =\u003e MultiJson object\n```\n\nGet species interactions for a taxon from 3i World Auchenorrhyncha Database by taxon ID:\n```ruby\nColrapi.taxon(2317, taxon_id: 28472, subresource: 'interaction') #  =\u003e MultiJson object\n```\n\nGet media for a taxon from WoRMS World Porifera Database by taxon ID:\n```ruby\nColrapi.taxon(1044, taxon_id: 'urn:lsid:marinespecies.org:taxname:166055', subresource: 'media') #  =\u003e MultiJson object\n```\n\nGet a source information from the Catalogue of Life latest release by taxon ID:\n```ruby\nColrapi.taxon('3LR', taxon_id: 'BHC3', subresource: 'source') #  =\u003e MultiJson object\n```\n\nGet synonyms from the Catalogue of Life latest release by taxon ID:\n```ruby\nColrapi.taxon('3LR', taxon_id: 'BHC3', subresource: 'synonyms') #  =\u003e MultiJson object\n```\n\nGet a taxonomic treatment from a Plazi dataset by taxon ID:\n```ruby\nColrapi.taxon('49590', taxon_id: '03D087F29465E83AFCF39B19FA20FC96.taxon', subresource: 'treatment') #  =\u003e MultiJson object\n```\n\nGet vernacular names from the Catalogue of Life latest release by taxon ID:\n```ruby\nColrapi.taxon('3LR', taxon_id: 'BHC3', subresource: 'vernacular') #  =\u003e MultiJson object\n```\n\n## Development\n\nAfter checking out the repo, run `bin/setup` to install dependencies. Then, run `rake test` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.\n\nTo install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, update the `CHANGELOG.md`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).\n\n## Contributing\n\nBug reports and pull requests are welcome on GitHub at https://github.com/mjy/colrapi. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](https://github.com/species_file_group/colrapi/blob/main/CODE_OF_CONDUCT.md).\n\n## License\n\nThe gem is available as open source under the terms of the [MIT](https://opensource.org/licenses/MIT) license.\n\n## Code of Conduct\n\nEveryone interacting in the Colrapi project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/species_file_group/colrapi/blob/main/CODE_OF_CONDUCT.md).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fspeciesfilegroup%2Fcolrapi","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fspeciesfilegroup%2Fcolrapi","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fspeciesfilegroup%2Fcolrapi/lists"}