Project

nasturtium

0.0
The project is in a healthy, maintained state
Nasturtium is a low-level wrapper around the iNaturalist API.
2005
2006
2007
2008
2009
2010
2011
2012
2013
2014
2015
2016
2017
2018
2019
2020
2021
2022
2023
2024
 Dependencies

Development

~> 3.3, >= 3.3.6
~> 2.1, >= 2.1.4
~> 13.0, >= 13.0.1
~> 3.3, >= 3.3.6
~> 6.0
~> 3.18

Runtime

 Project Readme

Nasturtium

Nasturtium Logo

This is a Ruby wrapper on the iNaturalist API. Code follow the spirit/approach of the Gem serrano, and indeed much of the wrapping utility is copied 1:1 from that repo, thanks @sckott.

Installation

Add this line to your application's Gemfile:

gem 'nasturtium'

And then execute:

$ bundle install

Or install it yourself as:

$ gem install nasturtium

Usage

Controlled vocabulary terms

Get controlled vocabulary terms

Nasturtium.controlled_terms #  => MultiJson object

Get controlled vocabulary terms for a taxon

Nasturtium.controlled_terms(taxon_id: 1) #  => MultiJson object

Identifications

These are just some examples. For a complete list view the tests for examples or the API documentation.

Get an identification by ID

Nasturtium.identifications(id: 342040114) #  => MultiJson object

Get identifications in which the taxon is the same as the observation's taxon

Nasturtium.identifications(current_taxon: true) #  => MultiJson object

Get identifications which were added by the observer

Nasturtium.identifications(own_observation: true) #  => MultiJson object

Get identifications by taxonomic rank

Nasturtium.identifications(rank: 'suborder') #  => MultiJson object

Get identifications with the rank species and the observation rank variety:

Nasturtium.identifications(rank: 'species', observation_rank: 'variety') #  => MultiJson object

Get identifications by a user_id:

Nasturtium.identifications(user_id: '20717') #  => MultiJson object

Get identifications by category:

Nasturtium.identifications(category: 'improving') #  => MultiJson object

Get identifications by quality grade:

Nasturtium.identifications(quality_grade: 'research') #  => MultiJson object

Get identifications by taxon_id:

Nasturtium.identifications(taxon_id: 42196) #  => MultiJson object

Mapping

Get a grid map tile for the turkey vulture at zoom level 2 for coordinates (0, 1):

Nasturtium.mapping('grid', 2, 0, 1, style: 'geotilegrid', tile_size: 512, taxon_id: 4756)

Get a colored_heatmap map tile for the turkey vulture at zoom level 2 for coordinates (0, 1):

Nasturtium.mapping('colored_heatmap', 2, 0, 1, tile_size: 512, taxon_id: 4756, color: '#00ff00')

Get a points map tile for the turkey vulture at zoom level 2 for coordinates (0, 0):

Nasturtium.mapping('points', 2, 0, 0, tile_size: 512, taxon_id: 4756, color: '#00ff00')

Get a points map tile for the turkey vulture at zoom level 2 for coordinates (0, 0):

Nasturtium.mapping('grid', 2, 0, 1, taxon_id: 4756, return_json: true)

Get the taxon_places map for turkey vultures:

Nasturtium.mapping('taxon_places', 2, 0, 1, taxon_id: 4756)

Get the taxon_ranges map for turkey vultures:

Nasturtium.mapping('taxon_ranges', 2, 0, 1, taxon_id: 4756)

Get the places map for turkey vultures in place 35:

Nasturtium.mapping('places', 2, 0, 0, place_id: 35, taxon_id: 4756, tile_size: 512)

Observations

These are just some examples. For a complete list view the tests for examples or the API documentation.

Get an observation by ID

Nasturtium.observations(id: '150842485') #  => MultiJson object

Get observations with positional accuracy/coordinate uncertainty specified

Nasturtium.observations(acc: true) #  => MultiJson object

Get captive/cultivated observations

Nasturtium.observations(captive: true) #  => MultiJson object

Exclude captive/cultivated observations

Nasturtium.observations(captive: false) #  => MultiJson object

Get observations in which the taxon is endemic to their location

Nasturtium.observations(endemic: true) #  => MultiJson object

Get observations that are georeferenced

Nasturtium.observations(geo: true) #  => MultiJson object

Get observations that have been identified

Nasturtium.observations(identified: true) #  => MultiJson object

Get observations in which the taxon has been introduced in their location

