Module: Nasturtium

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

Defined Under Namespace

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

Constant Summary collapse

VERSION = 
"0.1.1"

Class Method Summary collapse

Methods included from Configuration

configuration, define_setting

Class Method Details

.controlled_terms(taxon_id: nil, page: nil, per_page: nil, verbose: false) ⇒ Hash, Boolean

Get controlled vocabulary terms

Parameters:

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

    If set returns controlled terms for the taxon

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

    The results page number

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

    The results limit

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

    Print headers to STDOUT

Returns:

  • (Hash, Boolean) —

    A hash of controlled terms results



40
41
42
43
44
45
46
47
 
# File 'lib/nasturtium.rb', line 40

def self.controlled_terms(taxon_id: nil, page: nil, per_page: nil, verbose: false)
  if taxon_id.nil?
    endpoint = 'controlled_terms'
  else
    endpoint = 'controlled_terms/for_taxon'
  end
  Request.new(endpoint: endpoint, taxon_id: taxon_id, page: page, per_page: per_page, verbose: verbose).perform
end

.identifications(id: nil, current_taxon: nil, own_observation: nil, is_change: nil, taxon_active: nil, observation_taxon_active: nil, rank: nil, observation_rank: nil, user_id: nil, user_login: nil, current: nil, category: nil, place_id: nil, quality_grade: nil, taxon_id: nil, observation_taxon_id: nil, iconic_taxon_id: nil, observation_iconic_taxon_id: nil, rank_lowest: nil, rank_highest: nil, observation_rank_lowest: nil, observation_rank_highest: nil, without_taxon_id: nil, without_observation_taxon_id: nil, before: nil, after: nil, observation_created_before: nil, observation_created_after: nil, observed_before: nil, observed_after: nil, id_below: nil, id_above: nil, only_id: nil, order: nil, order_by: nil, page: nil, per_page: nil, verbose: false) ⇒ Hash, Boolean

Get identifications

Parameters:

  • id (String, Integer, nil) (defaults to: nil) —

    An array of identification IDs

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

    The identification taxon is the same as its observation’s taxon

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

    The identification was added by th observer

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

    The identification was created as a result of a taxon change

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

    The identification’s taxon is currently an active taxon

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

    The observation’s taxon is currently an active taxon

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

    Filter by a comma-separated list of taxonomic ranks on the identification

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

    Filter by a comma-separated list of taxonomic ranks on the observation

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

    Filter by a comma-separated list of user IDs

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

    Filter by a comma-separated list of user logins

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

    The most recent identification on an observation by a user

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

    The type of identification (improving, supporting, leading)

  • place_id (String, Integer, nil) (defaults to: nil) —

    Filter by a comma-separated list of place IDs

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

    Filter by a comma-separated list of quality grades (casual, needs_id, research)

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

    Filter by a comma-separated list of taxon IDs on the identification

  • observation_taxon_id (String, Integer, nil) (defaults to: nil) —

    Filter by a comma-separated list of taxon IDs on the observation

  • iconic_taxon_id (String, Integer, nil) (defaults to: nil) —

    Filter by a comma-separated list of iconic taxon IDs on the identification

  • observation_iconic_taxon_id (String, Integer, nil) (defaults to: nil) —

    Filter by a comma-separated list of iconic taxon IDs on the observation

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

    The identification’s taxon must have this rank or higher

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

    The identification’s taxon must have this rank or lower

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

    The observation’s taxon must have this rank or higher

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

    The observation’s taxon must have this rank or lower

  • without_taxon_id (String, Integer, nil) (defaults to: nil) —

    Exclude this comma-separated list of identification taxon IDs and their descendants

  • without_observation_taxon_id (String, Integer, nil) (defaults to: nil) —

    Exclude this comma-separated list of observation taxon IDs and their descendants

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

    Identified before this time (d2)

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

    Identified after this time (d1)

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

    Observation record was created before this time (observation_created_d2)

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

    Observation record was created after this time (observation_created_d1)

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

    Observed before this time (observed_d2)

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

    Observed after this time (observed_d1)

  • id_below (String, Integer, nil) (defaults to: nil) —

    The identification ID must be below the provided value

  • id_above (String, Integer, nil) (defaults to: nil) —

    The identification ID must be above the provided value

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

    Only return record IDs

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

    Ascending or descending sort order (asc, desc)

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

    The parameter to sort by (created_at, id)

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

    The results page number

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

    The results limit

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

    Print headers to STDOUT

Returns:

  • (Hash, Boolean) —

    A hash of identification results



91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
 
# File 'lib/nasturtium.rb', line 91

def self.identifications(id: nil, current_taxon: nil, own_observation: nil, is_change: nil,
                         taxon_active: nil, observation_taxon_active: nil, rank: nil, observation_rank: nil,
                         user_id: nil, user_login: nil, current: nil, category: nil, place_id: nil,
                         quality_grade: nil, taxon_id: nil, observation_taxon_id: nil, iconic_taxon_id: nil,
                         observation_iconic_taxon_id: nil, rank_lowest: nil, rank_highest: nil,
                         observation_rank_lowest: nil, observation_rank_highest: nil, without_taxon_id: nil,
                         without_observation_taxon_id: nil, before: nil, after: nil,
                         observation_created_before: nil, observation_created_after: nil, observed_before: nil,
                         observed_after: nil, id_below: nil, id_above: nil, only_id: nil, order: nil, order_by: nil,
                         page: nil, per_page: nil, verbose: false)
  endpoint = 'identifications'
  Request.new(endpoint: endpoint,
              id: id,
              current_taxon: current_taxon,
              own_observation: own_observation,
              is_change: is_change,
              taxon_active: taxon_active,
              observation_taxon_active: observation_taxon_active,
              rank: rank,
              observation_rank: observation_rank,
              user_id: user_id,
              user_login: ,
              current: current,
              category: category,
              place_id: place_id,
              quality_grade: quality_grade,
              taxon_id: taxon_id,
              observation_taxon_id: observation_taxon_id,
              iconic_taxon_id: iconic_taxon_id,
              observation_iconic_taxon_id: observation_iconic_taxon_id,
              rank_lowest: rank_lowest,
              rank_highest: rank_highest,
              observation_rank_lowest: observation_rank_lowest,
              observation_rank_highest: observation_rank_highest,
              without_taxon_id: without_taxon_id,
              without_observation_taxon_id: without_observation_taxon_id,
              before: before,
              after: after,
              observation_created_before: observation_created_before,
              observation_created_after: observation_created_after,
              observed_before: observed_before,
              observed_after: observed_after,
              id_below: id_below,
              id_above: id_above,
              only_id: only_id,
              order: order,
              order_by: order_by,
              page: page,
              per_page: per_page,
              verbose: verbose).perform
