rubyBHL

= 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() # => #<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: ... >

== 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.