Module: Colrapi

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

Defined Under Namespace

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

Constant Summary collapse

VERSION = 
"0.1.6"

Class Method Summary collapse

Methods included from Configuration

configuration, define_setting

Class Method Details

.archive(dataset_id, attempt: nil, verbose: false) ⇒ Binary

Get a dataset’s original archive

Parameters:

  • dataset_id (String) —

    The dataset id

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

    Returns archive for a past import attempt number

Returns:

  • (Binary) —

    An archive of the original dataset



31
32
33
34
 
# File 'lib/colrapi.rb', line 31

def self.archive(dataset_id, attempt: nil, verbose: false)
  endpoint = "dataset/#{dataset_id}/archive"
  Request.new(endpoint: endpoint, attempt: attempt, verbose: verbose).perform
end

.assembly(dataset_id, verbose: false) ⇒ Hash

Get assembly status

Parameters:

  • dataset_id (String) —

    The dataset id

Returns:

  • (Hash) —

    A result hash of the assembly queue



20
21
22
23
 
# File 'lib/colrapi.rb', line 20

def self.assembly(dataset_id, verbose: false)
  endpoint = "dataset/#{dataset_id}/assembly"
  Request.new(endpoint: endpoint, verbose: verbose).perform
end

.dataset(dataset_id: nil, attempt: nil, q: nil, short_title: nil, code: nil, private: nil, released_from: nil, contributes_to: nil, has_source_dataset: nil, has_gbif_id: nil, gbif_id: nil, gbif_publisher_id: nil, editor: nil, reviewer: nil, modified_by: nil, origin: nil, type: nil, license: nil, row_type: nil, created_after: nil, created_before: nil, issued_after: nil, issued_before: nil, modified_after: nil, modified_before: nil, min_size: nil, sort_by: nil, token: nil, reverse: nil, offset: nil, limit: nil, verbose: false) ⇒ Array, Boolean

Get dataset metadata

For a specific dataset:

@param dataset_id [String] The dataset id
@param attempt [Integer] Returns archived metadata for a past import attempt number

Search datasets:

@param q [String] A search query for datasets
@param short_title [String] A dataset alias
@param title [String] A dataset title
@param code [String] The nomenclatural code (bacterial, botanical, cultivars, phytosociological, virus, zoological)
@param private [Boolean] Whether the dataset is private or not
@param released_from [Integer] Filter by a project id that a dataset was released from
@param contributes_to [Integer] Filter by a project id that a dataset contributes to
@param has_source_dataset [Boolean] Filter by if source datasets contribute to the project dataset
@param has_gbif_id [Boolean] Whether the dataset has a GBIF registry id
@param gbif_id [String] The GBIF registry id
@param gbif_publisher_id [String] Filter by a GBIF publisher's id
@param editor [Integer] Filter by an editor's user id
@param reviewer [Integer] Filter by a reviewer's user id
@param modified_by [Integer] Filter by a user id  on last modified by
@param origin [Array, String] Filter by the origin of a dataset (external, project, release, xrelease)
@param type [Array, String] Filter by the dataset type (nomenclatural, taxonomic, phylogenetic, article, legal, thematic, other)
@param license [Array, String] Filter by the license type (cc0, cc_by, cc_by_sa, cc_by_nc, cc_by_nd, cc_by_nc_sa, cc_by_nc_nd, unspecified, other)
@param row_type [Array, String] Filter by datasets that include a row type (e.g., acef:AcceptedSpecies, col:Taxon, dwc:Taxon)
@param created_after [Date] Filter by created after date
@param created_before [Date] Filter by created before date
@param issued_after [Date] Filter by issued after date
@param issued_before [Date] Filter by issued before date
@param modified_after [Date] Filter by modified after date
@param modified_before [Date] Filter by modified before date
@param min_size [Integer] Filter by minimum record size
@param token [String, nil] An authentication token from Colrapi.user_login()

@param sort_by [String] Sort by (key, alias, title, creator, relevance, created, modified, imported, size)
@param reverse [Boolean] Sort in reverse
@param offset [Integer] Offset for pagination
@param limit [Integer] Limit for pagination
@param verbose [Boolean] Print headers to STDOUT

Returns:

  • (Array, Boolean) —

    An array of hashes



77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
 
# File 'lib/colrapi.rb', line 77

def self.dataset(dataset_id: nil, attempt: nil, q: nil, short_title: nil, code: nil, private: nil, released_from: nil,
                 contributes_to: nil, has_source_dataset: nil, has_gbif_id: nil, gbif_id: nil, gbif_publisher_id: nil,
                 editor: nil, reviewer: nil, modified_by: nil, origin: nil, type: nil, license: nil, row_type: nil,
                 created_after: nil, created_before: nil, issued_after: nil, issued_before: nil, modified_after: nil,
                 modified_before: nil, min_size: nil, sort_by: nil, token: nil, reverse: nil, offset: nil, limit: nil,
                 verbose: false)
  endpoint = "dataset"
  unless dataset_id.nil?
    endpoint = "#{endpoint}/#{dataset_id}"
    unless attempt.nil?
      endpoint = "#{endpoint}/#{attempt}"
    end
    endpoint = "#{endpoint}.json"
    Request.new(endpoint: endpoint, verbose: verbose).perform
  else
    Request.new(endpoint: endpoint, q: q, short_title: short_title, code: code, private: private,
                released_from: released_from, contributes_to: contributes_to, has_source_dataset: has_source_dataset,
                has_gbif_id: has_gbif_id, gbif_id: gbif_id, gbif_publisher_id: gbif_publisher_id, editor: editor,
                reviewer: reviewer, modified_by: modified_by, origin: origin, type: type, license: license,
                row_type: row_type, created_after: created_after, created_before: created_before,
                issued_after: issued_after, issued_before: issued_before, modified_after: modified_after,
                modified_before: modified_before, min_size: min_size, sort_by: sort_by, reverse: reverse,
                offset: offset, limit: limit, token: token, verbose: verbose).perform
  end
end

.decision(dataset_id, decision_id: nil, name: nil, rank: nil, modified_by: nil, broken: nil, subject_dataset_id: nil, mode: nil, subject: nil, offset: nil, limit: nil, verbose: false) ⇒ Hash, Boolean

Get project decisions

Parameters:

  • dataset_id (String) —

    The dataset id

  • decision_id (Integer, nil) (defaults to: nil) —

    The decision id

  • name (String, nil) (defaults to: nil) —

    The scientific name to match

  • rank (String, nil) (defaults to: nil) —

    The rank of the scientific name

  • modified_by (Integer, nil) (defaults to: nil) —

    Filter by a user id on last modified by

  • broken (Boolean, nil) (defaults to: nil) —

    Whether the decision is broken or not

  • subject_dataset_id (String, nil) (defaults to: nil) —

    The source dataset id

  • mode (String, nil) (defaults to: nil) —

    The type of decision (block, reviewed, update, update_recursive, ignore)

  • subject (Boolean, nil) (defaults to: nil) —

    TODO: what does this do? All decisions with subject=true are bare names, so maybe it checks if the subject taxon exists?

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

    Offset for pagination

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

    Limit for pagination

  • verbose (Boolean) (defaults to: false) —

    Print headers to STDOUT

Returns:

  • (Hash, Boolean) —

    A result hash



120
121
122
123
124
125
126
127
128
129
130
131
 
# File 'lib/colrapi.rb', line 120