end

.mapping(asset_type, zoom_level, x, y, return_json: false, color: nil, style: nil, tile_size: nil, q: nil, search_on: nil, id: nil, not_id: nil, acc: nil, captive: nil, endemic: nil, geo: nil, identified: nil, introduced: nil, mappable: nil, native: nil, out_of_range: nil, pcid: nil, photos: nil, popular: nil, sounds: nil, taxon_is_active: nil, threatened: nil, verifiable: nil, licensed: nil, photo_licensed: nil, photo_license: nil, sound_license: nil, ofv_datatype: nil, place_id: nil, project_id: nil, rank: nil, site_id: nil, taxon_id: nil, without_taxon_id: nil, taxon_name: nil, user_id: nil, user_login: nil, ident_user_id: nil, day: nil, month: nil, year: nil, term_id: nil, without_term_id: nil, term_value_id: nil, without_term_value_id: nil, acc_below: nil, acc_below_or_unknown: nil, acc_above: nil, before: nil, observed_on: nil, after: nil, created_before: nil, created_on: nil, created_after: nil, unobserved_by_user_id: nil, apply_project_rules_for: nil, conservation_status: nil, conservation_status_authority: nil, conservation_status_iucn: nil, geoprivacy: nil, taxon_geoprivacy: nil, rank_lowest: nil, rank_highest: nil, iconic_taxa: nil, id_below: nil, id_above: nil, identifications: nil, latitude: nil, longitude: nil, radius: nil, ne_latitude: nil, ne_longitude: nil, sw_latitude: nil, sw_longitude: nil, list_id: nil, not_in_project: nil, not_matching_project_rules_for: nil, quality_grade: nil, updated_since: nil, viewer_id: nil, reviewed: nil, locale: nil, preferred_place_id: nil, only_id: nil, ttl: nil, order: nil, order_by: nil, page: nil, per_page: nil, headers: false, verbose: false) ⇒ Binary, Hash

Get map tiling assets for observations

Mapping-specific parameters:

@param asset_type [String] The type of asset to return [colored_heatmap, grid, heatmap, points, places, taxon_places, taxon_ranges]
@param return_json [Boolean] Whether to return UTFGRid (only use with asset_types: colored_heatmap, grid, heatmap, points)
@param color [String, nil] A color to use in map creation (e.g., blue, #0000ff)
@param style [String, nil] The map tile style (geotilegrid, possibly others)
@param tile_size [Integer, nil] The map tile size in pixels

All of the parameters for filtering observations are also available:

@param q [String, nil] An observation properties search query
@param search_on [String, nil] Observation properties to search on (names, tags, description, place)
@param id [String, Integer, nil] A comma-separated list of observation IDs
@param not_id [String, Integer, nil] A comma-separated list of observation IDs that must not be included
@param acc [Boolean, nil] Filter by whether the positional accuracy/coordinate uncertainty was specified
@param captive [Boolean, nil] Filter on whether it was captive/cultivated observations
@param endemic [Boolean, nil] Filter on whether observations were of taxa endemic to their location
@param geo [Boolean, nil] Filter to only georeferenced observations
@param identified [Boolean, nil] Filter to only observations with community identifications
@param introduced [Boolean, nil] Filter to observations of taxa that were introduced to their location
@param mappable [Boolean, nil] Filter to only observations that show on map tiles
@param native [Boolean, nil] Filter to only observations of taxa native tot heir location
@param out_of_range [Boolean, nil] Filter to only observations made in locations outside the taxon's known ranges
@param pcid [Boolean, nil] Filter to observations identified by a curator of a project
@param photos [Boolean, nil] Filter to observations with photos
@param popular [Boolean, nil] Filter to only observations that have been favorited by at least 1 user
@param sounds [Boolean, nil] Filter to observations with sounds
@param taxon_is_active [Boolean, nil] Filter to observations of active taxon concepts
@param threatened [Boolean, nil] Filter to observations of taxa that are threatened at their location
@param verifiable [Boolean, nil] Filter by observations with a quality_grade=needs_id,research
@param licensed [Boolean, nil] Filter by observations with a license
@param photo_licensed [Boolean, nil] License attribute of at least one photo in an observation must not be nil
@param license [String, nil] Filter by a comma-separated list of licenses (cc-by,cc-by-nc,cc-by-nd,cc-by-sa,cc-by-nc-nd,cc-by-nc-sa,cc0)
@param photo_license [String, nil] Filter by a comma-separated list of photo licenses (cc-by,cc-by-nc,cc-by-nd,cc-by-sa,cc-by-nc-nd,cc-by-nc-sa,cc0)
@param sound_license [String, nil] Filter by a comma-separated list of sound licenses (cc-by,cc-by-nc,cc-by-nd,cc-by-sa,cc-by-nc-nd,cc-by-nc-sa,cc0)
@param ofv_datatype [String, nil] Filter by a comma-separated list of datatypes that the observation must include  # TODO: does it take arrays?
@param place_id [String, Integer, nil] Filter by a comma-separated list of place_ids
@param project_id [String, Integer, nil] Filter by a comma-separated list of project_ids
@param rank [String, nil] Filter by an array of taxon ranks
@param site_id [String, Integer, nil] Filter by a comma-separated list of site_ids
@param taxon_id [String, Integer, nil] Filter by a comma-separated list of taxon_ids and their descendants
@param without_taxon_id [String, Integer, nil] Exclude a comma-separated list of taxon_ids and their descendants
@param taxon_name [String, Integer, nil] Filter by a comma-separated list of scientific or common names
@param user_id [String, Integer nil] Filter by observations made by a comma-separated list of user_ids
@param user_login [String, nil] Filter by a comma-separated list of user_logins
@param ident_user_id [String, Integer, nil] Filter by observations identified by a particular user_id
@param day [String, Integer, nil] Filter on a comma-separated list of days
@param month [String, Integer, nil] Filter on a comma-separated list of months
@param year [String, Integer, nil] Filter on a comma-separated list of years
@param term_id [String, Integer, nil] Filter on a comma-separated list of term_ids
@param without_term_id String, Integer, nil] Exclude on a comma-separated list of term_ids
@param term_value_id [String, Integer, nil] Filter on annotations made with this controlled value ID; must be used with term_id
@param without_term_value_id [String, Integer, nil] Exclude on annotations made with this controlled value ID
@param acc_above [String, nil] Positional accuracy must be above value
@param acc_below [String, nil] Positional accuracy must be below value
@param acc_below_or_unknown [String, nil] Positional accuracy must be below value or unknown
@param before [String, nil] Must have been observed on or before this date (d2)
@param after [String, nil] Must have been observed on or after this date (d1)
@param observed_on [String, nil] Must have been observed on this date
@param created_before [String, nil] Must have been created on or before this date (created_d2)
@param created_on [String, nil] Must have been created on this date
@param created_after [String, nil] Must have been created on or before this date (created_d1)
@param unobserved_by_user_id [String, nil] Taxon must be unobserved by the provided user_id
@param apply_project_rules_for [String, nil] Must match rules of the provided project_id
@param conservation_status [String, nil] Taxon must have this conservation status (cs) code, use with place_id to make location-specific
@param conservation_status_authority [String, nil] Taxon must have the conservation status from the provided authority (csa), use with place_id to make location-specific
@param conservation_status_iucn [String, nil] Taxon must have the provided conservation status from the IUCN, use with place_id to make location-specific
@param geoprivacy [String, nil] Filter by a comma-separated list of geoprivacy settings (obscured, obscured_private, open)
@param taxon_geoprivacy [String, nil] Filter by a comma-separated list of geoprivacy settings (obscured, obscured_private, open) of the most conservative geoprivacy associated with one of the taxa proposed in the current identifications
@param rank_lowest [String, nil] Taxon rank must be less than or equal to provided rank
@param rank_highest [String, nil] Taxon rank must be greater than or equal to provided rank
@param iconic_taxa [String, nil] Filter by taxa with the provided iconic taxon (Actinopterygii, Animalia, Amphibia, Arachnida, Aves, Chromista, Fungi, Insecta, Mammalia, Mollusca, Repitilia, Plantae, Protozoa, unknown)
@param id_below [String, Integer, nil] Most have an observation ID below the provided value
@param id_above [String, Integer, nil] Most have an observation ID above the provided value
@param identifications [String, nil] Filter by identifications status (most_agree, some_agree, most_disagree)
@param latitude [Double, nil] Filter by observations within a {radius} kilometer circle around the provided latitude coordinate (lat)
@param longitude [Double, nil] Filter by observations within a {radius} kilometer circle around the provided longitude coordinate (lng)
@param radius [String, Integer, Double] Filter by observations within the provided radius in kilometers
@param ne_latitude [Double, nil] Filter by observations within provided (nelat) bounding box (ne_latitude, ne_longitude, sw_latitude, sw_longitude)
@param ne_longitude [Double, nil] Filter by observations within provided (nelng) bounding box (ne_latitude, ne_longitude, sw_latitude, sw_longitude)
@param sw_latitude [Double, nil] Filter by observations within provided (swlat) bounding box (ne_latitude, ne_longitude, sw_latitude, sw_longitude)
@param sw_longitude [Double, nil] Filter by observations within provided (swlng) bounding box (ne_latitude, ne_longitude, sw_latitude, sw_longitude)
@param list_id [Integer, nil] Taxon must bin the list with the provided ID
@param not_in_project [String, nil] Observation must not be in the provided project_id or slug
@param not_matching_project_rules_for [String, nil] Must not match the rules of the provided project_id or slug
@param quality_grade [String, nil] Filter by observation quality grade (casual, needs_id, research)
@param updated_since [String, nil] Filter by observations updated since the provided time
@param reviewed [Boolean, nil] Observations have been reviewed by viewer_id
@param viewer_id [String, nil] Use with reviewed boolean to filter by observations reviewed by the provided viewer_id
@param locale [String, nil] Locale preference for taxon common names (e.g., en-US)
@param preferred_place_id [Integer, nil] Place of preference for regional taxon common names
@param ttl [String, Integer, nil] Set the Cache-Control HTTP header with a max-age value to cache the request on iNaturalist serers and within the client
@param only_id [Boolean, nil] Only return record IDs

