{"id":43223323,"url":"https://github.com/gnames/bhlnames","last_synced_at":"2026-02-01T09:16:12.240Z","repository":{"id":57504923,"uuid":"230794153","full_name":"gnames/bhlnames","owner":"gnames","description":"BHLnames finds nomenclatural events, adds taxonomic intelligence to Biodiversity Heritage Library","archived":false,"fork":false,"pushed_at":"2024-05-14T09:53:20.000Z","size":2266,"stargazers_count":1,"open_issues_count":2,"forks_count":0,"subscribers_count":5,"default_branch":"master","last_synced_at":"2024-06-11T18:23:11.473Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Go","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/gnames.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"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":"2019-12-29T19:27:55.000Z","updated_at":"2024-06-21T16:27:23.009Z","dependencies_parsed_at":"2024-03-18T22:24:33.895Z","dependency_job_id":"3474a235-5f04-47ee-9376-40b0f1ae9ade","html_url":"https://github.com/gnames/bhlnames","commit_stats":null,"previous_names":[],"tags_count":21,"template":false,"template_full_name":null,"purl":"pkg:github/gnames/bhlnames","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gnames%2Fbhlnames","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gnames%2Fbhlnames/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gnames%2Fbhlnames/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gnames%2Fbhlnames/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/gnames","download_url":"https://codeload.github.com/gnames/bhlnames/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gnames%2Fbhlnames/sbom","scorecard":{"id":431012,"data":{"date":"2025-08-11","repo":{"name":"github.com/gnames/bhlnames","commit":"9c25f7678da1c05da3548c856ef9552376507461"},"scorecard":{"version":"v5.2.1-40-gf6ed084d","commit":"f6ed084d17c9236477efd66e5b258b9d4cc7b389"},"score":1.6,"checks":[{"name":"Maintained","score":0,"reason":"0 commit(s) and 0 issue activity found in the last 90 days -- score normalized to 0","details":null,"documentation":{"short":"Determines if the project is \"actively maintained\".","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#maintained"}},{"name":"Packaging","score":-1,"reason":"packaging workflow not detected","details":["Warn: no GitHub/GitLab publishing workflow detected."],"documentation":{"short":"Determines if the project is published as a package that others can easily download, install, easily update, and uninstall.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#packaging"}},{"name":"Code-Review","score":0,"reason":"Found 0/30 approved changesets -- score normalized to 0","details":null,"documentation":{"short":"Determines if the project requires human code review before pull requests (aka merge requests) are merged.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#code-review"}},{"name":"SAST","score":0,"reason":"no SAST tool detected","details":["Warn: no pull requests merged into dev branch"],"documentation":{"short":"Determines if the project uses static code analysis.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#sast"}},{"name":"Dangerous-Workflow","score":-1,"reason":"no workflows found","details":null,"documentation":{"short":"Determines if the project's GitHub Action workflows avoid dangerous patterns.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#dangerous-workflow"}},{"name":"Binary-Artifacts","score":10,"reason":"no binaries found in the repo","details":null,"documentation":{"short":"Determines if the project has generated executable (binary) artifacts in the source repository.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#binary-artifacts"}},{"name":"Token-Permissions","score":-1,"reason":"No tokens found","details":null,"documentation":{"short":"Determines if the project's workflows follow the principle of least privilege.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#token-permissions"}},{"name":"CII-Best-Practices","score":0,"reason":"no effort to earn an OpenSSF best practices badge detected","details":null,"documentation":{"short":"Determines if the project has an OpenSSF (formerly CII) Best Practices Badge.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#cii-best-practices"}},{"name":"Security-Policy","score":0,"reason":"security policy file not detected","details":["Warn: no security policy file detected","Warn: no security file to analyze","Warn: no security file to analyze","Warn: no security file to analyze"],"documentation":{"short":"Determines if the project has published a security policy.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#security-policy"}},{"name":"Fuzzing","score":0,"reason":"project is not fuzzed","details":["Warn: no fuzzer integrations found"],"documentation":{"short":"Determines if the project uses fuzzing.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#fuzzing"}},{"name":"License","score":10,"reason":"license file detected","details":["Info: project has a license file: LICENSE:0","Info: FSF or OSI recognized license: MIT License: LICENSE:0"],"documentation":{"short":"Determines if the project has defined a license.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#license"}},{"name":"Pinned-Dependencies","score":0,"reason":"dependency not pinned by hash detected -- score normalized to 0","details":["Warn: containerImage not pinned by hash: Dockerfile:1: pin your Docker image by updating alpine:3.18 to alpine:3.18@sha256:de0eb0b3f2a47ba1eb89389859a9bd88b28e82f5826b6969ad604979713c2d4f","Info:   0 out of   1 containerImage dependencies pinned"],"documentation":{"short":"Determines if the project has declared and pinned the dependencies of its build process.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#pinned-dependencies"}},{"name":"Signed-Releases","score":0,"reason":"Project has not signed or included provenance with any releases.","details":["Warn: release artifact v0.0.5 not signed: https://api.github.com/repos/gnames/bhlnames/releases/23877919","Warn: release artifact v0.0.4 not signed: https://api.github.com/repos/gnames/bhlnames/releases/23465984","Warn: release artifact v0.0.3 not signed: https://api.github.com/repos/gnames/bhlnames/releases/23136752","Warn: release artifact v0.0.5 does not have provenance: https://api.github.com/repos/gnames/bhlnames/releases/23877919","Warn: release artifact v0.0.4 does not have provenance: https://api.github.com/repos/gnames/bhlnames/releases/23465984","Warn: release artifact v0.0.3 does not have provenance: https://api.github.com/repos/gnames/bhlnames/releases/23136752"],"documentation":{"short":"Determines if the project cryptographically signs release artifacts.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#signed-releases"}},{"name":"Branch-Protection","score":0,"reason":"branch protection not enabled on development/release branches","details":["Warn: branch protection not enabled for branch 'master'"],"documentation":{"short":"Determines if the default and release branches are protected with GitHub's branch protection settings.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#branch-protection"}},{"name":"Vulnerabilities","score":2,"reason":"8 existing vulnerabilities detected","details":["Warn: Project is vulnerable to: GO-2025-3553 / GHSA-mh63-6h87-95cp","Warn: Project is vulnerable to: GO-2024-3321 / GHSA-v778-237x-gjrc","Warn: Project is vulnerable to: GO-2025-3487 / GHSA-hcg3-q754-cr77","Warn: Project is vulnerable to: GO-2024-3333","Warn: Project is vulnerable to: GO-2025-3503 / GHSA-qxp5-gwg8-xv66","Warn: Project is vulnerable to: GO-2025-3595 / GHSA-vvgc-356p-c3xw","Warn: Project is vulnerable to: GO-2024-2687 / GHSA-4v7x-pqxf-cx7m","Warn: Project is vulnerable to: GO-2024-2611 / GHSA-8r3f-844c-mc37"],"documentation":{"short":"Determines if the project has open, known unfixed vulnerabilities.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#vulnerabilities"}}]},"last_synced_at":"2025-08-19T03:21:04.819Z","repository_id":57504923,"created_at":"2025-08-19T03:21:04.819Z","updated_at":"2025-08-19T03:21:04.819Z"},"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28974544,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-01T08:16:14.655Z","status":"ssl_error","status_checked_at":"2026-02-01T08:06:51.373Z","response_time":56,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"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":"2026-02-01T09:16:11.334Z","updated_at":"2026-02-01T09:16:12.230Z","avatar_url":"https://github.com/gnames.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# bhlnames\n\n[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.14262195.svg)](https://doi.org/10.5281/zenodo.14262195)\n\nBHLnames takes one or more scientific names and finds their occurrences in\nBiodiversity Heritage Library (BHL). The app also creates an apparent link\nbetween a name-string/publication input and the corresponding BHL reference.\nIt can be used to find nomenclatural events in BHL by a name and a citation.\n\n## Introduction\n\n[Biodiversity Heritage Library (BHL)][bhl] contains more than 250 000 volumes\n(books, scientific journals, diaries of explorers, etc.). BHL provides an\nimportant biodiversity information. Since the middle of 18th century,\nscientists use Latinized scientific names as identifiers for known species. For\nbiologists, it is crucial to get information about species in publications,\nit is especially valuable to find original description of species or creation\nof a new binomial genus/species combination.\n\nThis program tries to answer the following questions:\n\n- Where a particular name-string appears in BHL?\n\n- Given a names string, where species it assigned to appears in BHL? In this\n  case we find all synonyms of the name-string and the currently accepted\n  name of the species\n\n- Given a name-string and a reference to its original publication, does this\n  publication exists in BHL, and what is the link to it?\n\n- Given a name-string and a reference to a publication about the name-string,\n  find a link to this publication in BHL.\n\nThe `bhlnames` app uses [Catalogue Of Life (CoL)][col] synonymy information to\nfind publications not only about a given name but also about its synonyms. In\nthe future it will support other resources with synonymy information.\n\n## Provided functionalities\n\n1. Find references in BHL where a scientific name-string appears.\n\n   Searching for a name-string without synonyms.\n\n2. Find references in BHL where a taxon, represented by a name-string appears.\n\n   Determining the corresponding taxon an entered name-string. This taxon\n   has a currently accepted name and a variety of synonym name-strings.\n   Entered name-string might match either a synonym, or the currently accepted\n   name. Searching for references where any of the found name-strings\n   appear.\n\n3. Find a reference to the original description of a name or a new combination.\n\n   In this case the input is a nomenclatural event represented by a name and\n   its official nomenclatural publication. We use provided information trying\n   to find a BHL reference that corresponds to that publication.\n\n4. Find a link to a publication, using a publication reference and\n   a name used in the publication.\n\n5. Provide REST API and command line tool to access aforementioned\n   functionalities.\n\n## Prerequisites\n\nTo be able to use this program you need\n\n- a modern computer (laptop or desktop)\n- one of the 3 operating systems (Linux, Mac OS, Windows)\n- a PostgreSQL database\n- 30+ GB of space on a hard drive\n- 32GB or more of memory\n\n## Installation\n\n1. Download the [latest release] of `bhlnames`, untar or unzip the executable\n   `bhlnames` or `bhlnames.exe` and place it somewhere in your PATH.\n\n2. Create a database (default name is `bhlnames`) on your Postgresql server. We\n   are not covering how to use Postgresql in this document. There are many\n   tutorials about it on the web. Make sure that the database is accessible\n   from the computer where you installed `bhlnames` executable.\n\n3. Run `bhlnames -V`. It will show the version number of the program and will\n   create a configuration file. Terminal output will provide information where\n   the file is located. For example on Linux machines it will be placed in\n   `$HOME/.config/bhlnames.yaml`.\n\n4. Go to the configuration file and modify database parameters in the config.\n   You can also change setup for `InputDir` directory for downloaded and\n   temporary files, as well as for key-value store databases. You can leave\n   other parameters as is for now.\n\nThe system should be ready for the initialization step.\n\n## Initialization\n\nThis step downloads all the needed BHL and names metadata on your computer.\nSome of the data go to the Postgresql database, others to a key-value store.\nYou do not need to worry about the creation of tables, or key-value databases;\nthey will be populated automatically. The program uses a file containing\nmetadata dump from BHL, as well as names data created by `bhlindex`. Dump\nprovides information about papers (parts in BHL terminology), volumes (issues),\nand books/journal volume sets (titles). The `bhlindex` provides fresh\ninformation about names and their occurrences in BHL.\n\nTo start the initialization process type:\n\n```bash\nbhlnames init\n```\n\nThe whole process will take about 1-2 hours, but it could take significantly\nlonger if your computer or internet connection are slow.\n\nIf for some reason you have to restart the program, you do not need to delete\nworking directories or the database. All of them will be updated automatically.\nSome slow steps will not be repeated (such as downloading full dump of BHL\ndatabase), unless you use `-r` option during initialization:\n\n```bash\nbhlnames init -r\n```\n\nIn this case, everything will start from the beginning. In case if you\ndownloaded a newer version of `bhlnames` instead of older ones, you might need\nto drop the database and create it again, and do init from scratch. Note that\nthe BHL dump is updated regularly, and it is good to rebuild your metadata set\nfrom time to time from scratch.\n\n## Usage\n\nTo find references to a whole taxon (synonyms and currently accepted name)\nfrom a name-string:\n\n```bash\nbhlnames name \"Pardosa moesta\"\n```\n\nThe result (in JSON format) will be sent to `STDOUT` and can be redirected to a\nfile\n\n```bash\nbhlnames name \"Pardosa moesta\" \u003e pm.json\n```\n\nBy default, JSON is returned in its compact form. Optionally you can get data in\na more human-readable form with:\n\n```bash\nbhlnames name \"Pardosa moesta\" -f pretty\n```\n\nYou can also use [jq] or a similar tool\n\n```bash\nbhlnames name \"Pardosa moesta\" 2\u003e/dev/null | jq\n```\n\nIn case if it is preferable to have the oldest publications last,\nyou can reverse sorting order with:\n\n```bash\nbhlnames name \"Pardosa moesta\" -f pretty -d\n```\n\nTo search for a large collection of names provide the name of a file instead\n(one name per line):\n\n```bash\nbhlnames name names.txt\n```\n\nFor computers with modern multi-core CPU, you can increase number of parallel\njobs. Usually, there is no much gain from setting more than 8 jobs.\n\n```bash\nbhlnames name names.txt -j 8\n```\n\nTo get a short version of data without details for references:\n\n```bash\nbhlnames name names.txt -s\n```\n\nTo get results without synonyms:\n\n```bash\nbhlnames name names.txt --no_synonyms\n```\n\nTo find a link to a name-string with its original reference you can use a\nCSV.\n\nMinimal fields are:\n\n```csv\nId,NameString,RefString\n```\n\nWhere `Id` is an internal identifier, `NameString` is a full scientific name\nwith authorship and year (if they are given), `RefString` is an unparsed\nreference string.\n\nIf you have a more detailed information the following fields can also be used:\n\n`NameCanonical` canonical form of a name, `NameYear` the year of the name\npublication, `RefYear` the year of the reference publication.\n\nMost\n\nYou can use the following command:\n\n```bash\nbhlnames nomen name-refs.csv\n```\n\nThe result will be send to `STDOUT` in a compact JSON format, one datum per\nline. Use [jq] or similar program to render 'pretty' version of JSON.\n\nOn a 12-core laptop, processing of 10000 names took about 40 seconds with 8\nparallel jobs, and 2m 45sec with a single job. 10000 names generated 120MB of\nresults.\n\nWhen you find the optimal number of jobs for your computer you can modify\n`JobsNum` parameter in your version of the [`bhlnames.yaml`][config] file\naccordingly.\n\n## REST API\n\nTo start `bhlnames` as a server on a port 1234:\n\n```bash\nbhlnames rest -p 1234\n```\n\n### REST end-points\n\n- `/name_refs` (POST) to find occurrences of a names-string. Takes JSON encoded\n  list of name-strings as an argument.\n\n- `/taxon_refs` (POST) to find occurrences of a taxon. Takes JSON encoded list\n  of name-strings as an argument.\n\n- `/nomen_refs` (POST) to find a link to the provided reference.\n  Takes a JSON-encoded structure.\n\nFor more details how to use API you can refer to the [REST test file].\n\n## Explanation of received data\n\n### Taxon and name-string output\n\nThis output is created by `bhlnames name` command.\n\nReturning information can be quite large. You will get data in chronological\norder. If there is data about a specific paper, we return information about\nthe paper; if we only have information about the item, or title, we return that\ninformation.\n\nFor every item, we return the most populated Linnean kingdom for the\nunique names found in the item. We also provide the percentage of names that\ngot resolved to that kingdom. We use the managerial CoL classification for this\npurpose.\n\nIn addition, we return a \"context\" of the item. The context is the lowest taxon\nthat still contains at least 50% of all names found in the item. This gives a\nbetter idea about the item's biological content. For example, if the context is\n\"Araneae\" the item is mostly about spiders.\n\nYou can use provided `page_id` and `item_id` to find information on BHL\nwebsite. For example to find `page_id` 26895127 use:\n\n`https://www.biodiversitylibrary.org/page/26895127`\n\n### Original reference output\n\nThis output is created by `bhlnames nomen` command.\n\nYou receive input information (id, name, reference) as well as 0 or 1 reference\nfrom BHL that was the picked as the best candidate to the link for the\ninput reference. If we did not get any feasible candidates, no BHL reference\nis provided.\n\nTODO: Explain score and score thresholds.\n\n## Development\n\n### Running tests\n\n1. Install `direnv`, copy `envrc.example` to `.envrc`.\n2. Modify `.envrc` according to your needs, enable `direnv`.\n3. Install bhlnames as described above.\n4. Use [bhlnames test database] for data.\n5. in `./internal/io/restio/restio.go` go to TODO and swap development\n   and production servers. (Dont forget to swap them back for production)\n6. Start RESTful service in another terminal window:\n\n   ```bash\n   bhlnames rest\n   ```\n\n7. Run `make tools`\n8. Run `make test`\n9. Run `make testrest`\n\n## Authors\n\n- [Dmitry Mozzherin]\n- [Geoff Ower]\n\n## License\n\nReleased under [MIT license]\n\n[bhl]: https://www.biodiversitylibrary.org/\n[col]: https://www.catalogueoflife.org/col/\n[latest release]: https://github.com/gnames/bhlnames/releases/latest\n[config]: https://raw.githubusercontent.com/gnames/bhlnames/master/config_example/.bhlnames.yaml\n[jq]: https://github.com/stedolan/jq\n[dmitry mozzherin]: https://github.com/dimus\n[geoff ower]: https://github.com/gdower\n[mit license]: https://github.com/gnames/bhlnames/blob/master/LICENSE\n[rest test file]: https://github.com/gnames/bhlnames/blob/master/rest/rest_test.go\n[bhlnames test database]: http://opendata.globalnames.org/bhlnames/bhlnames-postgres-2024-05-07.zst\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgnames%2Fbhlnames","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgnames%2Fbhlnames","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgnames%2Fbhlnames/lists"}