Supported technology/Online Database
| Platform | Gundi v2 |
| Type | Pull integration |
| Data | Events |
| Direction | Data provider |
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
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:
casualneeds_idresearch
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 |