def self.decision(dataset_id, decision_id: nil, name: nil, rank: nil, modified_by: nil, broken: nil,
                  subject_dataset_id: nil, mode: nil, subject: nil, offset: nil, limit: nil, verbose: false)
  if decision_id.nil?
    endpoint = "dataset/#{dataset_id}/decision"
    Request.new(endpoint: endpoint, name: name, rank: rank, modified_by: modified_by, broken: broken,
                subject_dataset_id: subject_dataset_id, mode: mode, subject: subject, offset: offset,
                limit: limit, verbose: verbose).perform
  else
    endpoint = "dataset/#{dataset_id}/decision/#{decision_id}"
    Request.new(endpoint: endpoint, verbose: verbose).perform
  end
end

.diff(dataset_id, dataset2_id, root_id: nil, root2_id: nil, min_rank: nil, authorship: nil, include_synonyms: nil, include_parent: nil, parent_rank: nil, offset: nil, limit: nil, token: nil, verbose: false) ⇒ String, Boolean

Get names diff between 2 datasets

Parameters:

  • dataset_id (String) —

    The first dataset id

  • dataset2_id (String) —

    The second dataset id

  • root_id (Array, String, nil) (defaults to: nil) —

    The root taxon for the first dataset

  • root2_id (Array, String, nil) (defaults to: nil) —

    The root taxon for the second dataset

  • min_rank (String, nil) (defaults to: nil) —

    The minimum taxonomic rank

  • authorship (Boolean, nil) (defaults to: nil) —

    Include authorship

  • include_synonyms (Boolean, nil) (defaults to: nil) —

    Include synonyms

  • include_parent (Boolean, nil) (defaults to: nil) —

    Include parent

  • parent_rank (String, nil) (defaults to: nil) —

    Filter by parent rank

  • token (String, nil) (defaults to: nil) —

    An authentication token from Colrapi.user_login()

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

    Offset for pagination

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

    Limit for pagination

  • verbose (Boolean) (defaults to: false) —

    Print headers to STDOUT

Returns:

  • (String, Boolean) —

    A text diff of names



163
164
165
166
167
168
169
170
171
 
# File 'lib/colrapi.rb', line 163

def self.diff(dataset_id, dataset2_id, root_id: nil, root2_id: nil, min_rank: nil,
              authorship: nil, include_synonyms: nil, include_parent: nil, parent_rank: nil,
              offset: nil, limit: nil, token: nil, verbose: false)
  endpoint = "dataset/#{dataset_id}/diff/#{dataset2_id}"
  Request.new(endpoint: endpoint, root_id: root_id, root2_id: root2_id, min_rank: min_rank,
              authorship: authorship, include_synonyms: include_synonyms,
              include_parent: include_parent, parent_rank: parent_rank,
              offset: offset, limit: limit, token: token, verbose: verbose).perform
end

.duplicate(dataset_id, offset: nil, limit: nil, verbose: false) ⇒ Object

Get duplicate names

Parameters:

  • dataset_id (String) —

    The dataset id

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

    Offset for pagination

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

    Limit for pagination

  • verbose (Boolean) (defaults to: false) —

    Print headers to STDOUT



140
141
142
143
 
# File 'lib/colrapi.rb', line 140

def self.duplicate(dataset_id, offset: nil, limit: nil, verbose: false)
  endpoint = "dataset/#{dataset_id}/duplicate"
  Request.new(endpoint: endpoint, offset: offset, limit: limit, verbose: verbose).perform
end

.editor(dataset_id, token, verbose: false) ⇒ Object

Get editor info

# @return [Array, Hash, Boolean] An array of hashes

Parameters:

  • dataset_id (String) —

    The dataset id

  • token (String, nil) —

    The authentication token from retrieved with Colrapi.user_login(user, password)



179
180
181
182
 
# File 'lib/colrapi.rb', line 179

def self.editor(dataset_id, token, verbose: false)
  endpoint = "dataset/#{dataset_id}/editor"
  Request.new(endpoint: endpoint, token: token, verbose: verbose).perform
end

.estimate(dataset_id, estimate_id: nil, name: nil, rank: nil, modified_by: nil, broken: nil, min: nil, max: nil, offset: nil, limit: nil, verbose: false) ⇒ Hash, Boolean

Get estimates

Parameters:

  • dataset_id (String) —

    The dataset id

  • estimate_id (Integer, nil) (defaults to: nil) —

    The estimate ID

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

    The scientific name

  • rank (String, nil) (defaults to: nil) —

    taxonomic rank

  • modified_by (Integer, nil) (defaults to: nil) —

    Filter by a user id on last modified by

  • broken (Boolean, nil) (defaults to: nil) —

    Whether the estimate is broken or not

  • min (Integer, nil) (defaults to: nil) —

    Filter by the minimum estimate

  • max (Integer, nil) (defaults to: nil) —

    Filter by the maximum estimate

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

    Offset for pagination

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

    Limit for pagination

  • verbose (Boolean) (defaults to: false) —

    Print headers to STDOUT

Returns:

  • (Hash, Boolean) —

    A results hash



199
200
201
202
203
204
205
206
207
208
209
 
# File 'lib/colrapi.rb', line 199

def self.estimate(dataset_id, estimate_id: nil, name: nil, rank: nil, modified_by: nil, broken: nil, min: nil,
                  max: nil, offset: nil, limit: nil, verbose: false)
  endpoint = "dataset/#{dataset_id}/estimate"
  if estimate_id.nil?
    Request.new(endpoint: endpoint, name: name, rank: rank, modified_by: modified_by, broken: broken,
                min: min, max: max, offset: offset, limit: limit, verbose: verbose).perform
  else
    endpoint = "dataset/#{dataset_id}/estimate/#{estimate_id}"
    Request.new(endpoint: endpoint, verbose: verbose).perform
  end
end

.export(dataset_id, show_id: nil, verbose: false) ⇒ Hash, Boolean

TODO: /dataset/key/export is covered, but /export and /export/id are not Get a dataset export

Parameters:

  • dataset_id (String) —

    The dataset id

  • show_id (Boolean, nil) (defaults to: nil) —

    TODO: not implemented because it doesn’t seem to do anything?

  • verbose (Boolean) (defaults to: false) —

    Print headers to STDOUT

Returns:

  • (Hash, Boolean) —

    An export hash



219
220
221
222
 
# File 'lib/colrapi.rb', line 219

def self.export(dataset_id, show_id: nil, verbose: false)
  endpoint = "dataset/#{dataset_id}/export"
  Request.new(endpoint: endpoint, verbose: verbose).perform
end

.importer(dataset_id: nil, dataset_id_filter: nil, state: nil, running: nil, offset: nil, limit: nil, verbose: false) ⇒ Array, Boolean

Get importer status

Parameters:

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

    Calls the dataset_id endpoint /importer/dataset_id

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

    Filters the importer queue by dataset_id

  • state (Array, String) (defaults to: nil) —

    The import status (e.g., waiting, preparing, downloading, processing, inserting, …)

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

    Filter by actively importing datasets

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

    Offset for pagination

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

    Limit for pagination

  • verbose (Boolean) (defaults to: false) —

    Print headers to STDOUT

Returns:

  • (Array, Boolean) —

    An array of hashes



275
276
277
278
279
280
281
282
283
284
285
 
# File 'lib/colrapi.rb', line 275

def self.importer(dataset_id: nil, dataset_id_filter: nil, state: nil, running: nil, offset: nil, limit: nil,
                  verbose: false)
  endpoint = "importer"
  if dataset_id.nil?
    Request.new(endpoint: endpoint, dataset_id_filter: dataset_id_filter, state: state, running: running,
                offset: offset, limit: limit, verbose: verbose).perform
  else
    endpoint = "#{endpoint}/#{dataset_id}"
    Request.new(endpoint: endpoint, verbose: verbose).perform
  end
