Module: Eol

Includes:
HTTParty
Defined in:
lib/eol.rb,
lib/eol/ping.rb,
lib/eol/pages.rb,
lib/eol/search.rb,
lib/eol/version.rb,
lib/eol/collections.rb,
lib/eol/hierarchies.rb,
lib/eol/data_objects.rb,
lib/eol/hierarchy_entries.rb,
lib/eol/search_by_provider.rb,
lib/eol/provider_hierarchies.rb

Overview

The Eol namespace holds all methods and classes that interact with the Encyclopedia of Life API.

Defined Under Namespace

Classes: Collections, DataObjects, Hierarchies, HierarchyEntries, Pages, Ping, ProviderHierarchies, Search, SearchByProvider

Constant Summary collapse

VERSION = 
"0.1.1"

Class Method Summary collapse

Class Method Details

.collections(id, query_options = {}) ⇒ Eol::Collections

Given the identifier for a collection this API will return all metadata about the collection and the items it contains.

Examples:

Eol.collections('176', sort_by: 'oldest', cache_ttl: 30) ==> #<Eol::Collections:0x0000000147d078 @name="EOL Group on Flickr", @description="This group...>

Parameters:

  • id (Integer) —

    any integer

  • query_options (Hash) (defaults to: {})

Options Hash (query_options):

  • :page (Integer) — default: 1 —

    fetches page of results

  • :per_page (0-500) — default: 50 —

    sets number of results per page

  • :filter (articles, collections, communities, images, sounds, taxa, users, video) —

    filters search results

  • :sort_by (recently_added, oldest, alphabetical, reverse_alphabetical, richness, rating, sort_field, reverse_sort_field) — default: recently_added —

    sorts results

  • :sort_field (String) —

    If a sort_field parameter is included, only collection items whose sort field exactly matches the given string will be returned

  • :cache_ttl (Integer) —

    the number of seconds you wish to have the response cached

  • :language (ms, de, en, es, fr, gl, it, nl, nb, oc, pt-BR, sv, tl, mk, sr, uk, ar, zh-Hans, zh-Hant, ko) — default: en —

    provides the results in the specified language.

Returns:

See Also:



162
163
164
165
166
 
# 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

.data_objects(id, query_options = {}) ⇒ Eol::DataObjects

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

Examples:

Eol.data_objects('30073527', language: 'it', cache_ttl: 30) ==> #<Eol::DataObjects:0x00000000fc75b0 @identifier=1045608...>

Parameters:

  • id (String) —

    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

  • query_options (Hash) (defaults to: {})

Options Hash (query_options):

  • :taxonomy (Boolean) — default: true —

    return any taxonomy details from different taxon hierarchy providers, in an array named “taxonConcepts”

  • :cache_ttl (Integer) —

    the number of seconds you wish to have the response cached

Returns:

See Also:



187
188
189
190
191
 
# 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

.hierarchies(id, query_options = {}) ⇒ Eol::Hierarchies

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

Examples:

Eol.hierarchies('1188', language: 'de', cache_ttl: 30) ==> #<Eol::Hierarchies:0x000000015e7a08 @title="Species 2000 & ITIS Catalogue of Life: April 2013"...>

Parameters:

  • id (Integer) —

    any integer

  • query_options (Hash) (defaults to: {})

Options Hash (query_options):

  • :cache_ttl (Integer) —

    the number of seconds you wish to have the response cached

  • :language (ms, de, en, es, fr, gl, it, nl, nb, oc, pt-BR, sv, tl, mk, sr, uk, ar, zh-Hans, zh-Hant, ko) — default: en —

    provides the results in the specified language

Returns:

See Also:



230
231
232
233
234
 
# 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

.hierarchy_entries(id, query_options = {}) ⇒ Eol::HierarchyEntries

Gives access to a single hierarchy and its internal relationships

Examples:

Eol.hierarchy_entries('30408282', common_names: true) ==> #<Eol::HierarchyEntries:0x000000015b8c08 @source_identifier="taxon:142651"...>

Parameters:

  • id (Integer) —

    any integer

  • query_options (Hash) (defaults to: {})

Options Hash (query_options):

  • :common_names (Boolean) — default: false —

    return all common names for this taxon

  • :synonyms (Boolean) — default: false —

    return all synonyms for this taxon

  • :cache_ttl (Integer) —

    the number of seconds you wish to have the response cached

  • :language (ms, de, en, es, fr, gl, it, nl, nb, oc, pt-BR, sv, tl, mk, sr, uk, ar, zh-Hans, zh-Hant, ko) — default: en —

    provides the results in the specified language

Returns:

See Also:



210
211
212
213
214
 
# 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

.pages(id, query_options = {}) ⇒ Eol::Pages

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.

Examples:

Eol.pages('1045608', images_per_page: 10, cache_ttl: 30) ==> #<Eol::Pages:0x00000001024058 @scientific_name="Apis mellifera Linnaeus 1758"...>

