module Eol
The Eol
namespace holds all methods and classes that interact with the Encyclopedia of Life API.
Constants
- VERSION
Public Class Methods
Given the identifier for a collection this API will return all metadata about the collection and the items it contains.
@see eol.org/api/docs/collections @param [Integer] id any integer @param [Hash] query_options @option query_options [Integer] :page (1) fetches page of results @option query_options [0-500] :per_page (50) sets number of results per page @option query_options [articles, collections, communities, images, sounds,
taxa, users, video] :filter filters search results
@option query_options [recently_added, oldest, alphabetical,
reverse_alphabetical, richness, rating, sort_field, reverse_sort_field] :sort_by (recently_added) sorts results
@option query_options [String] :sort_field If a sort_field parameter is
included, only collection items whose sort field exactly matches the given string will be returned
@option query_options [Integer] :cache_ttl the number of seconds you wish to
have the response cached
@option query_options [ms, de, en, es, fr, gl, it, nl, nb, oc, pt-BR, sv,
tl, mk, sr, uk, ar, zh-Hans, zh-Hant, ko] :language (en) provides the results in the specified language.
@example
Eol.collections('176', sort_by: 'oldest', cache_ttl: 30) ==> #<Eol::Collections:0x0000000147d078 @name="EOL Group on Flickr", @description="This group...>
@return <Eol::Collections>
# File lib/eol.rb, line 162 def self.collections(id, query_options = {}) @query = { id: id }.merge!(query_options) response = get('/collections/1.0.json', query: @query) response.code == 200 ? Eol::Collections.new(response) : bad_response(response) end
Given the identifier for a data object this API will return all metadata about the object as submitted to EOL by the contributing content partner
@see eol.org/api/docs/data_objects @param [String] id the ID parameter can either be an integer (a DataObject
version ID) or a 16 character GUID which will return the latest version of that object
@param [Hash] query_options @option query_options [Boolean] :taxonomy (true) return any taxonomy details
from different taxon hierarchy providers, in an array named "taxonConcepts"
@option query_options [Integer] :cache_ttl the number of seconds you wish to
have the response cached
@opation query_options [ms, de, en, es, fr, gl, it, nl, nb, oc, pt-BR, sv,
tl, mk, sr, uk, ar, zh-Hans, zh-Hant, ko] :language (en) provides the results in the specified language
@example
Eol.data_objects('30073527', language: 'it', cache_ttl: 30) ==> #<Eol::DataObjects:0x00000000fc75b0 @identifier=1045608...>
@return <Eol::DataObjects>
# File lib/eol.rb, line 187 def self.data_objects(id, query_options = {}) @query = { id: id }.merge!(query_options) response = get('/data_objects/1.0.json', query: @query) response.code == 200 ? Eol::DataObjects.new(response) : bad_response(response) end
Lists metadata about a hierarchy such as the provider name and source URL, as well as lists all the taxa which are the root taxa of the taxonomic tree
@see eol.org/api/docs/hierarchies @param [Integer] id any integer @param [Hash] query_options @option query_options [Integer] :cache_ttl the number of seconds you wish to
have the response cached
@option query_options [ms, de, en, es, fr, gl, it, nl, nb, oc, pt-BR, sv,
tl, mk, sr, uk, ar, zh-Hans, zh-Hant, ko] :language (en) provides the results in the specified language
@example
Eol.hierarchies('1188', language: 'de', cache_ttl: 30) ==> #<Eol::Hierarchies:0x000000015e7a08 @title="Species 2000 & ITIS Catalogue of Life: April 2013"...>
@return <Eol::Hierarchies>
# File lib/eol.rb, line 230 def self.hierarchies(id, query_options = {}) @query = { id: id }.merge!(query_options) response = get('/hierarchies/1.0.json', query: @query) response.code == 200 ? Eol::Hierarchies.new(response) : bad_response(response) end
Gives access to a single hierarchy and its internal relationships
@see eol.org/api/docs/hierarchy_entries @param [Integer] id any integer @param [Hash] query_options @option query_options [Boolean] :common_names (false) return all common
names for this taxon
@option query_options [Boolean] :synonyms (false) return all synonyms for
this taxon
@option query_options [Integer] :cache_ttl the number of seconds you wish to
have the response cached
@option query_options [ms, de, en, es, fr, gl, it, nl, nb, oc, pt-BR, sv,
tl, mk, sr, uk, ar, zh-Hans, zh-Hant, ko] :language (en) provides the results in the specified language
@example
Eol.hierarchy_entries('30408282', common_names: true) ==> #<Eol::HierarchyEntries:0x000000015b8c08 @source_identifier="taxon:142651"...>
@return <Eol::HierarchyEntries>
# File lib/eol.rb, line 210 def self.hierarchy_entries(id, query_options = {}) @query = { id: id }.merge!(query_options) response = get('/hierarchy_entries/1.0.json', query: @query) response.code == 200 ? Eol::HierarchyEntries.new(response) : bad_response(response) end
This method takes an EOL page identifier and returns the scientific name for that page, and optionally returns information about common names, media (text, images and videos), and references to the hierarchies which recognize the taxon described on the page.
@see eol.org/api/docs/pages @param [String] id identifier for node in hierarchies which EOL indexes @param [Hash] query_options @option query_options [Boolean] :batch (False) returns either a batch or not @option query_options [0-75] :images_per_page limits the number of returned
image objects
@option query_options [Integer] :images_page (1) images page @option query_options [0-75] :videos_per_page limits the number of returned @option query_options [Integer] :videos_page (1) videos page @option query_options [0-75] :sounds_per_page limits the number of returned @option query_options [Integer] :sounds_page (1) sounds page @option query_options [0-75] :maps_per_page limits the number of returned @option query_options [Integer] :maps_page (1) maps page @option query_options [0-75] :texts_per_page limites the number of returned @option query_options [Integer] :texts_page (1) texts page @option query_options [String] :subjects
'overview' to return the overview text (if exists), a pipe | delimited list of subject names from the list of EOL accepted subjects (e.g. TaxonBiology, FossilHistory), or 'all' to get text in any subject. options at: http://eol.org/info/toc_subjects
@option query_options [cc-by, cc-by-nc, cc-by-sa, cc-by-nc-sa, pd [public
domain], na [not applicable], all] :license (all) a pipe | delimited list of licenses or 'all' to get objects under any license. Licenses abbreviated cc- are all Creative Commons licenses.
@option query_options [Boolean] :details (false) include all metadata for
data objects
@option query_options [Boolean] :common_names (false) return all common
names for the page's taxon
@option query_options [Boolean] :synonyms (false) return all synonyms for
the page's taxon
@option query_options [Boolean] :references (false) return all references
for the page's taxon
@option query_options [Boolean] :taxonomy (true) return any taxonomy details
from different taxon hierarchy providers, in an array named "taxonConcepts"
@option query_options [0,1,2,3,4] :vetted (0) If 'vetted' is given a value
of '1', then only trusted content will be returned. If 'vetted' is '2', then only trusted and unreviewed content will be returned (untrusted content will not be returned). If 'vetted' is '3', then only unreviewed content will be returned. If 'vetted' is '4', then only untrusted content will be returned.The default is to return all content.
@option query_options [Integer] :cache_ttl the number of seconds you wish to
have the response cached
@option query_options [ms, de, en, es, fr, gl, it, nl, nb, oc, pt-BR, sv,
tl, mk, sr, uk, ar, zh-Hans, zh-Hant, ko] :language (en) provides the results in the specified language.
@example
Eol.pages('1045608', images_per_page: 10, cache_ttl: 30) ==> #<Eol::Pages:0x00000001024058 @scientific_name="Apis mellifera Linnaeus 1758"...>
@return <Eol::Pages>
# File lib/eol.rb, line 132 def self.pages(id, query_options = {}) @query = { id: id }.merge!(query_options) response = get('/pages/1.0.json', query: @query) response.code == 200 ? Eol::Pages.new(response) : bad_response(response) end
Pings the EOL API
@see www.eol.org/api/docs/ping @example
Eol.ping ==> #<Eol::Ping:0x000000027ffcb8 @message="Success">
@return [Eol::Ping] Success or failure results
# File lib/eol.rb, line 28 def self.ping response = get('/ping/1.0.json') response.code == 200 ? Eol::Ping.new(response['response']['message']) : bad_response(response) end
This method will return references to all hierarchies supplied by EOL Content Partners. The response will include the label of the hierarchy and the EOL unique ID representing the hierarchy
@see eol.org/api/docs/provider_hierarchies @example
Eol.provider_hierarchies ==> [#<Eol::ProviderHierarchies:0x000000016080f0 @id=121, @label="AntWeb (Ant Species)">...]
@return [Array<Eol::ProviderHierarchies>]
# File lib/eol.rb, line 244 def self.provider_hierarchies response = get('/provider_hierarchies/1.0.json') response.code == 200 ? response.map { |item| Eol::ProviderHierarchies.new(item) } : bad_response(response) end
Returns one page of results from the EOL API search
@see www.eol.org/api/docs/search @param [String] query The species you're looking for. @param [Hash] query_options @option query_options [Integer] :page a maximum of 30 results are returned
per page. This parameter allows you to fetch more pages of results if there are more than 30 matches
@option query_options [String] :exact will find taxon pages if the preferred
name or any synonym or common name exactly matches the search term, `true` or `false`
@option query_options [Integer] :filter_by_taxon_concept_id given an EOL
page ID, search results will be limited to members of that taxonomic group
@option query_options [Integer] :filter_by_hierarchy_entry_id given a
Hierarchy Entry ID, search results will be limited to members of that taxonomic group
@option query_options [String] :filter_by_string given a search term, an
exact search will be made and that matching page will be used as the taxonomic group against which to filter search results
@option query_options [Integer] :cache_ttl the number of seconds you wish to
have the response cached
@example
Eol.search("dendrophylax", 'exact':true) ==> [#<Eol::Search:0x000000023e0a10 @id=37413, @title="Dendrophylax", @link= ...>]
@return [Array<Eol::Search>]
# File lib/eol.rb, line 57 def self.search(query, query_options = {}) @query = { q: query }.merge!(query_options) response = get('/search/1.0.json', query: @query) response.code == 200 ? response['results'].map { |item| Eol::Search.new(item) } : bad_response(response) end
Returns all results from an EOL API search
@see www.eol.org/api/docs/search @param [String] query The species you're looking for. @note this method does not accept query options, for a more customized search
use Eol.search
@example
Eol.search_all("dendrophylax") ==> [#<Eol::Search:0x000000023e0a10 @id=37413, @title="Dendrophylax", @link= ...>]
@return (see search)
# File lib/eol.rb, line 72 def self.search_all(query) @query = { q: query } response = get('/search/1.0.json', query: @query) response.code == 200 ? all_pages(query, response) : bad_response(response) end
This method takes an integer or string which is the unique identifier for a taxon from some provider's database, and a hierarchy_id which represents the provider and returns the EOL page ID for that taxon.
@see eol.org/api/docs/search_by_provider @param [String] id any string @param [Integer] hierarchy_id the ID of the provider's hierarchy you are
searching within.
@param [Hash] query_options @option query_options [Boolean] :batch (false) returns either a batch or not @option query_options [Integer] :cache_ttl the number of seconds you wish to
have the response cached
@example
Eol.search_by_provider('180542', 903) ==> [#<Eol::SearchByProvider:0x000000022bf3c0 @eol_page_id=328580>, #<Eol::SearchByProvider:0x000000022bf398...>]
@return [Array<Eol::SearchByProvider>]
# File lib/eol.rb, line 264 def self.search_by_provider(id, hierarchy_id, query_options = {}) @query = { id: id, hierarchy_id: hierarchy_id }.merge!(query_options) response = get('/search_by_provider/1.0.json?', query: @query) response.code == 200 ? response.map { |item| Eol::SearchByProvider.new(item) } : bad_response(response) end
Private Class Methods
# File lib/eol.rb, line 270 def self.all_pages(query, response) @n = 0 total = (response['totalResults'] / 30.to_f).ceil total.times.collect { response = get('/search/1.0.json', query: { q: query, page: (@n += 1) }) response['results'].map { |item| Eol::Search.new(item) } }.flatten end
# File lib/eol.rb, line 279 def self.bad_response(response) raise Error, "Error code #{response.code}" if response.class == HTTParty::Response raise StandardError, 'Unknown Error' end