end

.issues(dataset_id, issue: nil, mode: 'verbatim', offset: nil, limit: nil, verbose: false) ⇒ Array, ...

Get data quality issues

Parameters:

  • dataset_id (String) —

    The dataset id

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

    Filter by data quality issue (e.g., ACCEPTED_NAME_MISSING, DUPLICATE_NAME, URL_INVALID)

  • mode (String) (defaults to: 'verbatim') —

    Verbatim (default) or interpreted

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

    Offset for pagination

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

    Limit for pagination

  • verbose (Boolean) (defaults to: false) —

    Print headers to STDOUT

Returns:

  • (Array, Hash, Boolean) —

    An array of hashes



235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
 
# File 'lib/colrapi.rb', line 235

def self.issues(dataset_id, issue: nil, mode: 'verbatim', offset: nil, limit: nil, verbose: false)
  if issue.nil?
    metrics = Request.new(endpoint: "/dataset/#{dataset_id}/import?state=finished").perform
    return {"issuesCount" => metrics[0]['issuesCount']}
  else
    if mode == 'interpreted'
      issues = self.vocab(term: 'issue')
      record_type = 'any'
      issues.each do |i|
        if i['name'] == issue.downcase
          record_type = i['group']
        end
      end

      # TODO: so far issues are only filterable on nameusage/search and /reference
      #   for other record_types, may need to add other endpoints in the future
      if record_type == 'reference'
        self.reference(dataset_id, issue: issue, offset: offset, limit: limit, verbose: verbose)
      else
        self.nameusage_search(dataset_id: dataset_id, issue: issue, facet: 'issue', offset: offset, limit: limit,
                            verbose: verbose)
      end
    else
      self.verbatim(dataset_id, issue: issue, offset: offset, limit: limit, verbose: verbose)
    end
  end
end

.logo(dataset_id, size: nil, verbose: false) ⇒ Binary

Get a dataset’s logo

Parameters:

  • dataset_id (String) —

    The dataset id

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

    The size of the logo (original, large, medium, small)

Returns:

  • (Binary) —

    The dataset logo



293
294
295
296
 
# File 'lib/colrapi.rb', line 293

def self.(dataset_id, size: nil, verbose: false)
  endpoint = "dataset/#{dataset_id}/logo"
  Request.new(endpoint: endpoint, size: size, verbose: verbose).perform
end

.matching(dataset_id, name: nil, authorship: nil, code: nil, rank: nil, within_superkingdom: nil, within_kingdom: nil, within_subkingdom: nil, within_superphylum: nil, within_phylum: nil, within_subphylum: nil, within_superclass: nil, within_class: nil, within_subclass: nil, within_superorder: nil, within_order: nil, within_suborder: nil, within_superfamily: nil, within_family: nil, within_subfamily: nil, within_tribe: nil, within_subtribe: nil, within_genus: nil, within_subgenus: nil, within_section: nil, within_species: nil, verbose: false) ⇒ Array, Boolean

Get names or a name from a dataset

Parameters:

  • dataset_id (String) —

    The dataset id

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

    The scientific name to match

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

    The authorship string for the scientific name

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

    The nomenclatural code (bacterial, botanical, cultivars, phytosociological, virus, zoological)

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

    The rank of the scientific name

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

    Restricts query to within a superkingdom

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

    Restricts query to within a kingdom

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

    Restricts query to within a subkingdom

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

    Restricts query to within a superphylum

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

    Restricts query to within a phylum

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

    Restricts query to within a subphylum

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

    Restricts query to within a superclass

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

    Restricts query to within a class

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

    Restricts query to within a subclass

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

    Restricts query to within a superorder

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

    Restricts query to within a order

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

    Restricts query to within a suborder

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

    Restricts query to within a superfamily

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

    Restricts query to within a family

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

    Restricts query to within a subfamily

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

    Restricts query to within a tribe

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

    Restricts query to within a subtribe

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

    Restricts query to within a genus

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

    Restricts query to within a subgenus

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

    Restricts query to within a section

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

    Restricts query to within a species

  • verbose (Boolean) (defaults to: false) —

    Print headers to STDOUT

Returns:

  • (Array, Boolean) —

    An array of hashes



506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
 
# File 'lib/colrapi.rb', line 506

def self.matching(dataset_id, name: nil, authorship: nil, code: nil, rank: nil, within_superkingdom: nil,
                  within_kingdom: nil, within_subkingdom: nil, within_superphylum: nil, within_phylum: nil,
                  within_subphylum: nil, within_superclass: nil, within_class: nil, within_subclass: nil,
                  within_superorder: nil, within_order: nil, within_suborder: nil, within_superfamily: nil,
                  within_family: nil, within_subfamily: nil, within_tribe: nil, within_subtribe: nil,
                  within_genus: nil, within_subgenus: nil, within_section: nil, within_species: nil,
                  verbose: false)
  endpoint = "dataset/#{dataset_id}/nameusage/match"
  Request.new(endpoint: endpoint, name: name, authorship: authorship, code: code, rank: rank,
              within_superkingdom: within_superkingdom, within_kingdom: within_kingdom,
              within_subkingdom: within_subkingdom, within_superphylum: within_superphylum,
              within_phylum: within_phylum, within_subphylum: within_subphylum, within_superclass: within_superclass,
              within_class: within_class, within_subclass: within_subclass, within_superorder: within_superorder,
              within_order: within_order, within_suborder: within_suborder, within_superfamily: within_superfamily,
              within_family: within_family, within_subfamily: within_subfamily, within_tribe: within_tribe,
              within_subtribe: within_subtribe, within_genus: within_genus, within_subgenus: within_subgenus,
              within_section: within_section, within_species: within_species, verbose: verbose).perform
end

.metrics(dataset_id, import_attempt: nil, verbose: false) ⇒ Array, ...

Get metrics for the *last successful* import of a dataset or a specific import_attempt

Parameters:

  • dataset_id (String) —

    The dataset id

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

    The import attempt

Returns:

  • (Array, Hash, Boolean) —

    An array of hashes



355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
 
# File 'lib/colrapi.rb', line 355

def self.metrics(dataset_id, import_attempt: nil, verbose: false)

  import = self.importer(dataset_id: dataset_id)
  unless %w[unchanged finished].include? import['state']
    return {"code" => 400, 'message' => 'Dataset has not finished importing or failed to import'}
  end

  # it's necessary to get the last finished import attempt because status=unchanged import results don't have metrics
  #   project release datasets do not seem to have import_attempts or should be taken from the project dataset, e.g.:
  #     https://api.checklistbank.org/dataset/3/import/107 == https://api.checklistbank.org/dataset/9837/import
  if import_attempt.nil?
    import = self.importer(dataset_id_filter: dataset_id, state: 'finished')
    if import['total'] > 0
      import_attempt = import['result'][0]['attempt']
    end
  end

  endpoint = "dataset/#{dataset_id}/import"
  if !import_attempt.nil?
    endpoint = "#{endpoint}/#{import_attempt}"
    Request.new(endpoint: endpoint, verbose: verbose).perform
  else
    # /dataset/{id}/import returns an array of 1 item while /dataset/{id}/import/{attempt} doesn't
    res = Request.new(endpoint: endpoint, verbose: verbose).perform
    res[0]
  end
end

.name(dataset_id, name_id: nil, subresource: nil, offset: nil, limit: nil, verbose: false) ⇒ Array, Boolean

Get names or a name from a dataset

Parameters:

  • dataset_id (String) —

    The dataset id

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

    The name id

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

    The name subresource endpoint (relations, synonyms, types, or orphans)

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

    Offset for pagination

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

    Limit for pagination

  • verbose (Boolean) (defaults to: false) —

    Print headers to STDOUT