Parameters:

  • id (String) —

    identifier for node in hierarchies which EOL indexes

  • query_options (Hash) (defaults to: {})

Options Hash (query_options):

  • :batch (Boolean) — default: False —

    returns either a batch or not

  • :images_per_page (0-75) —

    limits the number of returned image objects

  • :images_page (Integer) — default: 1 —

    images page

  • :videos_per_page (0-75) —

    limits the number of returned

  • :videos_page (Integer) — default: 1 —

    videos page

  • :sounds_per_page (0-75) —

    limits the number of returned

  • :sounds_page (Integer) — default: 1 —

    sounds page

  • :maps_per_page (0-75) —

    limits the number of returned

  • :maps_page (Integer) — default: 1 —

    maps page

  • :texts_per_page (0-75) —

    limites the number of returned

  • :texts_page (Integer) — default: 1 —

    texts page

  • :subjects (String) —

    ‘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: eol.org/info/toc_subjects

  • :license (cc-by, cc-by-nc, cc-by-sa, cc-by-nc-sa, pd [public domain], na [not applicable], all) — default: all —

    a pipe | delimited list of licenses or ‘all’ to get objects under any license. Licenses abbreviated cc- are all Creative Commons licenses.

  • :details (Boolean) — default: false —

    include all metadata for data objects

  • :common_names (Boolean) — default: false —

    return all common names for the page’s taxon

  • :synonyms (Boolean) — default: false —

    return all synonyms for the page’s taxon

  • :references (Boolean) — default: false —

    return all references for the page’s taxon

  • :taxonomy (Boolean) — default: true —

    return any taxonomy details from different taxon hierarchy providers, in an array named “taxonConcepts”

  • :vetted (0, 1, 2, 3, 4) — default: 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.

  • :cache_ttl (Integer) —

    the number of seconds you wish to have the response cached

  • :language (ms, de, en, es, fr, gl, it, nl, nb, oc, pt-BR, sv, tl, mk, sr, uk, ar, zh-Hans, zh-Hant, ko) — default: en —

    provides the results in the specified language.

Returns:

See Also:



132
133
134
135
136
 
# 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

.ping ⇒ Eol::Ping

Pings the EOL API

Examples:

Eol.ping ==> #<Eol::Ping:0x000000027ffcb8 @message="Success">

Returns:

See Also:



28
29
30
31
 
# 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

.provider_hierarchies ⇒ Array<Eol::ProviderHierarchies>

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

Examples:

Eol.provider_hierarchies ==> [#<Eol::ProviderHierarchies:0x000000016080f0 @id=121, @label="AntWeb (Ant Species)">...]

Returns:

See Also:



244
245
246
247
 
# 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

.search(query, query_options = {}) ⇒ Array<Eol::Search>

Returns one page of results from the EOL API search

Examples:

Eol.search("dendrophylax", 'exact':true) ==> [#<Eol::Search:0x000000023e0a10 @id=37413, @title="Dendrophylax", @link= ...>]

Parameters:

  • query (String) —

    The species you’re looking for.

  • query_options (Hash) (defaults to: {})

Options Hash (query_options):

  • :page (Integer) —

    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

  • :exact (String) —

    will find taxon pages if the preferred name or any synonym or common name exactly matches the search term, ‘true` or `false`

  • :filter_by_taxon_concept_id (Integer) —

    given an EOL page ID, search results will be limited to members of that taxonomic group

  • :filter_by_hierarchy_entry_id (Integer) —

    given a Hierarchy Entry ID, search results will be limited to members of that taxonomic group

  • :filter_by_string (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

  • :cache_ttl (Integer) —

    the number of seconds you wish to have the response cached

Returns:

See Also:



57
58
59
60
61
 
# 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

.search_all(query) ⇒ Array<Eol::Search>

Note:

this method does not accept query options, for a more customized search use Eol.search

Returns all results from an EOL API search

Examples:

Eol.search_all("dendrophylax") ==> [#<Eol::Search:0x000000023e0a10 @id=37413, @title="Dendrophylax", @link= ...>]

Parameters:

  • query (String) —

    The species you’re looking for.

Returns:

See Also:



72
73
74
75
76
 
# 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

.search_by_provider(id, hierarchy_id, query_options = {}) ⇒ Array<Eol::SearchByProvider>

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.

Examples:

Eol.search_by_provider('180542', 903) ==> [#<Eol::SearchByProvider:0x000000022bf3c0 @eol_page_id=328580>, #<Eol::SearchByProvider:0x000000022bf398...>]

Parameters:

  • id (String) —

    any string

  • hierarchy_id (Integer) —

    the ID of the provider’s hierarchy you are searching within.

  • query_options (Hash) (defaults to: {})

Options Hash (query_options):

  • :batch (Boolean) — default: false —

    returns either a batch or not

  • :cache_ttl (Integer) —

    the number of seconds you wish to have the response cached

Returns:

See Also:



264
265
266
267
268
 
# 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