Returns:

  • (Binary, Hash) —

    Returns binary png images of map tiles unless return_json is true



238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
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/nasturtium.rb', line 238

def self.mapping(asset_type, zoom_level, x, y, return_json: false, color: nil, style: nil, tile_size: nil, 
  q: nil, search_on: nil, id: nil, not_id: nil, acc: nil, captive: nil,
  endemic: nil, geo: nil, identified: nil, introduced: nil, mappable: nil, native: nil,
  out_of_range: nil, pcid: nil, photos: nil, popular: nil, sounds: nil, taxon_is_active: nil,
  threatened: nil, verifiable: nil, licensed: nil, photo_licensed: nil,
  photo_license: nil, sound_license: nil, ofv_datatype: nil, place_id: nil, project_id: nil,
  rank: nil, site_id: nil, taxon_id: nil, without_taxon_id: nil, taxon_name: nil, user_id: nil,
  user_login: nil, ident_user_id: nil, day: nil, month: nil, year: nil, term_id: nil,
  without_term_id: nil, term_value_id: nil, without_term_value_id: nil, acc_below: nil,
  acc_below_or_unknown: nil, acc_above: nil, before: nil, observed_on: nil,
  after: nil, created_before: nil, created_on: nil, created_after: nil,
  unobserved_by_user_id: nil, apply_project_rules_for: nil, conservation_status: nil,
  conservation_status_authority: nil, conservation_status_iucn: nil, geoprivacy: nil,
  taxon_geoprivacy: nil, rank_lowest: nil, rank_highest: nil, iconic_taxa: nil,
  id_below: nil, id_above: nil, identifications: nil, latitude: nil, longitude: nil,
  radius: nil, ne_latitude: nil, ne_longitude: nil, sw_latitude: nil, sw_longitude: nil,
  list_id: nil, not_in_project: nil, not_matching_project_rules_for: nil, quality_grade: nil,
  updated_since: nil, viewer_id: nil, reviewed: nil, locale: nil, preferred_place_id: nil,
  only_id: nil, ttl: nil, order: nil, order_by: nil, page: nil, per_page: nil, headers: false,
  verbose: false)

  if !color.nil? and color.include? '#'
    color = color.gsub('#', '%23')
  end

  endpoint = ''
  if ['colored_heatmap', 'grid', 'heatmap', 'points'].include? asset_type
    if return_json
      endpoint = "#{asset_type}/#{zoom_level}/#{x}/#{y}.grid.json"
    else
      endpoint = "#{asset_type}/#{zoom_level}/#{x}/#{y}.png"
    end
  elsif asset_type == 'places'
    endpoint = "places/#{place_id}/#{zoom_level}/#{x}/#{y}.png"
    if place_id.nil?
      raise "place_id must be provided"
    end
  elsif asset_type == 'taxon_places'
    endpoint = "taxon_places/#{taxon_id}/#{zoom_level}/#{x}/#{y}.png"
    if taxon_id.nil?
      raise "taxon_id must be provided"
    end
  elsif asset_type == 'taxon_ranges'
    endpoint = "taxon_ranges/#{taxon_id}/#{zoom_level}/#{x}/#{y}.png"
    if taxon_id.nil?
      raise "taxon_id must be provided"
    end
  else
    raise "Invalid asset_type: #{asset_type} (must be one of: colored_heatmap, grid, heatmap, points, places, taxon_places, taxon_ranges)" 
  end

  Request.new(endpoint: endpoint,
    color: color,
    style: style,
    tile_size: tile_size,
    q: q,
    search_on: search_on,
    id: id,
    not_id: not_id,
    acc: acc,
    captive: captive,
    endemic: endemic,
    geo: geo,
    identified: identified,
    introduced: introduced,
    mappable: mappable,
    native: native,
    out_of_range: out_of_range,
    pcid: pcid,
    photos: photos,
    popular: popular,
    sounds: sounds,
    taxon_is_active: taxon_is_active,
    threatened: threatened,
    verifiable: verifiable,
    licensed: licensed,
    photo_licensed: photo_licensed,
    photo_license: photo_license,
    sound_license: sound_license,
    ofv_datatype: ofv_datatype,
    place_id: place_id,
    project_id: project_id,
    rank: rank,
    site_id: site_id,
    taxon_id: taxon_id,
    without_taxon_id: without_taxon_id,
    taxon_name: taxon_name,
    user_id: user_id,
    user_login: ,
    ident_user_id: ident_user_id,
    day: day,
    month: month,
    year: year,
    term_id: term_id,
    without_term_id: without_term_id,
    term_value_id:  term_value_id,
    without_term_value_id: without_term_value_id,
    acc_below: acc_below,
    acc_below_or_unknown: acc_below_or_unknown,
    acc_above: acc_above,
    before: before,
    observed_on: observed_on,
    after: after,
    created_before: created_before,
    created_on: created_on,
    created_after: created_after,
    unobserved_by_user_id: unobserved_by_user_id,
    apply_project_rules_for: apply_project_rules_for,
    conservation_status: conservation_status,
    conservation_status_authority: conservation_status_authority,
    conservation_status_iucn: conservation_status_iucn,
    geoprivacy: geoprivacy,
    taxon_geoprivacy: taxon_geoprivacy,
    rank_lowest: rank_lowest,
    rank_highest: rank_highest,
    iconic_taxa: iconic_taxa,
    id_below: id_below,
    id_above: id_above,
    identifications: identifications,
    latitude: latitude,
    longitude: longitude,
    radius: radius,
    ne_latitude: ne_latitude,
    ne_longitude: ne_longitude,
    sw_latitude: sw_latitude,
    sw_longitude: sw_longitude,
    list_id: list_id,
    not_in_project: not_in_project,
    not_matching_project_rules_for: not_matching_project_rules_for,
    quality_grade: quality_grade,
    updated_since: updated_since,
    viewer_id: viewer_id,
    reviewed: reviewed,
    locale: locale,
    preferred_place_id: preferred_place_id,
    only_id: only_id,
    ttl: ttl,
    order: order,
    order_by: order_by,
    page: page,
    per_page: per_page,
    headers: headers,
    verbose: verbose).perform
