Module: Crawlyflower

Extended by:
Configuration
Defined in:
lib/crawlyflower.rb,
lib/crawlyflower/error.rb,
lib/crawlyflower/request.rb,
lib/crawlyflower/version.rb

Defined Under Namespace

Classes: BadGateway, BadRequest, Error, GatewayTimeout, InternalServerError, NotFound, Request, ServiceUnavailable

Constant Summary collapse

FULL_RECORD_FORMATS = 
{
  jsonld: 'application/ld+json',
  rdf: 'application/rdf+xml',
  turtle: 'text/turtle',
  ntriples: 'application/n-triples'
}.freeze
VERSION = 
"0.0.2"

Class Method Summary collapse

Methods included from Configuration

configuration, define_setting

Class Method Details

.aphia_id_by_name(name, marine_only: nil, extant_only: nil, verbose: false) ⇒ Integer?

Get the AphiaID for a given name

Parameters:

  • name (String) —

    Name to search for

  • marine_only (Boolean) (defaults to: nil) —

    Limit to marine taxa. Default: true

  • extant_only (Boolean) (defaults to: nil) —

    Limit to extant taxa. Default: true

Returns:

  • (Integer, nil) —

    An AphiaID, -999 for multiple matches, or nil if nothing found



67
68
69
70
71
 
# File 'lib/crawlyflower.rb', line 67

def self.aphia_id_by_name(name, marine_only: nil, extant_only: nil, verbose: false)
  endpoint = "AphiaIDByName/#{ERB::Util.url_encode(name)}"
  opts = { marine_only: marine_only, extant_only: extant_only }.compact
  Request.new(endpoint: endpoint, verbose: verbose, options: opts).perform
end

.aphia_ids_by_attribute_key(id, offset: nil, verbose: false) ⇒ Array?

Get a list of AphiaIDs (max 50) with attribute tree for a given attribute definition ID

Parameters:

  • id (Integer) —

    The attribute definition id to search for

  • offset (Integer) (defaults to: nil) —

    Starting record number. Default: 1

Returns:

  • (Array, nil) —

    An array of AphiaAttributeSets or nil if nothing found



306
307
308
309
310
 
# File 'lib/crawlyflower.rb', line 306

def self.aphia_ids_by_attribute_key(id, offset: nil, verbose: false)
  endpoint = "AphiaIDsByAttributeKeyID/#{id}"
  opts = { offset: offset }.compact
  Request.new(endpoint: endpoint, verbose: verbose, options: opts).perform
end

.attribute_keys(id, include_children: nil, verbose: false) ⇒ Array?

Get attribute definitions

Parameters:

  • id (Integer) —

    The attribute definition id to search for. Use 0 for root items

  • include_children (Boolean) (defaults to: nil) —

    Include the tree of children. Default: true

Returns:

  • (Array, nil) —

    An array of attribute keys or nil if nothing found



284
285
286
287
288
 
# File 'lib/crawlyflower.rb', line 284

def self.attribute_keys(id, include_children: nil, verbose: false)
  endpoint = "AphiaAttributeKeysByID/#{id}"
  opts = { include_children: include_children }.compact
  Request.new(endpoint: endpoint, verbose: verbose, options: opts).perform
end

.attribute_values_by_category(id, verbose: false) ⇒ Array?

Get list values that are grouped by a CategoryID

Parameters:

  • id (Integer) —

    The CategoryID to search for

Returns:

  • (Array, nil) —

    An array of attribute values or nil if nothing found



295
296
297
298
 
# File 'lib/crawlyflower.rb', line 295

def self.attribute_values_by_category(id, verbose: false)
  endpoint = "AphiaAttributeValuesByCategoryID/#{id}"
  Request.new(endpoint: endpoint, verbose: verbose).perform
end

.attributes(id, include_inherited: nil, verbose: false) ⇒ Array?

Get a list of attributes for a given AphiaID

Parameters:

  • id (Integer) —

    The AphiaID to search for

  • include_inherited (Boolean) (defaults to: nil) —

    Include attributes inherited from parent(s). Default: false

Returns:

  • (Array, nil) —

    An array of attributes or nil if nothing found



318
319
320
321
322
 
# File 'lib/crawlyflower.rb', line 318

def self.attributes(id, include_inherited: nil, verbose: false)
  endpoint = "AphiaAttributesByAphiaID/#{id}"
  opts = { include_inherited: include_inherited }.compact
  Request.new(endpoint: endpoint, verbose: verbose, options: opts).perform
end

.children(id, marine_only: nil, extant_only: nil, offset: nil, verbose: false) ⇒ Array?

