https://github.com/speciesfilegroup/rubybhl
A simple Ruby wrapper to the Biodiversity Heritage Library API.
https://github.com/speciesfilegroup/rubybhl
Last synced: over 1 year ago
JSON representation
A simple Ruby wrapper to the Biodiversity Heritage Library API.
- Host: GitHub
- URL: https://github.com/speciesfilegroup/rubybhl
- Owner: SpeciesFileGroup
- License: other
- Created: 2009-10-19T21:46:03.000Z (almost 17 years ago)
- Default Branch: master
- Last Pushed: 2020-07-28T03:55:28.000Z (about 6 years ago)
- Last Synced: 2025-04-11T18:24:00.372Z (over 1 year ago)
- Language: Ruby
- Homepage:
- Size: 42 KB
- Stars: 7
- Watchers: 5
- Forks: 2
- Open Issues: 1
-
Metadata Files:
- Readme: README.rdoc
- License: LICENSE
Awesome Lists containing this project
README
= RubyBHL
A simple Ruby wrapper to {version 3.x of the BHL API}[https://www.biodiversitylibrary.org/docs/api3.html].
== Really quick start
Add your key (http://www.biodiversitylibrary.org/getapikey.aspx) to ~/.bhl_api_key.
gem install rubyBHL
require 'rubyBHL'
RubyBHL.quick_request() # => {"Status":"ok","ErrorMessage":null,"Result":[]}
== API Key
You need a BHL key from http://www.biodiversitylibrary.org/getapikey.aspx. Do one of:
1) Add it to the file ~/.bhl_api_key.
2) Add it to the file _.env_ in the root of your application:
BHL_API_KEY=sekret_key_here
3) Set BHL_API_KEY in your shell profile.
4) Pass it explicitly to your request:
RubyBHL::Request.new(api_key: '123_343_etc')
If the key is set in multiple places priority is reverse order listed here.
== Requests
Construct one all at once:
r = RubyBHL::Request.new(method: :TitleSearch, params: {'title' => 'Dark and Storm Night'}, format: 'xml', api_key: 'top_sekret_key')
Build it piece by piece if you need to
r = RubyBHL::Request.new() # => #
The method defaults to :NameSearch
r.method # => :NameSearch
r.method = :TitleSearchSimple # => :TitleSearchSimple
Parameters are passed as a hash, keys are strings:
r.params = {'title' => 'Hen in the Foxhouse.'} # => {"title"=>"Hen in the Foxhouse."}
Format is one of `xml` or `json` (default):
r.format = 'xml' # => "xml"
It's possible to set your API key per request:
r.api_key = 'top_sekret_key' # => "top_sekret_key"
Test that your params are supported:
r.params = {'foo' => 'bar'} # => {"foo"=>"bar"}
r.params_are_supported? # => false
Test that method has the required params?
r.params = {} # => {}
r.method = :NameSearch # => :NameSearch
r.has_required_params? # false => false
r.params = {'name' => "Yeti"} # => {"name"=>"Yeti"}
r.has_required_params? # => true
Test the overall validity of the present request:
r.valid? # => true
Return the search_url:
r.search_url # => "http://www.biodiversitylibrary.org/api2/httpquery.ashx?op=NameSearch&name=Yeti&format=xml&apikey=top_sekret_key"
Get a response
r.response # => #
== Responses
Require a RubyBHL::Request:
request = RubyBHL::Request.new(params: {'name' => 'blorf'})
response = RubyBHL::Response.new(request: request)
Get the json:
response.json # => {"Status"=>"ok", "ErrorMessage"=>nil, "Result"=>[]}
== Mining
Just some examples at present.
For a taxon name, and a list of "attributes", generate a CSV table with one page per row, and 0 (absent) or 1 (present) for each "attribute". You can limit the number of pages returned.
require 'rubyBHL'
r = RubyBHL::Mine.taxon_attribute_table('Apis melifera', ['honey', 'disease', 'parasite'], 5)
# => "honey\tdisease\tparasite\tPageID\n0\t0\t0\t15995011\n0\t0\t0\t16445239\n0\t0\t0\t27274823\n0\t0\t0\t18188723\n0\t0\t0\t37765472\n1\t0\t0\t34216230\n1\t0\t1\t31898980\n0\t0\t1\t32014594\n0\t0\t0\t32014638\n1\t1\t0\t32015159\n"
CSV.parse(r, col_sep: "\t")
# => [["honey", "disease", "parasite", "PageID"],
["0", "0", "0", "15995011"],
["0", "0", "0", "16445239"],
["0", "0", "0", "27274823"],
["0", "0", "0", "18188723"],
["0", "0", "0", "37765472"],
["1", "0", "0", "34216230"],
["1", "0", "1", "31898980"],
["0", "0", "1", "32014594"],
["0", "0", "0", "32014638"],
["1", "1", "0", "32015159"]]
# ... R-stats
== Contributing
Fork the repo, hack, test, submit a pull request.
== Acknowledgements
Katja Seltmann provided code and requirements for the original incarnation of the gem. The general pattern for this gem, including some baseline tests, is pilfered from dwc-archive by Dmitry Mozzherin. Mx A. Matienzo (@anarchivist) wrote a {Python translation of the original version}[http://www.biodiversitylibrary.org/api2/docs/docs.html], and inspired the different architecture used now. Thanks BHL for being awesome!
== License
Open, NCSA[http://opensource.org/licenses/NCSA]. See LICENSE.