end

.observations(subresource: nil, q: nil, search_on: nil, id: nil, not_id: nil, acc: nil, captive: nil, endemic: nil, geo: nil, identified: nil, introduced: nil, mappable: nil, native: nil, out_of_range: nil, pcid: nil, photos: nil, popular: nil, sounds: nil, taxon_is_active: nil, threatened: nil, verifiable: nil, licensed: nil, photo_licensed: nil, photo_license: nil, sound_license: nil, ofv_datatype: nil, place_id: nil, project_id: nil, rank: nil, site_id: nil, taxon_id: nil, without_taxon_id: nil, taxon_name: nil, user_id: nil, user_login: nil, ident_user_id: nil, day: nil, month: nil, year: nil, term_id: nil, without_term_id: nil, term_value_id: nil, without_term_value_id: nil, acc_below: nil, acc_below_or_unknown: nil, acc_above: nil, before: nil, observed_on: nil, after: nil, created_before: nil, created_on: nil, created_after: nil, unobserved_by_user_id: nil, apply_project_rules_for: nil, conservation_status: nil, conservation_status_authority: nil, conservation_status_iucn: nil, geoprivacy: nil, taxon_geoprivacy: nil, rank_lowest: nil, rank_highest: nil, iconic_taxa: nil, id_below: nil, id_above: nil, identifications: nil, latitude: nil, longitude: nil, radius: nil, ne_latitude: nil, ne_longitude: nil, sw_latitude: nil, sw_longitude: nil, list_id: nil, not_in_project: nil, not_matching_project_rules_for: nil, quality_grade: nil, updated_since: nil, viewer_id: nil, reviewed: nil, locale: nil, preferred_place_id: nil, only_id: nil, ttl: nil, order: nil, order_by: nil, page: nil, per_page: nil, headers: false, verbose: false) ⇒ Hash, Boolean

Get observations

Note: use the subresource parameter to access these subresource endpoints which share the same parameters as /observations:
  /observations/histogram
  /observations/identifiers
  /observations/observers
  /observations/popular_field_values
  /observations/species_counts

