A simple Ruby wrapper to version 3.x of the BHL API.
Add your key (www.biodiversitylibrary.org/getapikey.aspx) to ~/.bhl_api_key.
gem install rubyBHL require 'rubyBHL' RubyBHL.quick_request() # => {"Status":"ok","ErrorMessage":null,"Result":[]}
You need a BHL key from 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.
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() # => #<RubyBHL::Request:0x0000010189bf28
@api_key="redacted_secret_key",
@method=:NameSearch, @format="json", @params={}>
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 # => #<RubyBHL::Response: ... >
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"=>[]}
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"]]
# ... <clickity> R-stats </clickity>
Fork the repo, hack, test, submit a pull request.
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, and inspired the different architecture used now. Thanks BHL for being awesome!
Open, NCSA. See LICENSE.