iNaturalist

Supported technology/Online Database

inaturalist.org

Platform Gundi v2
Type Pull integration
Data Events
Direction Data provider

Setup You, in the portal

iNaturalist sends wildlife sightings from your projects or area to EarthRanger through Gundi. Gundi checks iNaturalist on a schedule, and each sighting shows up as an event on the map, with its photos attached.

What you'll receive

We add details here as we confirm what iNaturalist sends. If you know something we're missing, let us know.

Positions No
Alerts and events Yes. Each sighting becomes an inat_observation event (you can pick another event type), titled with the species' common name after the prefix "iNat: ". When a sighting changes in iNaturalist, Gundi updates its event, for sightings uploaded up to 150 days ago (Max age (days)). See iNaturalist Event Type.
Sensor readings No. Each event carries the species and common name, taxon rank, conservation status, a Wikipedia link, quality grade, place, observer, whether it was captive, whether the location is hidden, and a link to the sighting on iNaturalist.
Photos and files Yes. Up to 3 photos per sighting are attached to the event, in iNaturalist's order. You can set 0 to 50 with Photos per sighting, or turn photos off with Include photos. Photos arrive shortly after the event.
Past data Yes. The first time, Gundi loads 3 days of sightings; set 1 to 7 with Default number of days to load. After that, each check covers changes since the last one. To load older sightings, run Backfill iNaturalist Observations (up to 3,650 days, no photos). Each check sends at most 150 new events; set up to 1,000 with New events per run.

How this integration works

This is a pull integration. Gundi checks the data provider for new data on a schedule, using the account details you enter in the Route, and passes what it finds on to your destination.

Who's involved

  • You create the Route in Gundi and enter your provider account details, or give them to Gundi support when the setup badge says so.
  • The data provider keeps your account and devices active.
  • Your destination, for example EarthRanger, is where the data shows up.
  • Gundi support helps only when the setup badge at the top of this page says so.

Historical data

When you first connect, Gundi fetches a limited amount of past data. How far back it goes depends on the integration and is shown under "Past data" above.

When data doesn't show up

Check your Route Activity Logs first: wrong account details and provider outages show up there. Then check with the provider that your devices are reporting.

How often data arrives

Gundi checks on a schedule. Where we know how often, it's shown under "Data Pull Frequency" on this page. New data arrives after the next check, plus the time the device takes to upload it to the provider.

Prerequisites

iNaturalist

To integrate iNaturalist with Gundi, you will need either:

  • iNaturalist Project IDs, or
  • iNaturalist Taxa IDs and a bounding box for the search area

Identifying the Project ID

The Project ID can be either a numeric value or a slug. You can find the slug by:

Navigating to the desired project on iNaturalist.

Copying the identifier from the site URL.

Example: https://www.inaturalist.org/projects/example-project

image.png

Another method is appending .json to the project URL and searching for the slug value.

Example: https://www.inaturalist.org/projects/example-project.json

 
 

Identifying the Taxon ID

The Taxon ID is a numeric value found in the site URL when viewing a taxon page.

Example: https://www.inaturalist.org/taxa/47686-Protozoa

Alternatively, you can append .json to the taxon URL and search for the numeric ID.

Example: https://www.inaturalist.org/taxa/47686-Protozoa.json

 
 


Destination

EarthRanger

Setup Instructions for the iNaturalist - EarthRanger Integration.

1. Create an Integration User

In EarthRanger, create a dedicated user account (e.g., “Gundi Service Account”) for this integration. Please refer to EarthRanger's documentation or contact Support.

2. Create Authentication Token

Create a long-lived token for the user created in Step 1. This token will be used for authentication. Please refer to EarthRanger's documentation or contact Support.

3. Configure Event Type and Schema

Ensure that the required event type and schema exist in EarthRanger:

Event Type: inat_observation

4. Assign Permissions

Edit the user created in Step 1 and assign the necessary permissions to post event data. Be sure to include permission for the Event Category that contains the inat_observation event type (from Step 3).

 
 

Smart Connect

To send data to SMART:

  • Ensure that the necessary categories and attributes are set up in your SMART CA data model before proceeding.
 
 

Configuration

GUIDE

1. Login to Gundi and click Create Route.

2. Select iNaturalist.

3. Enter what to pull from iNaturalist, using one of these options:

  • Project IDs: click Add Item to add each Project ID. A Project ID on its own is enough.
  • Taxa IDs and a bounding box: enter the Taxa IDs as a comma-separated list (e.g., 12345, 67890) and fill in the Bounding box described below. Without a Project ID, both are required; a bounding box on its own is not enough.

If neither option is complete, the route will not save and This field is required. appears under the missing field.

4. Apply any optional filters (these will be in addition to any filters already applied in iNaturalist).

Quality Grade

If specified, only observations with the selected quality grades will be included. As of November 2024, valid values are:

  • casual
  • needs_id
  • research
 
 

Annotations

Map of annotation terms and the values which to include.  

Format

{"TermID": ["TermValue"], "TermID": ["TermValue", "TermValue",…]}

An observation is included only when it has every term and every value you list.


Example

{"1": ["2"], "22": ["24", "25"]}

This will include observations where:

Life Stage is Adult (ID 1, Value 2) AND

Evidence of Presence is Organism (22, Value 24) AND Scat (22, Value 25).

Reference Guide

Term ID 1: Life Stage (2=Adult, 3=Teneral, 4=Pupa, 5=Nymph, 6=Larva, 7=Egg, 8=Juvenile, 16=SubimagoBody)
Term ID 9: Sex (10=Female, 11=Male)
Term ID 12: Plant Phenology (13=Flowering, 14=Fruiting, 15=Flower Budding, 21=No Evidence of Flowering)
Term ID 17: Alive or Dead (18=Alive, 19=Dead, 20=Cannot Be Determined)
Term ID 22: Evidence of Presence (23=Feather, 24=Organism, 25=Scat, 26=Track, 27=Bone, 28=Molt, 29=Gall, 30=Egg, 31=Hair, 32=Leafmine, 35=Construction)
 
 

Bounding box

Required when you use Taxa IDs without a Project ID. Specify a bounding box for the search area in the format:

[ne_latitude, ne_longitude, sw_latitude, sw_longitude]

That is, [north, east, south, west]. The first number must be larger than the third, and the second larger than the fourth.

 
 

5. Enter the event type ID to use in EarthRanger.  

6. Configure a string prefix for observed species when creating events. 

7. Configure the number of days of data to load from iNaturalist on the connection's first run (required; 1 to 7 days, default 3).

8. Specify whether to include photos from iNaturalist observations.

  • Photos per sighting: how many photos to attach to each event (0 to 50, default 3).
  • Max age (days): sightings uploaded longer ago than this are not created or updated (default 150).
  • New events per run: the most new events each check sends (default 150, up to 1,000).

9. Select your Workspace.

10. Enter a name for this Route (e.g., “iNaturalist - AccountName”)

11. Click Next

12. Click Add destination on the flow map and select a destination. Please consult our guides.

Next Steps

EarthRanger

Coming soon..

 
 

SMART Connect

Coming soon..

 
 

Screenshots

Data Latency

Gundi pulls data from iNaturalist every 10 minutes, and it is a configurable parameter. 

Other Online Database

eBird
Back to the integration catalog Need help setting this up? Contact us