Parameters:

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

    Access a subresource endpoint of observations (histogram, identifiers, observers, popular_field_values, species_counts)

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

    An observation properties search query

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

    Observation properties to search on (names, tags, description, place)

  • id (String, Integer, nil) (defaults to: nil) —

    A comma-separated list of observation IDs

  • not_id (String, Integer, nil) (defaults to: nil) —

    A comma-separated list of observation IDs that must not be included

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

    Filter by whether the positional accuracy/coordinate uncertainty was specified

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

    Filter on whether it was captive/cultivated observations

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

    Filter on whether observations were of taxa endemic to their location

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

    Filter to only georeferenced observations

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

    Filter to only observations with community identifications

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

    Filter to observations of taxa that were introduced to their location

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

    Filter to only observations that show on map tiles

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

    Filter to only observations of taxa native tot heir location

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

    Filter to only observations made in locations outside the taxon’s known ranges

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

    Filter to observations identified by a curator of a project

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

    Filter to observations with photos

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

    Filter to only observations that have been favorited by at least 1 user

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

    Filter to observations with sounds

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

    Filter to observations of active taxon concepts

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

    Filter to observations of taxa that are threatened at their location

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

    Filter by observations with a quality_grade=needs_id,research

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

    Filter by observations with a license

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

    License attribute of at least one photo in an observation must not be nil

  • license (String, nil) —

    Filter by a comma-separated list of licenses (cc-by,cc-by-nc,cc-by-nd,cc-by-sa,cc-by-nc-nd,cc-by-nc-sa,cc0)

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

    Filter by a comma-separated list of photo licenses (cc-by,cc-by-nc,cc-by-nd,cc-by-sa,cc-by-nc-nd,cc-by-nc-sa,cc0)

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

    Filter by a comma-separated list of sound licenses (cc-by,cc-by-nc,cc-by-nd,cc-by-sa,cc-by-nc-nd,cc-by-nc-sa,cc0)

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

    Filter by a comma-separated list of datatypes that the observation must include # TODO: does it take arrays?

  • place_id (String, Integer, nil) (defaults to: nil) —

    Filter by a comma-separated list of place_ids

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

    Filter by a comma-separated list of project_ids

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

    Filter by an array of taxon ranks

  • site_id (String, Integer, nil) (defaults to: nil) —

    Filter by a comma-separated list of site_ids

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

    Filter by a comma-separated list of taxon_ids and their descendants

  • without_taxon_id (String, Integer, nil) (defaults to: nil) —

    Exclude a comma-separated list of taxon_ids and their descendants

  • taxon_name (String, Integer, nil) (defaults to: nil) —

    Filter by a comma-separated list of scientific or common names

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

    Filter by observations made by a comma-separated list of user_ids

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

    Filter by a comma-separated list of user_logins

  • ident_user_id (String, Integer, nil) (defaults to: nil) —

    Filter by observations identified by a particular user_id

  • day (String, Integer, nil) (defaults to: nil) —

    Filter on a comma-separated list of days

  • month (String, Integer, nil) (defaults to: nil) —

    Filter on a comma-separated list of months

  • year (String, Integer, nil) (defaults to: nil) —

    Filter on a comma-separated list of years

  • term_id (String, Integer, nil) (defaults to: nil) —

    Filter on a comma-separated list of term_ids

  • without_term_id (defaults to: nil) —

    String, Integer, nil] Exclude on a comma-separated list of term_ids

  • term_value_id (String, Integer, nil) (defaults to: nil) —

    Filter on annotations made with this controlled value ID; must be used with term_id

  • without_term_value_id (String, Integer, nil) (defaults to: nil) —

    Exclude on annotations made with this controlled value ID

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

    Positional accuracy must be above value

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

    Positional accuracy must be below value

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

    Positional accuracy must be below value or unknown

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

    Must have been observed on or before this date (d2)

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

    Must have been observed on or after this date (d1)

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

    Must have been observed on this date

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

    Must have been created on or before this date (created_d2)

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

    Must have been created on this date

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

    Must have been created on or before this date (created_d1)

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

    Taxon must be unobserved by the provided user_id

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

    Must match rules of the provided project_id

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

    Taxon must have this conservation status (cs) code, use with place_id to make location-specific

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

    Taxon must have the conservation status from the provided authority (csa), use with place_id to make location-specific

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

    Taxon must have the provided conservation status from the IUCN, use with place_id to make location-specific

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

    Filter by a comma-separated list of geoprivacy settings (obscured, obscured_private, open)

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

    Filter by a comma-separated list of geoprivacy settings (obscured, obscured_private, open) of the most conservative geoprivacy associated with one of the taxa proposed in the current identifications

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

    Taxon rank must be less than or equal to provided rank

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

    Taxon rank must be greater than or equal to provided rank

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

    Filter by taxa with the provided iconic taxon (Actinopterygii, Animalia, Amphibia, Arachnida, Aves, Chromista, Fungi, Insecta, Mammalia, Mollusca, Repitilia, Plantae, Protozoa, unknown)

  • id_below (String, Integer, nil) (defaults to: nil) —

    Most have an observation ID below the provided value

  • id_above (String, Integer, nil) (defaults to: nil) —

    Most have an observation ID above the provided value

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

    Filter by identifications status (most_agree, some_agree, most_disagree)

  • latitude (Double, nil) (defaults to: nil) —

    Filter by observations within a radius kilometer circle around the provided latitude coordinate (lat)

  • longitude (Double, nil) (defaults to: nil) —

    Filter by observations within a radius kilometer circle around the provided longitude coordinate (lng)

  • radius (String, Integer, Double) (defaults to: nil) —

    Filter by observations within the provided radius in kilometers

  • ne_latitude (Double, nil) (defaults to: nil) —

    Filter by observations within provided (nelat) bounding box (ne_latitude, ne_longitude, sw_latitude, sw_longitude)

  • ne_longitude (Double, nil) (defaults to: nil) —

    Filter by observations within provided (nelng) bounding box (ne_latitude, ne_longitude, sw_latitude, sw_longitude)

  • sw_latitude (Double, nil) (defaults to: nil) —

    Filter by observations within provided (swlat) bounding box (ne_latitude, ne_longitude, sw_latitude, sw_longitude)

  • sw_longitude (Double, nil) (defaults to: nil) —

    Filter by observations within provided (swlng) bounding box (ne_latitude, ne_longitude, sw_latitude, sw_longitude)

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

    Taxon must bin the list with the provided ID

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

    Observation must not be in the provided project_id or slug

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

    Must not match the rules of the provided project_id or slug

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

    Filter by observation quality grade (casual, needs_id, research)

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

    Filter by observations updated since the provided time

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

    Observations have been reviewed by viewer_id

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

    Use with reviewed boolean to filter by observations reviewed by the provided viewer_id

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

    Locale preference for taxon common names (e.g., en-US)

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

    Place of preference for regional taxon common names

  • ttl (String, Integer, nil) (defaults to: nil) —

    Set the Cache-Control HTTP header with a max-age value to cache the request on iNaturalist serers and within the client

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

    Only return record IDs

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

    Ascending or descending sort order (asc, desc)

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

    The parameter to sort by (observed_on, species_guess, votes, id, created_at)

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

    The results page number

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

    The results limit

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

    Return headers instead of body

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

    Print headers to STDOUT