Returns:

  • (Array, Boolean) —

    An array of hashes



394
395
396
397
398
399
400
401
402
403
404
405
 
# File 'lib/colrapi.rb', line 394

def self.name(dataset_id, name_id: nil, subresource: nil, offset: nil, limit: nil, verbose: false)
  endpoint = "dataset/#{dataset_id}/name"
  unless name_id.nil?
    endpoint = "#{endpoint}/#{name_id}"
    offset = nil
    limit = nil
  end
  if !subresource.nil? and %w[relations synonyms types orphans].include? subresource
    endpoint = "#{endpoint}/#{subresource}"
  end
  Request.new(endpoint: endpoint, offset: offset, limit: limit, verbose: verbose).perform
end

.name_list(dataset_id, import_attempt: nil, verbose: nil) ⇒ Object

Get a text list of names for a dataset

Parameters:

  • dataset_id (String) —

    The dataset id

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

    The import attempt number



412
413
414
415
416
417
418
419
420
421
422
 
# File 'lib/colrapi.rb', line 412

def self.name_list(dataset_id, import_attempt: nil, verbose: nil)

  # get last import attempt number if none given
  if import_attempt.nil?
    import = self.importer(dataset_id: dataset_id)
    import_attempt = import['attempt']
  end

  endpoint = "dataset/#{dataset_id}/import/#{import_attempt}/names"
  Request.new(endpoint: endpoint, verbose: verbose).perform
end

.name_tree(dataset_id, import_attempt: nil, verbose: nil) ⇒ Object

Get a text tree of names for a dataset

Parameters:

  • dataset_id (String) —

    The dataset id

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

    The import attempt number



429
430
431
432
433
434
435
436
437
438
439
 
# File 'lib/colrapi.rb', line 429

def self.name_tree(dataset_id, import_attempt: nil, verbose: nil)

  # get last import attempt number if none given
  if import_attempt.nil?
    import = self.importer(dataset_id: dataset_id)
    import_attempt = import['attempt']
  end

  endpoint = "dataset/#{dataset_id}/import/#{import_attempt}/tree"
  Request.new(endpoint: endpoint, verbose: verbose).perform
end

.nameusage(dataset_id, nameusage_id: nil, q: nil, rank: nil, nidx_id: nil, subresource: nil, offset: nil, limit: nil, verbose: false) ⇒ Array, Boolean

Get name usages or a nameusage from a dataset

Note: Queries the PostgreSQL database, whereas nameusage_search uses Elasticsearch

Parameters:

  • dataset_id (String) —

    The dataset id

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

    The nameusage id

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

    The scientific name or authorship search query

  • rank (Array, String) (defaults to: nil) —

    The rank of the taxon in the search query q

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

    The name index id

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

    The name subresource endpoint (relations, synonyms, types, or orphans)

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

    Offset for pagination

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

    Limit for pagination

  • verbose (Boolean) (defaults to: false) —

    Print headers to STDOUT

Returns:

  • (Array, Boolean) —

    An array of hashes



456
457
458
459
460
461
462
463
464
465
466
467
468
469
 
# File 'lib/colrapi.rb', line 456

def self.nameusage(dataset_id, nameusage_id: nil, q: nil, rank: nil, nidx_id: nil, subresource: nil,
                   offset: nil, limit: nil, verbose: false)
  endpoint = "dataset/#{dataset_id}/nameusage"
  unless nameusage_id.nil?
    endpoint = "#{endpoint}/#{nameusage_id}"
    offset = nil
    limit = nil
  end
  unless subresource.nil?
    endpoint = "#{endpoint}/#{subresource}"
  end
  Request.new(endpoint: endpoint, q: q, rank: rank, nidx_id: nidx_id, offset: offset, limit: limit,
              verbose: verbose).perform
end

.nameusage_pattern(dataset_id, regexp, status: nil, rank: nil, project_id: nil, decision_mode: nil, offset: nil, limit: nil, verbose: false) ⇒ Object

Search for a name usage with a regex pattern

Parameters:

  • dataset_id (String, nil) —

    restricts name usage pattern search within a dataset

  • regexp (String) —

    The regular expression pattern

  • status (String, nil) (defaults to: nil) —

    The taxonomic status (accepted, provisionally_accepted, synonym, ambiguous_synonym, misapplied, bare_name)

  • rank (String, nil) (defaults to: nil) —

    The taxonomic rank

  • project_id (String, nil) (defaults to: nil) —

    Filter to names from project_id, required if decision_mode used

  • decision_mode (String, nil) (defaults to: nil) —

    The type of decision (block, reviewed, update, update_recursive, ignore)

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

    Offset for pagination

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

    Limit for pagination

  • verbose (Boolean) (defaults to: false) —

    Print headers to STDOUT



537
538
539
540
541
542
 
# File 'lib/colrapi.rb', line 537

def self.nameusage_pattern(dataset_id, regexp, status: nil, rank: nil, project_id: nil, decision_mode: nil,
                           offset: nil, limit: nil, verbose: false)
  endpoint = "dataset/#{dataset_id}/nameusage/pattern"
  Request.new(endpoint: endpoint, regexp: regexp, project_id: project_id, status: status, rank: rank,
              decision_mode: decision_mode, offset: offset, limit: limit, verbose: verbose).perform
end

.nameusage_search(q: nil, authorship: nil, authorship_year: nil, dataset_id: nil, endpoint: 'nameusage/search', extinct: nil, field: nil, content: nil, issue: nil, type: nil, rank: nil, min_rank: nil, max_rank: nil, environment: nil, facet: nil, nomenclatural_code: nil, highest_taxon_id: nil, usage_id: nil, nomenclatural_status: nil, name_type: nil, origin: nil, secondary_source: nil, sector_mode: nil, sector_dataset_id: nil, status: nil, taxonomic_group: nil, sort_by: nil, reverse: nil, offset: nil, limit: nil, verbose: false) ⇒ Array, Boolean

Search the nameusage route, which uses Elastic Search

