Nasturtium
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 objectGet controlled vocabulary terms for a taxon
Nasturtium.controlled_terms(taxon_id: 1) # => MultiJson objectIdentifications
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 objectGet identifications in which the taxon is the same as the observation's taxon
Nasturtium.identifications(current_taxon: true) # => MultiJson objectGet identifications which were added by the observer
Nasturtium.identifications(own_observation: true) # => MultiJson objectGet identifications by taxonomic rank
Nasturtium.identifications(rank: 'suborder') # => MultiJson objectGet identifications with the rank species and the observation rank variety:
Nasturtium.identifications(rank: 'species', observation_rank: 'variety') # => MultiJson objectGet identifications by a user_id:
Nasturtium.identifications(user_id: '20717') # => MultiJson objectGet identifications by category:
Nasturtium.identifications(category: 'improving') # => MultiJson objectGet identifications by quality grade:
Nasturtium.identifications(quality_grade: 'research') # => MultiJson objectGet identifications by taxon_id:
Nasturtium.identifications(taxon_id: 42196) # => MultiJson objectMapping
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 objectGet observations with positional accuracy/coordinate uncertainty specified
Nasturtium.observations(acc: true) # => MultiJson objectGet captive/cultivated observations
Nasturtium.observations(captive: true) # => MultiJson objectExclude captive/cultivated observations
Nasturtium.observations(captive: false) # => MultiJson objectGet observations in which the taxon is endemic to their location
Nasturtium.observations(endemic: true) # => MultiJson objectGet observations that are georeferenced
Nasturtium.observations(geo: true) # => MultiJson objectGet observations that have been identified
Nasturtium.observations(identified: true) # => MultiJson objectGet observations in which the taxon has been introduced in their location
Nasturtium.observations(introduced: true) # => MultiJson objectGet observations that show on map tiles
Nasturtium.observations(mappable: true) # => MultiJson objectGet observations in which the taxon is native in their location
Nasturtium.observations(native: true) # => MultiJson objectGet observations in which the taxon was observed outside of their known range
Nasturtium.observations(out_of_range: true) # => MultiJson objectGet observations with photos
Nasturtium.observations(photos: true) # => MultiJson objectGet observations that have been favorited by at least 1 user
Nasturtium.observations(popular: true) # => MultiJson objectGet observations with sounds
Nasturtium.observations(sounds: true) # => MultiJson objectGet observations in which the taxon concept is active
Nasturtium.observations(taxon_is_active: true) # => MultiJson objectGet observations in which the taxon is threatened in their location
Nasturtium.observations(threatened: true) # => MultiJson objectGet observations with a quality_grade of needs_id or research
Nasturtium.observations(verifiable: true) # => MultiJson objectGet observations that have a cc0 license
Nasturtium.observations(license: 'cc0') # => MultiJson objectGet observations that have a license
Nasturtium.observations(licensed: true) # => MultiJson objectGet observations that have a cc0 photo license
Nasturtium.observations(photo_license: 'cc0') # => MultiJson objectGet observations in which at least 1 photo has a license
Nasturtium.observations(photo_licensed: true) # => MultiJson objectGet observations by a place_id
Nasturtium.observations(place_id: 26) # => MultiJson objectGet observations from a project_id
Nasturtium.observations(project_id: 22499) # => MultiJson objectGet observations by a taxonomic rank
Nasturtium.observations(rank: 'subspecies') # => MultiJson objectGet observations by an iNaturalist network website site_id
Nasturtium.observations(site_id: 2) # => MultiJson objectGet observations with a cc0 licensed sound recording
Nasturtium.observations(sound_license: 'cc0') # => MultiJson objectGet observations by a taxon_id
Nasturtium.observations(taxon_id: '522193') # => MultiJson objectGet observations by a taxon_name
Nasturtium.observations(taxon_name: 'Nasturtium floridanum') # => MultiJson objectGet observations by a user_id
Nasturtium.observations(user_id: '20717') # => MultiJson objectGet observations by a user_login
Nasturtium.observations(user_login: 'debpaul') # => MultiJson objectGet observations by a date
Nasturtium.observations(year: 2020, month: 3, day: 15) # => MultiJson objectGet observations that have a controlled vocabulary term
Nasturtium.observations(term_id: 1) # => MultiJson objectGet 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 objectPlaces autocomplete
Get suggested place name autocompletions
Nasturtium.places_autocomplete('Kickapoo Rail Trail') # => MultiJson objectPlaces 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 objectPosts
Get journal posts:
Nasturtium.posts # => MultiJson objectGet journal posts for parent_id:
Nasturtium.posts(parent_id: 1, page: 1, per_page: 10) # => MultiJson objectGet journal posts for project_id:
Nasturtium.posts(project_id: 42768) # => MultiJson objectGet journal posts for a user:
Nasturtium.posts(login: 'loarie') # => MultiJson objectProjects
Search projects with query term, Illinois:
Nasturtium.projects(q: 'Illinois') # => MultiJson objectGet a project by ID
Nasturtium.projects(id: 22499) # => MultiJson objectSearch for projects within 5 km of 40.11136254505831, -88.2460817474295
Nasturtium.projects(latitude: 40.11136254505831, longitude: -88.2460817474295, radius: 5) # => MultiJson objectGet projects with place_id or with place_id as a place ancestor
Nasturtium.projects(place_id: 35) # => MultiJson objectGet featured projects on iNaturalist México
Nasturtium.projects(featured: true, site_id: 2) # => MultiJson objectGet noteworthy projects on iNaturalist
Nasturtium.projects(noteworthy: true, site_id: 1) # => MultiJson objectGet projects that include user_id as a member
Nasturtium.projects(member_id: 477) # => MultiJson objectGet projects with journal posts
Nasturtium.projects(has_posts: true) # => MultiJson objectProject 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 objectTaxa
Search and fetch taxa with a comma-separted list of IDs:
Nasturtium.taxa(id: '1,2') # => MultiJson objectSearch and fetch taxa:
Nasturtium.taxa(q: 'Danaus plexippus', rank: 'species') # => MultiJson objectFetch taxa ordered by greatest observations count:
Nasturtium.taxa(rank: 'species', order: 'desc', order_by: 'observations_count') # => MultiJson objectTaxa 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 objectInclude all names for each suggested taxon:
Nasturtium.taxa_autocomplete(q: 'Sinapis', rank: 'genus,species,subspecies', per_page: 5, all_names: true) # => MultiJson objectGet 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 objectUser
Get a user by ID
Nasturtium.user(20717) # => MultiJson objectUser autocomplete
Suggest a user by autocomplete
Nasturtium.user_autocomplete('debpau') # => MultiJson objectUser projects
Get a user's projects of type collection
Nasturtium.user_projects(20717, project_type: 'collection') # => MultiJson objectDevelopment
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 MIT license.
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.