Returns:

  • (Hash, Boolean) —

    A hash with observation results



671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
 
# File 'lib/nasturtium.rb', line 671

def self.observations(subresource: nil, q: nil, search_on: nil, id: nil, not_id: nil, acc: nil, captive: nil,
                      endemic: nil, geo: nil, identified: nil, introduced: nil, mappable: nil, native: nil,
                      out_of_range: nil, pcid: nil, photos: nil, popular: nil, sounds: nil, taxon_is_active: nil,
                      threatened: nil, verifiable: nil, licensed: nil, photo_licensed: nil,
                      photo_license: nil, sound_license: nil, ofv_datatype: nil, place_id: nil, project_id: nil,
                      rank: nil, site_id: nil, taxon_id: nil, without_taxon_id: nil, taxon_name: nil, user_id: nil,
                      user_login: nil, ident_user_id: nil, day: nil, month: nil, year: nil, term_id: nil,
                      without_term_id: nil, term_value_id: nil, without_term_value_id: nil, acc_below: nil,
                      acc_below_or_unknown: nil, acc_above: nil, before: nil, observed_on: nil,
                      after: nil, created_before: nil, created_on: nil, created_after: nil,
                      unobserved_by_user_id: nil, apply_project_rules_for: nil, conservation_status: nil,
                      conservation_status_authority: nil, conservation_status_iucn: nil, geoprivacy: nil,
                      taxon_geoprivacy: nil, rank_lowest: nil, rank_highest: nil, iconic_taxa: nil,
                      id_below: nil, id_above: nil, identifications: nil, latitude: nil, longitude: nil,
                      radius: nil, ne_latitude: nil, ne_longitude: nil, sw_latitude: nil, sw_longitude: nil,
                      list_id: nil, not_in_project: nil, not_matching_project_rules_for: nil, quality_grade: nil,
                      updated_since: nil, viewer_id: nil, reviewed: nil, locale: nil, preferred_place_id: nil,
                      only_id: nil, ttl: nil, order: nil, order_by: nil, page: nil, per_page: nil, headers: false,
                      verbose: false)
  endpoint = 'observations'
  endpoint = "#{endpoint}/#{subresource}" unless subresource.nil?

  Request.new(endpoint: endpoint,
              q: q,
              search_on: search_on,
              id: id,
              not_id: not_id,
              acc: acc,
              captive: captive,
              endemic: endemic,
              geo: geo,
              identified: identified,
              introduced: introduced,
              mappable: mappable,
              native: native,
              out_of_range: out_of_range,
              pcid: pcid,
              photos: photos,
              popular: popular,
              sounds: sounds,
              taxon_is_active: taxon_is_active,
              threatened: threatened,
              verifiable: verifiable,
              licensed: licensed,
              photo_licensed: photo_licensed,
              photo_license: photo_license,
              sound_license: sound_license,
              ofv_datatype: ofv_datatype,
              place_id: place_id,
              project_id: project_id,
              rank: rank,
              site_id: site_id,
              taxon_id: taxon_id,
              without_taxon_id: without_taxon_id,
              taxon_name: taxon_name,
              user_id: user_id,
              user_login: ,
              ident_user_id: ident_user_id,
              day: day,
              month: month,
              year: year,
              term_id: term_id,
              without_term_id: without_term_id,
              term_value_id:  term_value_id,
              without_term_value_id: without_term_value_id,
              acc_below: acc_below,
              acc_below_or_unknown: acc_below_or_unknown,
              acc_above: acc_above,
              before: before,
              observed_on: observed_on,
              after: after,
              created_before: created_before,
              created_on: created_on,
              created_after: created_after,
              unobserved_by_user_id: unobserved_by_user_id,
              apply_project_rules_for: apply_project_rules_for,
              conservation_status: conservation_status,
              conservation_status_authority: conservation_status_authority,
              conservation_status_iucn: conservation_status_iucn,
              geoprivacy: geoprivacy,
              taxon_geoprivacy: taxon_geoprivacy,
              rank_lowest: rank_lowest,
              rank_highest: rank_highest,
              iconic_taxa: iconic_taxa,
              id_below: id_below,
              id_above: id_above,
              identifications: identifications,
              latitude: latitude,
              longitude: longitude,
              radius: radius,
              ne_latitude: ne_latitude,
              ne_longitude: ne_longitude,
              sw_latitude: sw_latitude,
              sw_longitude: sw_longitude,
              list_id: list_id,
              not_in_project: not_in_project,
              not_matching_project_rules_for: not_matching_project_rules_for,
              quality_grade: quality_grade,
              updated_since: updated_since,
              viewer_id: viewer_id,
              reviewed: reviewed,
              locale: locale,
              preferred_place_id: preferred_place_id,
              only_id: only_id,
              ttl: ttl,
              order: order,
              order_by: order_by,
              page: page,
              per_page: per_page,
              headers: headers,
              verbose: verbose).perform
end

.places_autocomplete(q, order_by: nil, per_page: nil, verbose: false) ⇒ Hash, Boolean

Suggest places

Parameters:

  • q (String) —

    A place name must start with this query

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

    The parameter to sort by (area) # TODO: iNaturalist bug? doesn’t seem to affect sorting in the API?

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

    The results limit

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

    Print headers to STDOUT

Returns:

  • (Hash, Boolean) —

    A hash with suggest places results



402
403
404
405
 
# File 'lib/nasturtium.rb', line 402

def self.places_autocomplete(q, order_by: nil, per_page: nil, verbose: false)
  endpoint = "places/autocomplete"
  Request.new(endpoint: endpoint, q: q, order_by: order_by, per_page: per_page, verbose: verbose).perform
end

.places_id(id, admin_level: nil, verbose: false) ⇒ Hash, Boolean

Get places

Parameters:

  • id (String, Integer) —

    A comma-separated list of place IDs

  • admin_level (String, Integer, nil) (defaults to: nil) —

    A comma-separated list of admin levels (-10: continent, 0: country, 10: state, 20: county, 30: town, 100: park)

Returns:

  • (Hash, Boolean) —

    A hash with places results



389
390
391
392
 
# File 'lib/nasturtium.rb', line 389

def self.places_id(id, admin_level: nil, verbose: false)
  endpoint = "places/#{id}"
  Request.new(endpoint: endpoint, admin_level: admin_level, verbose: verbose).perform
end

.places_nearby(ne_latitude, ne_longitude, sw_latitude, sw_longitude, name: nil, verbose: false) ⇒ Hash, Boolean

