Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
A simple Ruby wrapper to the Biodiversity Heritage Library API.
Ruby
Branch: master

Fetching latest commit…

Cannot retrieve the latest commit at this time

Failed to load latest commit information.
lib
spec
.env
.gitignore
.rspec
.ruby-version
Gemfile
Gemfile.lock
LICENSE
README.rdoc
Rakefile
rubyBHL.gemspec

README.rdoc

RubyBHL

A simple Ruby wrapper to version 2.5.x of the BHL API.

Really quick start

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":[]}

API Key

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.

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"]]
 # ... <clickity> R-stats </clickity>

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, and inspired the different architecture used now. Thanks BHL for being awesome!

License

Open, NCSA. See LICENSE.

Something went wrong with that request. Please try again.