Parameters:

  • authorship (Array, String, nil) (defaults to: nil) —

    filters by authorship

  • authorship_year (Array, String, nil) (defaults to: nil) —

    filters by authorship year

  • content (Array, String, nil) (defaults to: nil) —

    restrict search to SCIENTIFIC_NAME, or AUTHORSHIP

  • dataset_id (String, nil) (defaults to: nil) —

    restricts name usage search within a dataset

  • endpoint (String, nil) (defaults to: 'nameusage/search') —

    some endpoints have nested options

  • environment (Array, String, nil) (defaults to: nil) —

    filter by environment (MARINE, TERRESTRIAL, FRESHWATER, BRACKISH)

  • extinct (Array, int, nil) (defaults to: nil) —

    filter by extinct status (0, 1)

  • facet (Array, String, nil) (defaults to: nil) —

    the search facet

  • field (Array, String, nil) (defaults to: nil) —

    filter by name field (see: api.checklistbank.org/vocab/namefield)

  • highest_taxon_id (String, nil) (defaults to: nil) —

    Filter by highest taxon ID

  • issue (Array, String, nil) (defaults to: nil) —

    the data quality issue

  • max_rank (String, nil) (defaults to: nil) —

    maximum taxonomic rank of name usages

  • min_rank (String, nil) (defaults to: nil) —

    minimum taxonomic rank of name usages

  • name_type (Array, String, nil) (defaults to: nil) —

    filter by name type (hybrid formula, informal, no name, otu, placeholder, scientific, virus)

  • nomenclatural_code (Array, String, nil) (defaults to: nil) —

    filter by nomenclatural code (botanical, zoological, bacterial, viral, phytosociological, cultivars)

  • nomenclatural_status (Array, String, nil) (defaults to: nil) —

    filter by nomenclatural status (acceptable, conserved, doubtful, established, manuscript, not established, rejected, unacceptable)

  • origin (Array, String, nil) (defaults to: nil) —

    filter by origin of the name usage (see: api.checklistbank.org/vocab/origin)

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

    A query string

  • rank (Array, String, nil) (defaults to: nil) —

    taxonomic rank of name usages

  • secondary_source (Array, String, nil) (defaults to: nil) —

    filter by secondary source (authorship, basionym, extinct, holotype, parent, published in, rank, temporal range)

  • sector_dataset_id (Array, String, nil) (defaults to: nil) —

    filter by the sector source dataset ID

  • sector_mode (Array, String, nil) (defaults to: nil) —

    filter by the sector mode (attach, merge, union)

  • status (Array, String, nil) (defaults to: nil) —

    filter by taxonomic status (accepted, ambiguous synonym, misapplied, provisionally accepted, synonym)

  • taxonomic_group (Array, String, nil) (defaults to: nil) —

    filter by taxonomic group (see: api.checklistbank.org/vocab/taxgroup)

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

    sets the type of search to PREFIX, WHOLE_WORDS, or EXACT

  • usage_id (String, nil) (defaults to: nil) —

    Filter by usage ID

  • sort_by (String, nil) (defaults to: nil) —

    sort results by NAME, TAXONOMIC, INDEX_NAME_ID, NATIVE, or RELEVANCE

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

    sort in reverse order

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

    Offset for pagination

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

    Limit for pagination

  • verbose (Boolean) (defaults to: false) —

    Print headers to STDOUT

Returns:

  • (Array, Boolean) —

    An array of hashes



580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
 
# File 'lib/colrapi.rb', line 580

def self.nameusage_search(q: nil, authorship: nil, authorship_year: nil, dataset_id: nil, 
                          endpoint: 'nameusage/search', extinct: nil, field: nil, content: nil, issue: nil,
                          type: nil, rank: nil, min_rank: nil, max_rank: nil, environment: nil, facet: nil,
                          nomenclatural_code: nil, highest_taxon_id: nil, usage_id: nil, nomenclatural_status: nil, 
                          name_type: nil, origin: nil, secondary_source: nil, 
                          sector_mode: nil, sector_dataset_id: nil, status: nil, taxonomic_group: nil,
                          sort_by: nil, reverse: nil, offset: nil, limit: nil, verbose: false)

  # a nil dataset_id will search name usages from all datasets in ChecklistBank
  unless dataset_id.nil?
    endpoint = "dataset/#{dataset_id}/nameusage/search"
  end

  Request.new(endpoint: endpoint, q: q, authorship: authorship, authorship_year: authorship_year, 
              extinct: extinct, field: field, content: content, issue: issue, type: type,
              rank: rank, min_rank: min_rank, max_rank: max_rank, facet: facet, 
              nomenclatural_code: nomenclatural_code,environment: environment, 
              highest_taxon_id: highest_taxon_id, usage_id: usage_id, 
              name_type: name_type, nomenclatural_status: nomenclatural_status, origin: origin,
              secondary_source: secondary_source, sector_mode: sector_mode, 
              sector_dataset_id: sector_dataset_id, status: status, taxonomic_group: taxonomic_group, 
              sort_by: sort_by, reverse: reverse,  offset: offset, limit: limit, 
              verbose: verbose).perform
end

.nameusage_suggest(dataset_id, q, fuzzy: nil, min_rank: nil, max_rank: nil, sort_by: nil, reverse: nil, accepted: nil, limit: nil, verbose: false) ⇒ Hash, Boolean

Get a name usage suggestion

Parameters:

  • dataset_id (String) —

    restricts name usage search within a dataset

  • q (String) —

    A suggestion search query

  • fuzzy (Boolean, nil) (defaults to: nil) —

    Whether to include fuzzy matches for misspellings (TODO: might not actually work?)

  • min_rank (String, nil) (defaults to: nil) —

    The minimum rank to suggest

  • max_rank (String, nil) (defaults to: nil) —

    The maximum rank to suggest

  • sort_by (String, nil) (defaults to: nil) —

    The sorting order (name, taxonomic, index_name_id, native, relevance)

  • reverse (Boolean, nil) (defaults to: nil) —

    Sort in opposite order

  • accepted (Boolean, nil) (defaults to: nil) —

    Suggest only accepted names

  • verbose (Boolean) (defaults to: false) —

    Print headers to STDOUT

Returns:

  • (Hash, Boolean) —

    A a hash of name usage suggestions



620
621
622
623
624
625
 
# File 'lib/colrapi.rb', line 620

def self.nameusage_suggest(dataset_id, q, fuzzy: nil, min_rank: nil, max_rank: nil, sort_by: nil, reverse: nil,
                           accepted: nil, limit: nil, verbose: false)
  endpoint = "dataset/#{dataset_id}/nameusage/suggest"
  Request.new(endpoint: endpoint, q: q, fuzzy: fuzzy, min_rank: min_rank, max_rank: max_rank, sort_by: sort_by,
              reverse: reverse, accepted: accepted, limit: limit, verbose: verbose).perform
end

.nidx(nidx_id, subresource: nil, verbose: false) ⇒ Object

Get names index info

Parameters:

  • nidx_id (Integer) —

    a names index ID

  • subresource (String, nil) (defaults to: nil) —

    the subresource (group)



631
632
633
634
635
 
# File 'lib/colrapi.rb', line 631

def self.nidx(nidx_id, subresource: nil, verbose: false)
  endpoint = "nidx/#{nidx_id}"
  endpoint = "nidx/#{nidx_id}/#{subresource}" unless subresource.nil?
  Request.new(endpoint: endpoint, verbose: verbose).perform
end

.nidx_match(q, authorship: nil, rank: nil, code: nil, verbose: false) ⇒ Hash, Boolean

Get names index matches

Parameters:

  • q (String, nil) —

    A match query

  • authorship (String, nil) (defaults to: nil) —

    An authorship string

  • rank (String, nil) (defaults to: nil) —

    The taxonomic rank

  • code (String, nil) (defaults to: nil) —

    The nomenclatural code

  • verbose (Boolean) (defaults to: false) —

    Print headers to STDOUT

Returns:

  • (Hash, Boolean) —

    A match hash



646
647
648
649
 
# File 'lib/colrapi.rb', line 646

def self.nidx_match(q, authorship: nil, rank: nil, code: nil, verbose: false)
  endpoint = "nidx/match"
  Request.new(endpoint: endpoint, q: q, authorship: authorship, rank: rank, code: code, verbose: verbose).perform
end

.parser(subresource: nil, q: nil, verbose: false) ⇒ Array, ...

Parse a subresource

This is the generic parser wrapper. For specialized parsers, like the names, homoglyphs, idconverter, metadata,
  use the specialized parsers below like Colrapi.parser_name(). Returns a list of parsers if no subresource given.

Parameters:

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

    the type of parser to use

  • q (Array, String) (defaults to: nil) —

    a query string or array of query strings to parse

Returns:

  • (Array, Hash, Boolean) —

    An array of parsers, or a parser result hash



660
661
662
663
664
 
# File 'lib/colrapi.rb', line 660

def self.parser(subresource: nil, q: nil, verbose: false)
  endpoint = "parser"
  endpoint = "#{endpoint}/#{subresource}" unless subresource.nil?
  Request.new(endpoint: endpoint, q: q, verbose: verbose).perform