api.inaturalist.org/v1/places/nearby?nelat=40.346036&nelng=-87.951568&swlat=39.935393&swlng=-88.628846 Get nearby places

Parameters:

  • ne_latitude (Double, nil) —

    Get nearby places within provided (nelat) bounding box (ne_latitude, ne_longitude, sw_latitude, sw_longitude)

  • ne_longitude (Double, nil) —

    Get nearby places within provided (nelng) bounding box (ne_latitude, ne_longitude, sw_latitude, sw_longitude)

  • sw_latitude (Double, nil) —

    Get nearby places within provided (swlat) bounding box (ne_latitude, ne_longitude, sw_latitude, sw_longitude)

  • sw_longitude (Double, nil) —

    Get nearby places within provided (swlng) bounding box (ne_latitude, ne_longitude, sw_latitude, sw_longitude)

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

    Place name must match this value # TODO: iNaturalist bug? you can’t provide the last word of a name (e.g., River Bend Forest works, but River Bend Forest Preserve doesn’t work)

  • per_page (Integer, nil) —

    The results limit

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

    Print headers to STDOUT

Returns:

  • (Hash, Boolean) —

    A hash with suggest places results



419
420
421
422
 
# File 'lib/nasturtium.rb', line 419

def self.places_nearby(ne_latitude, ne_longitude, sw_latitude, sw_longitude, name: nil, verbose: false)
  endpoint = "places/nearby"
  Request.new(endpoint: endpoint, ne_latitude: ne_latitude, ne_longitude: ne_longitude, sw_latitude: sw_latitude, sw_longitude: sw_longitude, name: name, verbose: verbose).perform
end

.posts(login: nil, project_id: nil, parent_id: nil, page: nil, per_page: nil, verbose: false) ⇒ Array, Boolean

Get journal posts

Parameters:

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

    Filter by user login

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

    Filter by project ID

  • parent_id (String, Integer, nil) (defaults to: nil) —

    Filter by parent ID

  • page (String, Integer, nil) (defaults to: nil)
  • per_page (String, Integer, nil) (defaults to: nil)
  • verbose (Boolean) (defaults to: false) —

    Print headers to STDOUT

Returns:

  • (Array, Boolean) —

    An array of journal posts



435
436
437
438
 
# File 'lib/nasturtium.rb', line 435

def self.posts(login: nil, project_id: nil, parent_id: nil, page: nil, per_page: nil, verbose: false)
  endpoint = "posts"
  Request.new(endpoint: endpoint, login: , project_id: project_id, parent_id: parent_id, page: page, per_page: per_page, verbose: verbose).perform
end

.project_members(id, page: nil, per_page: nil, verbose: false) ⇒ Hash, Boolean

Get project members

Parameters:

  • id (String, Integer) —

    The project ID

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

    The results page number

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

    The results limit

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

    Print headers to STDOUT

Returns:

  • (Hash, Boolean) —

    A hash with search results



482
483
484
485
 
# File 'lib/nasturtium.rb', line 482

def self.project_members(id, page: nil, per_page: nil, verbose: false)
  endpoint = "projects/#{id}/members"
  Request.new(endpoint: endpoint, page: page, per_page: per_page, verbose: verbose).perform
end

.projects(q: nil, autocomplete: nil, id: nil, not_id: nil, latitude: nil, longitude: nil, radius: nil, place_id: nil, featured: nil, noteworthy: nil, site_id: nil, rule_details: nil, type: nil, member_id: nil, has_params: nil, has_posts: nil, page: nil, per_page: nil, order_by: nil, verbose: false) ⇒ Hash, Boolean

TODO: Add tests Get projects

Parameters:

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

    Project name must begin with query string

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

    Returns projects that start with the search q

  • id (String, Integer, nil) (defaults to: nil) —

    Project must have this ID

  • not_id (String, Integer, nil) (defaults to: nil) —

    Project must not have this ID

  • latitude (Double, nil) (defaults to: nil) —

    Filter by projects within a radius kilometer circle around the provided latitude coordinate (lat)

  • longitude (Double, nil) (defaults to: nil) —

    Filter by projects within a radius kilometer circle around the provided longitude coordinate (lng)

  • radius (String, Integer, Double) (defaults to: nil) —

    Filter by projects within the provided radius in kilometers

  • place_id (String, Integer, nil) (defaults to: nil) —

    Filter by a comma-separated list of place_ids

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

    Filter by marked featured for the relevant site

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

    Filter by marked noteworthy for the relevant site

  • site_id (String, Integer, nil) (defaults to: nil) —

    The site ID that applies to featured and noteworthy, defaults to site of the authenticated user or the main iNaturalist site

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

    Return more details about the project rules

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

    Filter by project type [collection, umbrella]

  • member_id (String, Integer, nil) (defaults to: nil) —

    Filter by projects that include a user ID

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

    Must have search parameter requirements

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

    Project must have posts

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

    The results page number

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

    The results limit

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

    The parameter to sort by (observed_on, species_guess, votes, id, created_at)

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

    Print headers to STDOUT

Returns:

  • (Hash, Boolean) —

    A hash with search results



465
466
467
468
469
470
471
472
 
# File 'lib/nasturtium.rb', line 465

def self.projects(q: nil, autocomplete: nil, id: nil, not_id: nil, latitude: nil, longitude: nil, radius: nil, place_id: nil, featured: nil, noteworthy: nil, site_id: nil, rule_details: nil, type: nil, member_id: nil, has_params: nil, has_posts: nil, page: nil, per_page: nil, order_by: nil, verbose: false)
  if autocomplete
    endpoint = "projects/autocomplete"
  else
    endpoint = "projects"
  end
  Request.new(endpoint: endpoint, q: q, id: id, not_id: not_id, latitude: latitude, longitude: longitude, radius: radius, place_id: place_id, featured: featured, noteworthy: noteworthy, site_id: site_id, rule_details: rule_details, type: type, member_id: member_id, has_params: has_params, has_posts: has_posts, page: page, per_page: per_page, order_by: order_by, verbose: verbose).perform
end

.search(q: nil, sources: nil, place_id: nil, preferred_place_id: nil, locale: nil, page: nil, per_page: nil, verbose: false) ⇒ Hash, Boolean

Search places, projects, taxa, users

Parameters:

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

    A search query

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

    Type of record to search (places, projects, taxa, users)

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

    Filter to an array of place_ids (TODO: place_id is an array in the documentation but doesn’t seem to work even with their example?)

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

    Place of preference for regional taxon common names

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

    Locale preference for taxon common names (e.g., en-US)

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

    The results page number

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

    The results limit

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

    Print headers to STDOUT