Get the direct children (max. 50) for a given AphiaID

Parameters:

  • id (Integer) —

    The AphiaID to search for

  • marine_only (Boolean) (defaults to: nil) —

    Limit to marine taxa. Default: true

  • extant_only (Boolean) (defaults to: nil) —

    Limit to extant taxa. Default: true

  • offset (Integer) (defaults to: nil) —

    Starting record number. Default: 1

Returns:

  • (Array, nil) —

    An array of AphiaRecords or nil if nothing found



22
23
24
25
26
 
# File 'lib/crawlyflower.rb', line 22

def self.children(id, marine_only: nil, extant_only: nil, offset: nil, verbose: false)
  endpoint = "AphiaChildrenByAphiaID/#{id}"
  opts = { marine_only: marine_only, extant_only: extant_only, offset: offset }.compact
  Request.new(endpoint: endpoint, verbose: verbose, options: opts).perform
end

.classification(id, verbose: false) ⇒ Hash?

Get the complete classification for one taxon

Parameters:

  • id (Integer) —

    The AphiaID to search for

Returns:

  • (Hash, nil) —

    A classification hash or nil if nothing found



33
34
35
36
 
# File 'lib/crawlyflower.rb', line 33

def self.classification(id, verbose: false)
  endpoint = "AphiaClassificationByAphiaID/#{id}"
  Request.new(endpoint: endpoint, verbose: verbose).perform
end

.distributions(id, verbose: false) ⇒ Array?

Get all distributions for a given AphiaID

Parameters:

  • id (Integer) —

    The AphiaID to search for

Returns:

  • (Array, nil) —

    An array of distributions or nil if nothing found



43
44
45
46
 
# File 'lib/crawlyflower.rb', line 43

def self.distributions(id, verbose: false)
  endpoint = "AphiaDistributionsByAphiaID/#{id}"
  Request.new(endpoint: endpoint, verbose: verbose).perform
end

.external_id(id, type: nil, verbose: false) ⇒ Array?

Get any external identifier(s) for a given AphiaID

Parameters:

  • id (Integer) —

    The AphiaID to search for

  • type (String) (defaults to: nil) —

    Type of external identifier (algaebase, bold, dyntaxa, fishbase, iucn, lsid, ncbi, tsn, gisd)

Returns:

  • (Array, nil) —

    An array of external identifiers or nil if nothing found



54
55
56
57
58
 
# File 'lib/crawlyflower.rb', line 54

def self.external_id(id, type: nil, verbose: false)
  endpoint = "AphiaExternalIDByAphiaID/#{id}"
  opts = { type: type }.compact
  Request.new(endpoint: endpoint, verbose: verbose, options: opts).perform
end

.full_record(id, format: :jsonld, verbose: false) ⇒ Hash, ...

Get the complete AphiaFullRecord (linked open data) for a given AphiaID

Parameters:

  • id (Integer) —

    The AphiaID to search for

  • format (Symbol) (defaults to: :jsonld) —

    Response format: :jsonld (default), :rdf, :turtle, :ntriples

Returns:

  • (Hash, String, nil) —

    The full record or nil if nothing found



272
273
274
275
276
 
# File 'lib/crawlyflower.rb', line 272

def self.full_record(id, format: :jsonld, verbose: false)
  endpoint = "AphiaRecordFullByAphiaID/#{id}"
  accept = FULL_RECORD_FORMATS[format] || FULL_RECORD_FORMATS[:jsonld]
  Request.new(endpoint: endpoint, verbose: verbose, accept: accept).perform
end

.name(id, verbose: false) ⇒ String?

Get the name for a given AphiaID

Parameters:

  • id (Integer) —

    The AphiaID to search for

Returns:

  • (String, nil) —

    The scientific name or nil if nothing found



78
79
80
81
 
# File 'lib/crawlyflower.rb', line 78

def self.name(id, verbose: false)
  endpoint = "AphiaNameByAphiaID/#{id}"
  Request.new(endpoint: endpoint, verbose: verbose).perform
end

.record(id, verbose: false) ⇒ Hash?

Get the complete AphiaRecord for a given AphiaID

Parameters:

  • id (Integer) —

    The AphiaID to search for

Returns:

  • (Hash, nil) —

    An AphiaRecord hash or nil if nothing found



88
89
90
91
 
# File 'lib/crawlyflower.rb', line 88

def self.record(id, verbose: false)
  endpoint = "AphiaRecordByAphiaID/#{id}"
  Request.new(endpoint: endpoint, verbose: verbose).perform
end