end

.parser_idconverter(mode, id, format, verbose: false) ⇒ String, ...

Encode or decode identifiers to different formats (e.g., proquints are used as stable identifiers in ChecklistBank)

Parameters:

  • mode (String) —

    encode or decode

  • id (String) —

    the identifier to convert

  • format (String) —

    the format (proquint, hex, latin29, latin32, latin36, base64)

  • verbose (Boolean) (defaults to: false) —

    Print headers to STDOUT

Returns:

  • (String, Integer, Boolean) —

    A parser result hash



674
675
676
677
 
# File 'lib/colrapi.rb', line 674

def self.parser_idconverter(mode, id, format, verbose: false)
  endpoint = "parser/idconverter/#{mode}"
  Request.new(endpoint: endpoint, id: id, format: format, verbose: verbose).perform
end

.parser_metadata(url, format: nil, verbose: false) ⇒ String, ...

Parse metadata

Parameters:

  • url (String) —

    The url to a metadata file

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

    The format of the metadata (yaml, json, eml, datacite, zenodo)

  • verbose (Boolean) (defaults to: false) —

    Print headers to STDOUT

Returns:

  • (String, Integer, Boolean) —

    A parser result hash



686
687
688
689
 
# File 'lib/colrapi.rb', line 686

def self.parser_metadata(url, format: nil, verbose: false)
  endpoint = 'parser/metadata'
  Request.new(endpoint: endpoint, url: url, format: format, verbose: verbose).perform
end

.parser_name(name, authorship: nil, rank: nil, code: nil, verbose: false) ⇒ Hash, Boolean

Parse a scientific name

Parameters:

  • name (String) —

    The scientific name to parse

  • authorship (String, nil) (defaults to: nil) —

    The authorship string for the scientific name

  • rank (String, nil) (defaults to: nil) —

    The rank of the scientific name to parse

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

    The nomenclatural code (bacterial, botanical, cultivars, phytosociological, virus, zoological)

Returns:

  • (Hash, Boolean) —

    A hash with the parsed scientific name



699
700
701
702
703
 
# File 'lib/colrapi.rb', line 699

def self.parser_name(name, authorship: nil, rank: nil, code: nil, verbose: false)
  endpoint = 'parser/name'
  Request.new(endpoint: endpoint, name: name, authorship: authorship, rank: rank, code: code,
              verbose: verbose).perform
end

.patch(dataset_id, patch_id: nil, token: nil, verbose: false) ⇒ Object

Get metadata patch

Parameters:

  • dataset_id (String) —

    The dataset id

  • token (String, nil) (defaults to: nil) —

    The authentication token from retrieved with Colrapi.user_login(user, password)



709
710
711
712
713
714
715
 
# File 'lib/colrapi.rb', line 709

def self.patch(dataset_id, patch_id: nil, token: nil, verbose: false)
  endpoint = "dataset/#{dataset_id}/patch"
  unless patch_id.nil?
    endpoint = "#{endpoint}/#{patch_id}"
  end
  Request.new(endpoint: endpoint, token: token, verbose: verbose).perform
end

.preview(project_id, token, verbose: false) ⇒ Array, Boolean

Get the latest preview release metadata (or points to the project draft dataset after the preview is released?)

(Note: you can also use 3LRC where 3 is the project_id as an ID on any endpoint with dataset_id or project_id
 to get data from the latest release candidate, or 3LR gets the latest release)

Parameters:

  • project_id (String) —

    The project id

  • token (String, nil) —

    The authentication token from retrieved with Colrapi.user_login(user, password)

  • verbose (Boolean) (defaults to: false) —

    Print headers to STDOUT

Returns:

  • (Array, Boolean) —

    An array of hashes



725
726
727
 
# File 'lib/colrapi.rb', line 725

def self.preview(project_id, token, verbose: false)
  Request.new(endpoint: "dataset/#{project_id}LRC.json", token: token, verbose: verbose).perform
end

.reference(dataset_id, reference_id: nil, subresource: nil, issue: nil, offset: nil, limit: nil, verbose: false) ⇒ Array, Boolean

Get a reference with @reference_id from dataset @dataset_id via the reference route

Parameters:

  • dataset_id (String) —

    The dataset id

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

    The reference id

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

    The reference subresource endpoint (orphans)

  • issue (Array, String) (defaults to: nil) —

    The data quality issue (api.checklistbank.org/vocab/issue)

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

    Offset for pagination

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

    Limit for pagination

  • verbose (Boolean) (defaults to: false) —

    Print headers to STDOUT

Returns:

  • (Array, Boolean) —

    An array of hashes



741
742
743
744
745
746
747
748
749
750
751
752
 
# File 'lib/colrapi.rb', line 741

def self.reference(dataset_id, reference_id: nil, subresource: nil, issue: nil, offset: nil, limit: nil,
                   verbose: false)
  endpoint = "dataset/#{dataset_id}/reference"
  if subresource == 'orphans'
    reference_id = nil
    endpoint = "#{endpoint}/orphans"
  end
  unless reference_id.nil?
    endpoint = "#{endpoint}/#{reference_id}"
  end
  Request.new(endpoint: endpoint, issue: issue, offset: offset, limit: limit, verbose: verbose).perform
end

.reviewer(dataset_id, token, verbose: false) ⇒ Object

Get reviewer info

# @return [Array, Hash, Boolean] An array of hashes

Parameters:

  • dataset_id (String) —

    The dataset id

  • token (String, nil) —

    The authentication token from retrieved with Colrapi.user_login(user, password)



760
761
762
763
 
# File 'lib/colrapi.rb', line 760

def self.reviewer(dataset_id, token, verbose: false)
  endpoint = "dataset/#{dataset_id}/reviewer"
  Request.new(endpoint: endpoint, token: token, verbose: verbose).perform
end

.sector(dataset_id, sector_id: nil, name: nil, rank: nil, modified_by: nil, broken: nil, subject_dataset_id: nil, last_synced_before: nil, mode: nil, subject: nil, min_size: nil, without_data: nil, offset: nil, limit: nil, verbose: false) ⇒ Hash, Boolean

Get sector metadata, which allows importing datasets into project subtrees

Parameters:

  • dataset_id (String) —

    The dataset id

  • sector_id (Integer, nil) (defaults to: nil) —

    The sector id

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

    The scientific name to query

  • rank (String, nil) (defaults to: nil) —

    The rank of the scientific name

  • modified_by (Integer, nil) (defaults to: nil) —

    Filter by a user id on last modified by

  • broken (Boolean, nil) (defaults to: nil) —

    Whether the decision is broken or not

  • subject_dataset_id (String, nil) (defaults to: nil) —

    The source dataset id

  • last_synced_before (Date, nil) (defaults to: nil) —

    Filter by sectors synced before this date

  • mode (String, nil) (defaults to: nil) —

    Filter by type of sector (attach, union, merge)

  • subject (Boolean, nil) (defaults to: nil) —

    TODO: what does this do? All decisions with subject=true are bare names, so maybe it checks if the subject taxon exists?

  • min_size (Integer, nil) (defaults to: nil) —

    The minimum number of records in the sector

  • without_data (Boolean, nil) (defaults to: nil) —

    Filters to empty sectors with no data synced into the project yet

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

    Offset for pagination

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

    Limit for pagination

  • verbose (Boolean) (defaults to: false) —

    Print headers to STDOUT

Returns:

  • (Hash, Boolean) —

    An hash of results



785
786
787
788
789
790
791
792
793
794
795
796
797
798
 
# File 'lib/colrapi.rb', line 785

