API Recommended Practices

iNaturalist has for a long time offered an API through the website, documented at https://www.inaturalist.org/pages/api+reference
A few years ago we released a newer API at https://api.inaturalist.org/, which was designed to be more consistent with faster response times, and to be the scalable API to use going forward. We recommend using the new API and consider the old one deprecated
The new API is used by the iNaturalist mobile applications and the iNaturalist website. Since our own applications rely on the new API functioning, it will be better supported and we’ll be more responsive to fixing and improving it
If there are methods implemented in the old API that aren’t present in the new API, and this is preventing you from using the new API, please let us know. Posting to https://forum.inaturalist.org/ is a good way to make feature requests
The new API does not re-implement the OAuth authentication endpoints in the older API, and those are the only non-deprecated endpoints in the old API

The preferred way to make an authenticated request in the newer API is to use a JSON Web Token (JWT), available at https://www.inaturalist.org/users/api_token
These tokens expire in 24 hours, and you’ll need to fetch a new token when it expires
Include the JWT in an HTTP Authorization header, e.g. Authorizaton: YOUR_JWT
OAuth tokens from the older API must be used to fetch JWTs
Authenticate API requests only when required. Since the data returned from authenticated requests might contain private information, these requests are not cached, therefore they can require more server time to process
Simplifying and unifying authentication is on our development wish list

The page and per_page parameters can be used to fetch up to (for many endpoints) 10k results. An error will be thrown if results beyond 10k are requested. This is due to database memory implications of paging through large result sets
Any change the search parameters, like adding date filters, or filtering by taxon, will be a new search. So try changing filters instead of paging through a huge result set
Be sure to use enough search filters so that you’re only fetching the data you plan to use
If more than 10k results are needed, that would be considered a bulk request, which are not best handled by the API. See the “Bulk Requests” section below
One way to use the API and fetch more than 10k records is to sort by id ascending (e.g. &order_by=id&order=asc) and use the id_above parameter set to the ID of the record in the last batch. id_above is a search parameter, so this is essentially the same recommendation as above to change search parameters, but by using a parameter that doesn’t affect the nature of the results

To fetch a lot of observation data efficiently, we recommend using observation exports https://www.inaturalist.org/observations/export
We hope to expand exports in the future to include more core data types to export (identifications, taxa, etc), and to have more pre-packaged large datasets available
Another recommended way to get a lot of data at once is to use the dataset of research grade observations that we submit weekly to GBIF https://www.gbif.org/dataset/50c9509d-22c7-4a22-a47d-8c48425ef4a7
A benefit to using this dataset is it has a DOI (https://doi.org/10.15468/ab3s5x) that can be used to cite iNaturalist data use, and these citations can be tracked
You can also export subsets of this data on GBIF itself. Custom exports on GBIF also come with their own citable DOI, which help both GBIF and iNat track which records were used in a particular publication, which taxa receive more research attention, etc.
If using the API to fetch a lot of results, please use the highest supported per_page value. For example you can get up to 200 observations in a single request, which would be faster and more efficient than fetching the default 30 results at a time
If fetching multiple records by ID, please send a concatenated list of multiple IDs to fetch many records in a single request as opposed to fetching each record individually, e.g. https://api.inaturalist.org/v1/observations/10000,10001,10002
If you’re looking for even more data, contact us directly at help@inaturalist.org

Please keep requests to about 1 per second, and around 10k API requests a day
The API is meant to be used for building applications and for fetching small to medium batches of data. It is not meant to be a way to download data in bulk
Requests exceeding this limit might be throttled, and will return an HTTP 429 exception “Too Many Requests”
Please add delays into your code to keep under these limits, and especially if you’re getting 429 errors
We may block IPs that consistently exceed these limits
Please use a single IP address for fetching data. If we think multiple IPs are being used in coordination to bypass rate limits, we may block those IPs regardless of query rate
Downloading over 5 GB of media per hour or 24 GB of media per day may result in a permanent block
If writing software to interact with the API, please consider using a custom User Agent to identify your application, or iNaturalist username, or something we might use to differentiate your requests
The User Agent can be set with an HTTP header, e.g. User-Agent: [[application or user name]

If you are creating an application that will allow users to post data to iNaturalist, please do not do it using a group account (i.e. many individuals submitting data under a single username).
Use one of the various OAuth authentication flows to allow users to log in to iNaturalist as themselves

Please post any API-related feature requests, bug reports, or suggestions to the forum https://forum.inaturalist.org/
We’re beginning to think about the next major release of the API. What would you like to see added, changed, or removed?

Revised on February 19, 2021 08:52 PM by