.record_by_external_id(id, type: nil, verbose: false) ⇒ Hash?

Get the Aphia Record for a given external identifier

Parameters:

  • id (String) —

    The external identifier to search for

  • type (String) (defaults to: nil) —

    Type of external identifier (algaebase, bold, dyntaxa, fishbase, iucn, lsid, ncbi, tsn, gisd)

Returns:

  • (Hash, nil) —

    An AphiaRecord hash or nil if nothing found



110
111
112
113
114
 
# File 'lib/crawlyflower.rb', line 110

def self.record_by_external_id(id, type: nil, verbose: false)
  endpoint = "AphiaRecordByExternalID/#{ERB::Util.url_encode(id.to_s)}"
  opts = { type: type }.compact
  Request.new(endpoint: endpoint, verbose: verbose, options: opts).perform
end

.records_by_aphia_ids(ids, verbose: false) ⇒ Array?

Get AphiaRecords for multiple AphiaIDs in one go (max: 50)

Parameters:

  • ids (Array<Integer>) —

    The AphiaIDs to search for

Returns:

  • (Array, nil) —

    An array of AphiaRecords or nil if nothing found



98
99
100
101
102
 
# File 'lib/crawlyflower.rb', line 98

def self.records_by_aphia_ids(ids, verbose: false)
  endpoint = "AphiaRecordsByAphiaIDs"
  opts = { "aphiaids[]": Array(ids) }
  Request.new(endpoint: endpoint, verbose: verbose, options: opts).perform
end

.records_by_date(startdate:, enddate: nil, marine_only: nil, extant_only: nil, offset: nil, verbose: false) ⇒ Array?

Lists all AphiaRecords that have their last edit action during the specified period

Parameters:

  • startdate (String) —

    ISO 8601 formatted start date(time)

  • enddate (String) (defaults to: nil) —

    ISO 8601 formatted end date(time)

  • marine_only (Boolean) (defaults to: nil) —

    Limit to marine taxa

  • extant_only (Boolean) (defaults to: nil) —

    Limit to extant taxa

  • offset (Integer) (defaults to: nil) —

    Starting record number. Default: 1

Returns:

  • (Array, nil) —

    An array of AphiaRecords or nil if nothing found



125
126
127
128
129
 
# File 'lib/crawlyflower.rb', line 125

def self.records_by_date(startdate:, enddate: nil, marine_only: nil, extant_only: nil, offset: nil, verbose: false)
  endpoint = "AphiaRecordsByDate"
  opts = { startdate: startdate, enddate: enddate, marine_only: marine_only, extant_only: extant_only, offset: offset }.compact
  Request.new(endpoint: endpoint, verbose: verbose, options: opts).perform
end

.records_by_match_names(scientificnames:, authorships: nil, marine_only: nil, extant_only: nil, match_authority: nil, verbose: false) ⇒ Array?

Try to find AphiaRecords using the TAXAMATCH fuzzy matching algorithm

Parameters:

  • scientificnames (Array<String>) —

    Names to search for

  • authorships (Array<String>) (defaults to: nil) —

    The authorities of the given names

  • marine_only (Boolean) (defaults to: nil) —

    Limit to marine taxa

  • extant_only (Boolean) (defaults to: nil) —

    Limit to extant taxa

  • match_authority (Boolean) (defaults to: nil) —

    Use the authority in the matching process

Returns:

  • (Array, nil) —

    An array of arrays of AphiaRecords or nil if nothing found



140
141
142
143
144
145
146
 
# File 'lib/crawlyflower.rb', line 140

def self.records_by_match_names(scientificnames:, authorships: nil, marine_only: nil, extant_only: nil, match_authority: nil, verbose: false)
  endpoint = "AphiaRecordsByMatchNames"
  opts = { "scientificnames[]": Array(scientificnames), marine_only: marine_only, extant_only: extant_only, match_authority: match_authority }
  opts[:"authorships[]"] = Array(authorships) if authorships
  opts = opts.compact
  Request.new(endpoint: endpoint, verbose: verbose, options: opts).perform
end

.records_by_name(name, like: nil, marine_only: nil, extant_only: nil, offset: nil, verbose: false) ⇒ Array?

Get one or more matching (max. 50) AphiaRecords for a given name

Parameters:

  • name (String) —

    Name to search for

  • like (Boolean) (defaults to: nil) —

    Add a ‘%’-sign after the ScientificName. Default: true

  • marine_only (Boolean) (defaults to: nil) —

    Limit to marine taxa

  • extant_only (Boolean) (defaults to: nil) —

    Limit to extant taxa

  • offset (Integer) (defaults to: nil) —

    Starting record number. Default: 1