Nasturtium.observations(introduced: true) #  => MultiJson object

Get observations that show on map tiles

Nasturtium.observations(mappable: true) #  => MultiJson object

Get observations in which the taxon is native in their location

Nasturtium.observations(native: true) #  => MultiJson object

Get observations in which the taxon was observed outside of their known range

Nasturtium.observations(out_of_range: true) #  => MultiJson object

Get observations with photos

Nasturtium.observations(photos: true) #  => MultiJson object

Get observations that have been favorited by at least 1 user

Nasturtium.observations(popular: true) #  => MultiJson object

Get observations with sounds

Nasturtium.observations(sounds: true) #  => MultiJson object

Get observations in which the taxon concept is active

Nasturtium.observations(taxon_is_active: true) #  => MultiJson object

Get observations in which the taxon is threatened in their location

Nasturtium.observations(threatened: true) #  => MultiJson object

Get observations with a quality_grade of needs_id or research

Nasturtium.observations(verifiable: true) #  => MultiJson object

Get observations that have a cc0 license

Nasturtium.observations(license: 'cc0') #  => MultiJson object

Get observations that have a license

Nasturtium.observations(licensed: true) #  => MultiJson object

Get observations that have a cc0 photo license

Nasturtium.observations(photo_license: 'cc0') #  => MultiJson object

Get observations in which at least 1 photo has a license

Nasturtium.observations(photo_licensed: true) #  => MultiJson object

Get observations by a place_id

Nasturtium.observations(place_id: 26) #  => MultiJson object

Get observations from a project_id

Nasturtium.observations(project_id: 22499) #  => MultiJson object

Get observations by a taxonomic rank

Nasturtium.observations(rank: 'subspecies') #  => MultiJson object

Get observations by an iNaturalist network website site_id

Nasturtium.observations(site_id: 2) #  => MultiJson object

Get observations with a cc0 licensed sound recording

Nasturtium.observations(sound_license: 'cc0') #  => MultiJson object

Get observations by a taxon_id

Nasturtium.observations(taxon_id: '522193') #  => MultiJson object

Get observations by a taxon_name

Nasturtium.observations(taxon_name: 'Nasturtium floridanum') #  => MultiJson object

Get observations by a user_id

Nasturtium.observations(user_id: '20717') #  => MultiJson object

Get observations by a user_login

Nasturtium.observations(user_login: 'debpaul') #  => MultiJson object

Get observations by a date

Nasturtium.observations(year: 2020, month: 3, day: 15) #  => MultiJson object

Get observations that have a controlled vocabulary term

Nasturtium.observations(term_id: 1) #  => MultiJson object

Get observations that have controlled vocabulary term 1 and controlled vocabulary value 2

Nasturtium.observations(term_id: 1, term_value_id: 2)

Get observations with positional accuracy above 100 meters and below 200 meters

Nasturtium.observations(acc_above: 100, acc_below: 200)

Get observations with open geoprivacy

Nasturtium.observations(geoprivacy: 'open')

Get observations with a taxonomic rank above genus and below phylum

Nasturtium.observations(rank_highest: 'genus', rank_lowest: 'phylum')

Get observations in which most people agree on the identification

Nasturtium.observations(identifications: 'most_agree')

Get observations with research quality grade identifications

Nasturtium.observations(quality_grade: 'research')

Get observations within a 1 km radius of 45.703259, -85.552406

@ne_lat = 40.084300
@sw_lat = 40.075877
@ne_lng = -88.198636
@sw_lng = -88.210169
Nasturtium.observations(latitude: 45.703259, longitude: -85.552406, radius: 1)

Get observations within a bounding box

@ne_lat = 40.084300
@sw_lat = 40.075877
@ne_lng = -88.198636
@sw_lng = -88.210169
Nasturtium.observations(ne_latitude: @ne_lat, ne_longitude: @ne_lng, sw_longitude: @sw_lat, sw_latitude: @sw_lng)

Search for observations with the query Parastratiosphecomyia

Nasturtium.observations(q: 'Parastratiosphecomyia')

Search for observations with Meadowbrook in a place name

Nasturtium.observations(q: 'Meadowbrook', search_on: 'place')

Search for observations with blue in a tag name

Nasturtium.observations(q: 'blue', search_on: 'tags')

Search for observations with blue in the description

Nasturtium.observations(q: 'blue', search_on: 'description')

Search for observations with grizzly in the names

Nasturtium.observations(q: 'grizzly', search_on: 'names')