def self.sector(dataset_id, sector_id: nil, name: nil, rank: nil, modified_by: nil, broken: nil,
                subject_dataset_id: nil, last_synced_before: nil, mode: nil, subject: nil, min_size: nil, without_data: nil,
                offset: nil, limit: nil, verbose: false)
  endpoint = "dataset/#{dataset_id}/sector"
  if sector_id.nil?
    Request.new(endpoint: endpoint, name: name, rank: rank, modified_by: modified_by, broken: broken,
                subject_dataset_id: subject_dataset_id, last_synced_before: last_synced_before, mode: mode,
                subject: subject, min_size: min_size, without_data: without_data,
                offset: offset, limit: limit, verbose: verbose).perform
  else
    endpoint = "#{endpoint}/#{sector_id}"
    Request.new(endpoint: endpoint, verbose: verbose).perform
  end
end

.sector_sync(dataset_id, sector_id: nil, attempt: nil, subresource: nil, state: nil, running: nil, offset: nil, limit: nil, verbose: false) ⇒ Hash, Boolean

Get sector sync info

Parameters:

  • dataset_id (String) —

    The dataset id

  • sector_id (Integer, nil) (defaults to: nil) —

    The sector id

  • state (Array, String, nil) (defaults to: nil) —

    The sector sync state (e.g., waiting, processing, inserting, indexing, finished, etc.)

  • running (Boolean, nil) (defaults to: nil) —

    Filter to sector syncs that are only running

  • attempt (Integer, nil) (defaults to: nil) —

    The sync attempt number for sector_id

  • subresource (String, nil) (defaults to: nil) —

    The subresource for attempt (names or tree)

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

    Offset for pagination

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

    Limit for pagination

  • verbose (Boolean) (defaults to: false) —

    Print headers to STDOUT

Returns:

  • (Hash, Boolean) —

    An hash of results



814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
 
# File 'lib/colrapi.rb', line 814

def self.sector_sync(dataset_id, sector_id: nil, attempt: nil, subresource: nil, state: nil, running: nil, offset: nil, limit: nil, verbose: false)
  endpoint = "dataset/#{dataset_id}/sector/sync"
  if sector_id.nil?
    Request.new(endpoint: endpoint, state: state, running: running, offset: offset, limit: limit,
                verbose:verbose).perform
  else
    if attempt.nil?
      endpoint = "dataset/#{dataset_id}/sector/#{sector_id}/sync"
    else
      endpoint = "dataset/#{dataset_id}/sector/#{sector_id}/sync/#{attempt}"
      endpoint = "#{endpoint}/#{subresource}" unless subresource.nil?
    end
    Request.new(endpoint: endpoint, verbose:verbose).perform
  end
end

.settings(dataset_id) ⇒ Hash, Boolean

Get the dataset settings

Parameters:

  • dataset_id (String) —

    The dataset id

Returns:

  • (Hash, Boolean) —

    A hash including the dataset settings



853
854
855
 
# File 'lib/colrapi.rb', line 853

def self.settings(dataset_id)
  Request.new(endpoint: "dataset/#{dataset_id}/settings").perform
end

.source(dataset_id, source_id: nil, not_current_only: nil, original: nil, verbose: false) ⇒ Array, ...

Get source metadata for datasets assembled into a project dataset

Parameters:

  • dataset_id (String) —

    The project dataset id

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

    The source dataset id

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

    Return only not current sources

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

    TODO: what does this do?

Returns:

  • (Array, Hash, Boolean) —

    An array of source hashes, or a hash of a source



838
839
840
841
842
843
844
845
846
 
# File 'lib/colrapi.rb', line 838

def self.source(dataset_id, source_id: nil, not_current_only: nil, original: nil, verbose: false)
  endpoint = "dataset/#{dataset_id}/source"
  if source_id.nil?
    Request.new(endpoint: endpoint, not_current_only: not_current_only, verbose: verbose).perform
  else
    endpoint = "dataset/#{dataset_id}/source/#{source_id}"
    Request.new(endpoint: endpoint, original: original, verbose: verbose).perform
  end
end

.synonym(dataset_id, synonym_id: nil, subresource: nil, offset: nil, limit: nil, verbose: false) ⇒ Array, Boolean

Get a synonym with @synonym_id from dataset @dataset_id via the synonym route

Parameters:

  • dataset_id (String) —

    The dataset id

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

    The synonym id

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

    The synonym subresource endpoint (source)

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

    Offset for pagination

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

    Limit for pagination

  • verbose (Boolean) (defaults to: false) —

    Print headers to STDOUT

Returns:

  • (Array, Boolean) —

    An array of hashes



868
869
870
871
872
873
874
875
876
877
 
# File 'lib/colrapi.rb', line 868

def self.synonym(dataset_id, synonym_id: nil, subresource: nil, offset: nil, limit: nil, verbose: false)
  endpoint = "dataset/#{dataset_id}/synonym"
  unless synonym_id.nil?
    endpoint = "#{endpoint}/#{synonym_id}"
  end
  if subresource == 'source'
    endpoint = "#{endpoint}/source"
  end
  Request.new(endpoint: endpoint, offset: offset, limit: limit, verbose: verbose).perform
end

.taxon(dataset_id, taxon_id: nil, subresource: nil, format: nil, offset: nil, limit: nil, verbose: false) ⇒ Array, Boolean

Get a taxon with @id from dataset @dataset_id via the taxon route

Parameters:

  • dataset_id (String) —

    The dataset id

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

    The taxon id

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

    The taxon subresource endpoint (classification, distribution, info, interaction, media, relation, source, synonyms, treatment, or vernacular)

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

    The format of the treatment (plain_text, markdown, xml, html, tax_pub, taxon_x, rdf)

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

    Offset for pagination

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

    Limit for pagination

  • verbose (Boolean) (defaults to: false) —

    Print headers to STDOUT

Returns:

  • (Array, Boolean) —

    An array of hashes



901
902
903
904
905
906
907
908
909
910
911
 
# File 'lib/colrapi.rb', line 901

def self.taxon(dataset_id, taxon_id: nil, subresource: nil, format: nil, offset: nil, limit: nil, verbose: false)
  endpoint = "dataset/#{dataset_id}/taxon"
  unless taxon_id.nil?
    endpoint = "#{endpoint}/#{taxon_id}"
  end

  if !subresource.nil?
    endpoint = "#{endpoint}/#{subresource}"
  end
  Request.new(endpoint: endpoint, offset: offset, format: format, limit: limit, verbose: verbose).perform
end

.taxon_ids(dataset_id, verbose: false) ⇒ Array, Boolean

Get the full list of taxon IDs for a dataset (returns 1 ID string per line, not JSON)

Parameters:

  • dataset_id (String) —

    The dataset id

Returns:

  • (Array, Boolean) —

    An array of hashes



884
885
886
 
# File 'lib/colrapi.rb', line 884

def self.taxon_ids(dataset_id, verbose: false)
  Request.new(endpoint: "dataset/#{dataset_id}/taxon/ids", verbose: verbose).perform
end

.tree(dataset_id, taxon_id: nil, children: false, offset: nil, limit: nil, verbose: false) ⇒ Array, Boolean

Get the root taxa

Parameters:

  • dataset_id (String) —

    The dataset id

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

    The taxon id

  • children (Boolean) (defaults to: false) —

    Display the children of taxon_id

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

    Offset for pagination

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

    Limit for pagination

  • verbose (Boolean) (defaults to: false) —

    Print headers to STDOUT

Returns:

  • (Array, Boolean) —

    An array of hashes



924
925
926
927
928
929
 
# File 'lib/colrapi.rb', line 924