Returns:

  • (Array, nil) —

    An array of AphiaRecords or nil if nothing found



157
158
159
160
161
 
# File 'lib/crawlyflower.rb', line 157

def self.records_by_name(name, like: nil, marine_only: nil, extant_only: nil, offset: nil, verbose: false)
  endpoint = "AphiaRecordsByName/#{ERB::Util.url_encode(name)}"
  opts = { like: like, marine_only: marine_only, extant_only: extant_only, offset: offset }.compact
  Request.new(endpoint: endpoint, verbose: verbose, options: opts).perform
end

.records_by_names(scientificnames:, like: nil, marine_only: nil, extant_only: nil, verbose: false) ⇒ Array?

For each given scientific name, try to find one or more AphiaRecords (max 500 names)

Parameters:

  • scientificnames (Array<String>) —

    Names to search for

  • like (Boolean) (defaults to: nil) —

    Add a ‘%’-sign after the ScientificName. Default: false

  • marine_only (Boolean) (defaults to: nil) —

    Limit to marine taxa

  • extant_only (Boolean) (defaults to: nil) —

    Limit to extant taxa

Returns:

  • (Array, nil) —

    An array of arrays of AphiaRecords or nil if nothing found



171
172
173
174
175
 
# File 'lib/crawlyflower.rb', line 171

def self.records_by_names(scientificnames:, like: nil, marine_only: nil, extant_only: nil, verbose: false)
  endpoint = "AphiaRecordsByNames"
  opts = { "scientificnames[]": Array(scientificnames), like: like, marine_only: marine_only, extant_only: extant_only }.compact
  Request.new(endpoint: endpoint, verbose: verbose, options: opts).perform
end

.records_by_taxon_rank_id(id, belongs_to: nil, offset: nil, verbose: false) ⇒ Array?

Get the AphiaRecords for a given taxonRankID (max 50)

Parameters:

  • id (Integer) —

    A taxonomic rank identifier

  • belongs_to (Integer) (defaults to: nil) —

    Limit the results to descendants of the given AphiaID

  • offset (Integer) (defaults to: nil) —

    Starting record number. Default: 1

Returns:

  • (Array, nil) —

    An array of AphiaRecords or nil if nothing found



253
254
255
256
257
 
# File 'lib/crawlyflower.rb', line 253

def self.records_by_taxon_rank_id(id, belongs_to: nil, offset: nil, verbose: false)
  endpoint = "AphiaRecordsByTaxonRankID/#{id}"
  opts = { belongsTo: belongs_to, offset: offset }.compact
  Request.new(endpoint: endpoint, verbose: verbose, options: opts).perform
end

.records_by_vernacular(name, like: nil, offset: nil, verbose: false) ⇒ Array?

Get one or more Aphia Records (max. 50) for a given vernacular

Parameters:

  • name (String) —

    The vernacular to find records for

  • like (Boolean) (defaults to: nil) —

    Add a ‘%’-sign before and after the input. Default: false

  • offset (Integer) (defaults to: nil) —

    Starting record number. Default: 1

Returns:

  • (Array, nil) —

    An array of AphiaRecords or nil if nothing found



184
185
186
187
188
 
# File 'lib/crawlyflower.rb', line 184

def self.records_by_vernacular(name, like: nil, offset: nil, verbose: false)
  endpoint = "AphiaRecordsByVernacular/#{ERB::Util.url_encode(name)}"
  opts = { like: like, offset: offset }.compact
  Request.new(endpoint: endpoint, verbose: verbose, options: opts).perform
end

.sources(id, verbose: false) ⇒ Array?

Get one or more sources/references including links, for one AphiaID

Parameters:

  • id (Integer) —

    The AphiaID to search for

Returns:

  • (Array, nil) —

    An array of sources or nil if nothing found



217
218
219
220
 
# File 'lib/crawlyflower.rb', line 217

def self.sources(id, verbose: false)
  endpoint = "AphiaSourcesByAphiaID/#{id}"
  Request.new(endpoint: endpoint, verbose: verbose).perform
end

.suggest(name_part, rank_min: nil, rank_max: nil, max_matches: nil, excluded_ids: nil, combine_vernaculars: nil, marine_only: nil, fossil_id: nil, languages: nil, verbose: false) ⇒ Array?

Get taxa suggestions for a given prefix of a taxon name