Places

Get places by ID with an admin_level of 100

Nasturtium.places_id(1000, admin_level: 100) #  => MultiJson object

Places autocomplete

Get suggested place name autocompletions

Nasturtium.places_autocomplete('Kickapoo Rail Trail') #  => MultiJson object

Places nearby

Get place names nearby within a bounding box and that include the string Meadowbrook

@ne_lat = 40.084300
@sw_lat = 40.075877
@ne_lng = -88.198636
@sw_lng = -88.210169
Nasturtium.places_nearby(@ne_lat, @ne_lng, @sw_lat, @sw_lng, name: "Meadowbrook") #  => MultiJson object

Posts

Get journal posts:

Nasturtium.posts #  => MultiJson object

Get journal posts for parent_id:

Nasturtium.posts(parent_id: 1, page: 1, per_page: 10) #  => MultiJson object

Get journal posts for project_id:

Nasturtium.posts(project_id: 42768) #  => MultiJson object

Get journal posts for a user:

Nasturtium.posts(login: 'loarie') #  => MultiJson object

Projects

Search projects with query term, Illinois:

Nasturtium.projects(q: 'Illinois') #  => MultiJson object

Get a project by ID

Nasturtium.projects(id: 22499) #  => MultiJson object

Search for projects within 5 km of 40.11136254505831, -88.2460817474295

Nasturtium.projects(latitude: 40.11136254505831, longitude: -88.2460817474295, radius: 5) #  => MultiJson object

Get projects with place_id or with place_id as a place ancestor

Nasturtium.projects(place_id: 35) #  => MultiJson object

Get featured projects on iNaturalist México

Nasturtium.projects(featured: true, site_id: 2) #  => MultiJson object

Get noteworthy projects on iNaturalist

Nasturtium.projects(noteworthy: true, site_id: 1) #  => MultiJson object

Get projects that include user_id as a member

Nasturtium.projects(member_id: 477) #  => MultiJson object

Get projects with journal posts

Nasturtium.projects(has_posts: true) #  => MultiJson object

Project members

Get the members of project_id 733

Nasturtium.project_members(733, page: 1, per_page: 10)

Search

Search places, projects, taxa, or users:

Nasturtium.search(q: 'Quercus', sources: 'taxa') #  => MultiJson object

Taxa

Search and fetch taxa with a comma-separted list of IDs:

Nasturtium.taxa(id: '1,2') #  => MultiJson object

Search and fetch taxa:

Nasturtium.taxa(q: 'Danaus plexippus', rank: 'species') #  => MultiJson object

Fetch taxa ordered by greatest observations count:

Nasturtium.taxa(rank: 'species', order: 'desc', order_by: 'observations_count') #  => MultiJson object

Taxa autocomplete

Get suggested taxa names for a query Sinapis at ranks genus,species,subspecies with a limit of 5 suggestions:

Nasturtium.taxa_autocomplete(q: 'Sinapis', rank: 'genus,species,subspecies', per_page: 5) #  => MultiJson object

Include all names for each suggested taxon:

Nasturtium.taxa_autocomplete(q: 'Sinapis', rank: 'genus,species,subspecies', per_page: 5, all_names: true) #  => MultiJson object

Get common names by the language at preferred_place_id which adds a preferred_common_name key (use Nasturtium.places_autocomplete to lookup place_id's):

Nasturtium.taxa_autocomplete(q: 'Danaus plexippus', preferred_place_id: 6903, rank: 'species') #  => MultiJson object

User

Get a user by ID

Nasturtium.user(20717) #  => MultiJson object

User autocomplete

Suggest a user by autocomplete

Nasturtium.user_autocomplete('debpau') #  => MultiJson object

User projects

Get a user's projects of type collection

Nasturtium.user_projects(20717, project_type: 'collection') #  => MultiJson object

Development

After checking out the repo, run bin/setup to install dependencies. Then, run rake test to run the tests. You can also run bin/console for an interactive prompt that will allow you to experiment.

To install this gem onto your local machine, run bundle exec rake install. To release a new version, update the version number in version.rb, and then run bundle exec rake release, which will create a git tag for the version, push git commits and the created tag, and push the .gem file to rubygems.org.

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/SpeciesFileGroup/nasturtium. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the code of conduct.

License

The gem is available as open source under the terms of the NCSA/Illinois.

Code of Conduct

Everyone interacting in the Nasturtium project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the code of conduct.