Returns:

  • (Hash, Boolean) —

    A hash with search results



499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
 
# File 'lib/nasturtium.rb', line 499

def self.search(q: nil, sources: nil, place_id: nil, preferred_place_id: nil, locale: nil, page: nil, per_page: nil,
                verbose: false)
  endpoint = 'search'
  Request.new(
    endpoint: endpoint,
    q: q,
    sources: sources,
    place_id: place_id,
    preferred_place_id: preferred_place_id,
    locale: locale,
    page: page,
    per_page: per_page,
    verbose: verbose
  ).perform
end

.taxa(id: nil, q: nil, is_active: nil, taxon_id: nil, parent_id: nil, rank: nil, rank_level: nil, id_above: nil, id_below: nil, locale: nil, only_id: nil, all_names: nil, preferred_place_id: nil, order: nil, order_by: nil, page: nil, per_page: nil, verbose: false) ⇒ Hash, Boolean

Taxon search

Parameters:

  • id (String, Integer, nil) (defaults to: nil) —

    A taxon ID or comma-separated array of taxon IDs

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

    A search query

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

    Filter to taxa with active taxon concepts

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

    Filter by a comma-separated array of taxon_ids

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

    Filter by a taxon parent_id

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

    Filter by an array of taxon ranks

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

    Filter by taxon rank level (e.g., 70 for kingdom)

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

    ID must be greater than value

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

    ID must be below value

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

    Place of preference for regional taxon common names

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

    Locale preference for taxon common names (e.g., en-US)

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

    Only return record IDs

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

    Include all taxon names in the response

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

    Ascending or descending sort order (asc, desc)

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

    The parameter to sort by

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

    The results page number

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

    The results limit

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

    Print headers to STDOUT

Returns:

  • (Hash, Boolean) —

    A hash with search results



806
807
808
809
810
811
812
813
814
815
816
817
818
819
 
# File 'lib/nasturtium.rb', line 806

def self.taxa(id: nil, q: nil, is_active: nil, taxon_id: nil, parent_id: nil, rank: nil, rank_level: nil,
              id_above: nil, id_below: nil, locale: nil, only_id: nil, all_names: nil, preferred_place_id: nil,
              order: nil, order_by: nil, page: nil, per_page: nil, verbose: false)
  if id.nil?
    endpoint = 'taxa'
    Request.new(endpoint: endpoint, q: q, is_active: is_active, taxon_id: taxon_id, parent_id: parent_id, rank: rank,
                rank_level: rank_level, id_above: id_above, id_below: id_below, locale: locale, only_id: only_id,
                all_names: all_names, preferred_place_id: preferred_place_id, order: order, order_by: order_by,
                page: page, per_page: per_page, verbose: verbose).perform
  else
    endpoint = "taxa/#{id}"
    Request.new(endpoint: endpoint, verbose: verbose).perform
  end
end

.taxa_autocomplete(q: nil, is_active: nil, taxon_id: nil, rank: nil, rank_level: nil, locale: nil, preferred_place_id: nil, all_names: nil, per_page: nil, verbose: false) ⇒ Hash, Boolean

Taxon suggest

Parameters:

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

    A suggest query

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

    Suggest only taxa with active taxon concepts

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

    Filter by comma-separated taxon IDs

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

    Filter by an array of taxon ranks

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

    Filter by taxon rank level (e.g., 70 for kingdom)

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

    Locale preference for taxon common names (e.g., en-US)

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

    Place of preference for regional taxon common names

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

    Include all taxon names in the response

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

    The results limit

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

    Print headers to STDOUT

Returns:

  • (Hash, Boolean) —

    A hash with search results



835
836
837
838
839
840
841
 
# File 'lib/nasturtium.rb', line 835

def self.taxa_autocomplete(q: nil, is_active: nil, taxon_id: nil, rank: nil, rank_level: nil, locale: nil,
                           preferred_place_id: nil, all_names: nil, per_page: nil, verbose: false)
  endpoint = 'taxa/autocomplete'
  Request.new(endpoint: endpoint, q: q, is_active: is_active, taxon_id: taxon_id, rank: rank, rank_level: rank_level,
              locale: locale, preferred_place_id: preferred_place_id, all_names: all_names, per_page: per_page,
              verbose: verbose).perform
end

.user(id, verbose: false) ⇒ Hash, Boolean

Get user

Parameters:

  • id (Integer) —

    The user ID

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

    Print headers to STDOUT

Returns:

  • (Hash, Boolean) —

    A hash with user results



521
522
523
524
 
# File 'lib/nasturtium.rb', line 521

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

.user_autocomplete(q, project_id: nil, per_page: nil, verbose: false) ⇒ Hash, Boolean

Get user suggestions

Parameters:

  • q (String) —

    The username must begin with this query

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

    Only show members of this project ID

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

    The results limit

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

    Print headers to STDOUT

Returns:

  • (Hash, Boolean) —

    A hash with user results



561
562
563
564
 
# File 'lib/nasturtium.rb', line 561

def self.user_autocomplete(q, project_id: nil, per_page: nil, verbose: false)
  endpoint = "users/autocomplete"
  Request.new(endpoint: endpoint, q: q, project_id: project_id, per_page: per_page, verbose: verbose).perform
end

.user_me(verbose: false) ⇒ Hash, Boolean

Get logged in user

Parameters:

  • id (Integer) —

    The user ID

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

    Print headers to STDOUT

Returns:

  • (Hash, Boolean) —

    A hash with user results



532
533
534
535
 
# File 'lib/nasturtium.rb', line 532

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

.user_projects(id, rule_details: nil, project_type: nil, page: nil, per_page: nil, verbose: false) ⇒ Hash, Boolean

Get user’s projects

Parameters:

  • id (Integer) —

    The user ID

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

    Return more details about project rules

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

    Filter by project type (collection, contest, traditional, umbrella)

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

    The results page number

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

    The results limit

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

    Print headers to STDOUT

Returns:

  • (Hash, Boolean) —

    A hash with user results



547
548
549
550
551
 
# File 'lib/nasturtium.rb', line 547

def self.user_projects(id, rule_details: nil, project_type: nil, page: nil, per_page: nil, verbose: false)
  endpoint = "users/#{id}/projects"
  Request.new(endpoint: endpoint, rule_details: rule_details, project_type: project_type,
              page: page, per_page: per_page, verbose: verbose).perform
end