Parameters:

  • name_part (String) —

    The prefix to use to search for taxa

  • rank_min (Integer) (defaults to: nil) —

    The minimum rank of the returned suggestion. Default: 10

  • rank_max (Integer) (defaults to: nil) —

    The maximum rank of the returned suggestion. Default: 280

  • max_matches (Integer) (defaults to: nil) —

    The maximum number of suggestions to return. Default: 20, Max: 50

  • excluded_ids (Array<Integer>) (defaults to: nil) —

    AphiaIDs to exclude from the result set

  • combine_vernaculars (Boolean) (defaults to: nil) —

    When true the name can also match vernaculars. Default: false

  • marine_only (Boolean) (defaults to: nil) —

    Limit to marine taxa. Default: true

  • fossil_id (Integer) (defaults to: nil) —

    Determines the search behavior for fossil taxa. Default: 0

  • languages (Array<String>) (defaults to: nil) —

    List of ISO 639-3 language codes to filter search results

Returns:

  • (Array, nil) —

    An array of suggestion records or nil if nothing found



337
338
339
340
341
342
343
344
345
 
# File 'lib/crawlyflower.rb', line 337

def self.suggest(name_part, rank_min: nil, rank_max: nil, max_matches: nil, excluded_ids: nil, combine_vernaculars: nil, marine_only: nil, fossil_id: nil, languages: nil, verbose: false)
  endpoint = "AjaxAphiaRecordsByNamePart/#{ERB::Util.url_encode(name_part)}"
  opts = { rank_min: rank_min, rank_max: rank_max, max_matches: max_matches,
           combine_vernaculars: combine_vernaculars, marine_only: marine_only, fossil_id: fossil_id }
  opts[:"excluded_ids[]"] = Array(excluded_ids) if excluded_ids
  opts[:"languages[]"] = Array(languages) if languages
  opts = opts.compact
  Request.new(endpoint: endpoint, verbose: verbose, options: opts).perform
end

.synonyms(id, offset: nil, verbose: false) ⇒ Array?

Get all synonyms for a given AphiaID

Parameters:

  • id (Integer) —

    The AphiaID to search for

  • offset (Integer) (defaults to: nil) —

    Starting record number. Default: 1

Returns:

  • (Array, nil) —

    An array of AphiaRecords or nil if nothing found



196
197
198
199
200
 
# File 'lib/crawlyflower.rb', line 196

def self.synonyms(id, offset: nil, verbose: false)
  endpoint = "AphiaSynonymsByAphiaID/#{id}"
  opts = { offset: offset }.compact
  Request.new(endpoint: endpoint, verbose: verbose, options: opts).perform
end

.taxon_ranks_by_id(id, aphia_id: nil, verbose: false) ⇒ Array?

Get taxonomic ranks by their identifier

Parameters:

  • id (Integer) —

    A taxonomic rank identifier. Default: -1

  • aphia_id (Integer) (defaults to: nil) —

    The AphiaID of the kingdom

Returns:

  • (Array, nil) —

    An array of taxonomic ranks or nil if nothing found



228
229
230
231
232
 
# File 'lib/crawlyflower.rb', line 228

def self.taxon_ranks_by_id(id, aphia_id: nil, verbose: false)
  endpoint = "AphiaTaxonRanksByID/#{id}"
  opts = { AphiaID: aphia_id }.compact
  Request.new(endpoint: endpoint, verbose: verbose, options: opts).perform
end

.taxon_ranks_by_name(name, aphia_id: nil, verbose: false) ⇒ Array?

Get taxonomic ranks by their name

Parameters:

  • name (String) —

    A taxonomic rank name

  • aphia_id (Integer) (defaults to: nil) —

    The AphiaID of the kingdom

Returns:

  • (Array, nil) —

    An array of taxonomic ranks or nil if nothing found



240
241
242
243
244
 
# File 'lib/crawlyflower.rb', line 240

def self.taxon_ranks_by_name(name, aphia_id: nil, verbose: false)
  endpoint = "AphiaTaxonRanksByName/#{ERB::Util.url_encode(name)}"
  opts = { AphiaID: aphia_id }.compact
  Request.new(endpoint: endpoint, verbose: verbose, options: opts).perform
end

.vernaculars(id, verbose: false) ⇒ Array?

Get all vernaculars for a given AphiaID

Parameters:

  • id (Integer) —

    The AphiaID to search for

Returns:

  • (Array, nil) —

    An array of vernaculars or nil if nothing found



207
208
209
210
 
# File 'lib/crawlyflower.rb', line 207

def self.vernaculars(id, verbose: false)
  endpoint = "AphiaVernacularsByAphiaID/#{id}"
  Request.new(endpoint: endpoint, verbose: verbose).perform
end