def self.tree(dataset_id, taxon_id: nil, children: false, offset: nil, limit: nil, verbose: false)
  endpoint = "dataset/#{dataset_id}/tree"
  endpoint = "#{endpoint}/#{taxon_id}" unless taxon_id.nil?
  endpoint = "#{endpoint}/children" unless taxon_id.nil? or !children
  Request.new(endpoint: endpoint, offset: offset, limit: limit, verbose: verbose).perform
end

.user(user_id: nil, q: nil, role: nil, offset: nil, limit: nil, token: nil, verbose: false) ⇒ Array, Boolean

Get user data

Parameters:

  • user_id (Integer, nil) (defaults to: nil) —

    The user id

  • q (String, nil) (defaults to: nil) —

    The search query

  • role (String, nil) (defaults to: nil) —

    The user role (admin, editor, or reviewer)

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

    Offset for pagination

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

    Limit for pagination

  • token (String, nil) (defaults to: nil) —

    The authentication token from retrieved with Colrapi.user_login(user, password)

  • verbose (Boolean) (defaults to: false) —

    Print headers to STDOUT

Returns:

  • (Array, Boolean) —

    An array of hashes



943
944
945
946
947
948
949
950
951
952
 
# File 'lib/colrapi.rb', line 943

def self.user(user_id: nil, q: nil, role: nil, offset: nil, limit: nil, token: nil, verbose: false)
  if user_id.nil?
    endpoint = "user"
    Request.new(endpoint: endpoint, q: q, role: role, offset: offset, limit: limit, token: token,
                verbose: verbose).perform
  else
    endpoint = "user/#{user_id}"
    Request.new(endpoint: endpoint, token: token, verbose: verbose).perform
  end
end

.user_dataset(token, dataset_id: nil, origin: nil, verbose: false) ⇒ Array, Boolean

Get datasets user can access

Parameters:

  • token (String) —

    The access token from Colrapi.user_login()

  • dataset_id (String, nil) (defaults to: nil) —

    A dataset id to check

  • origin (Array, String, nil) (defaults to: nil) —

    Filter by the origin of a dataset (external, project, release, xrelease)

Returns:

  • (Array, Boolean) —

    An array of datasets, or returns a boolean if dataset_id is provided



960
961
962
963
964
965
966
967
968
 
# File 'lib/colrapi.rb', line 960

def self.user_dataset(token, dataset_id: nil, origin: nil, verbose: false)
  endpoint = "user/dataset"
  if dataset_id.nil?
    Request.new(endpoint: endpoint, token: token, origin: origin, verbose: verbose).perform
  else
    endpoint = "user/dataset/#{dataset_id}"
    Request.new(endpoint: endpoint, token: token, verbose: verbose).perform
  end
end

.user_login(user, password, verbose: false) ⇒ Object

Authenticate user and get authentication token



971
972
973
 
# File 'lib/colrapi.rb', line 971

def self.(user, password, verbose: false)
  Request.new(endpoint: "user/login", user: user, password: password, verbose: verbose).perform
end

.user_me(token, verbose: false) ⇒ Array, Boolean

Get the authenticated user

Parameters:

  • token (String, nil) —

    The authentication token from retrieved with Colrapi.user_login(user, password)

  • verbose (Boolean) (defaults to: false) —

    Print headers to STDOUT

Returns:

  • (Array, Boolean) —

    An array of hashes



981
982
983
 
# File 'lib/colrapi.rb', line 981

def self.user_me(token, verbose: false)
  Request.new(endpoint: "user/me", token: token, verbose: verbose).perform
end

.verbatim(dataset_id, verbatim_id: nil, q: nil, issue: nil, type: nil, term: nil, term_operator: nil, offset: nil, limit: nil, verbose: false) ⇒ Array, Boolean

Get verbatim data

TODO: May not work yet: github.com/CatalogueOfLife/backend/issues/1201

@param term [Array, String] Filter by term (http://api.checklistbank.org/vocab/term)
@param term_operator [String] The operator to use with term ('and' or 'or')

Parameters:

  • dataset_id (String) —

    The dataset id

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

    The verbatim id

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

    The search query string

  • issue (Array, String) (defaults to: nil) —

    Filter by data quality issue (e.g., ACCEPTED_NAME_MISSING, DUPLICATE_NAME, URL_INVALID)

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

    The file type (e.g., acef:AcceptedSpecies, col:Taxon, dwc:Taxon)

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

    Offset for pagination

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

    Limit for pagination

  • verbose (Boolean) (defaults to: false) —

    Print headers to STDOUT

Returns:

  • (Array, Boolean) —

    An array of hashes



1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
 
# File 'lib/colrapi.rb', line 1002

def self.verbatim(dataset_id, verbatim_id: nil, q: nil, issue: nil, type: nil, term: nil, term_operator: nil,
                  offset: nil, limit: nil, verbose: false)
  endpoint = "dataset/#{dataset_id}/verbatim"
  if verbatim_id.nil?
    Request.new(endpoint: endpoint, q: q, issue: issue, type: type, term: term, term_operator: term_operator,
                offset: offset, limit: limit, verbose: verbose).perform
  else
    endpoint = "#{endpoint}/#{verbatim_id}"
    Request.new(endpoint: endpoint, verbose: verbose).perform
  end
end

.vernacular(dataset_id: nil, q: nil, language: nil, offset: nil, limit: nil, verbose: false) ⇒ Hash

Get vernacular names

Parameters:

  • dataset_id (String, nil) (defaults to: nil) —

    The dataset id

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

    A vernacular name search query

  • language (String, nil) (defaults to: nil) —

    The language of the vernacular name (see: api.checklistbank.org/vocab/language)

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

    Offset for pagination

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

    Limit for pagination

  • verbose (Boolean) (defaults to: false) —

    Print headers to STDOUT

Returns:

  • (Hash) —

    A hash of vernacular results



1025
1026
1027
1028
1029
1030
1031
1032
1033
 
# File 'lib/colrapi.rb', line 1025

def self.vernacular(dataset_id: nil, q: nil, language: nil, offset: nil, limit: nil, verbose: false)
  if dataset_id.nil?
    endpoint = 'vernacular'
    Request.new(endpoint: endpoint, q: q, language: language, offset: offset, limit: limit, verbose: verbose).perform
  else
    endpoint = "dataset/#{dataset_id}/vernacular"
    Request.new(endpoint: endpoint, q: q, language: language, offset: offset, limit: limit, verbose: verbose).perform
  end
end

.version(verbose: false) ⇒ String

Get backend version

Returns:

  • (String) —

    A version string



1038
1039
1040
 
# File 'lib/colrapi.rb', line 1038

def self.version(verbose: false)
  Request.new(endpoint: 'version', verbose: verbose).perform
end

.vocab(term: nil, subresource: nil, children: false, verbose: false) ⇒ Array

Get vocab

Parameters:

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

    The vocab term

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

    The subresource which is usually the id, code, or name

  • children (Boolean) (defaults to: false) —

    Returns the geotime’s children if true

  • verbose (Boolean) (defaults to: false) —

    Print headers to STDOUT

Returns:

  • (Array) 


1050
1051
1052
1053
1054
1055
1056
 
# File 'lib/colrapi.rb', line 1050

def self.vocab(term: nil, subresource: nil, children: false, verbose: false)
  endpoint = "vocab"
  endpoint = "#{endpoint}/#{term}" unless term.nil?
  endpoint = "#{endpoint}/#{subresource}" unless term.nil? or subresource.nil?
  endpoint = "#{endpoint}/children" if children and term == "geotime"
  Request.new(endpoint: endpoint, verbose: verbose).perform
end