RubyBHL¶ ↑

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.