omnilab/inaturalist API reference

Omnilab\INaturalist

INaturalistSource class

final class INaturalistSource extends HttpSource INaturalistSource.php:43

iNaturalist (California Academy of Sciences and National Geographic Society), through its API (api.inaturalist.org): a taxon by its id or a name it matches exactly - its rank, common name in a language, iconic group, conservation status, lineage, Wikipedia summary, number of observations, its default photo with its licence and attribution; its parent (or, for an inactive taxon, the one that replaced it) as a related thing; a search of its names. And the observations of a place and a period - research grade by default -, each an entity with its time and its place, its taxon related, its licence and its photo's (occurrences(), entity() by its number).

Which API: version 1 for the taxa (a taxon whole in one call); version 2 for the observations, which answers only the fields asked for - a page of 200 lion observations weighs 44 MB in version 1 (every identification, comment and vote of each), 0.18 MB so.

No key. iNaturalist throttles at 100 calls a minute, asks for 60 at most and 10,000 a day, and blocks without notice a use that weighs on it: one call a second. iNaturalist gives no identifier of another base for a taxon: Wikidata (P3151) is the way between them.

const BASE_URI = 'https://api.inaturalist.org/'

const THROTTLE = 1.0

Seconds between two calls: iNaturalist's 60 a minute.

const MAX_PER_PAGE = 200

The most taxa or observations one page holds (iNaturalist stops at 200).

const MAX_DEPTH = 10000

How deep a search pages by page number: page times size (iNaturalist's error beyond).

const QUALITY_GRADES = ['research', 'needs_id', 'casual']

The quality grades of an observation: research (identified by the community, dated, placed, wild, with evidence), needs_id, casual.

const LICENSES = ['cc0', 'cc-by', 'cc-by-nc', 'cc-by-sa', 'cc-by-nd', 'cc-by-nc-sa', 'cc-by-nc-nd']

The licences iNaturalist filters by.

const QUALITY_GRADE = 'quality_grade'

iNaturalist's own filter: the quality grade, or a list of them; "any" for all.

INaturalistSource::__construct()

public function __construct(HttpClientInterface $http, readonly string $locale = 'en', readonly string $quality = 'research', readonly float $radius = 10.0, string $baseUri = self::BASE_URI, array $headers = [], float $throttle = self::THROTTLE)

$locale

the language of the common names

$quality

the quality grade asked when a query does not say ("any": all)

$radius

the radius around a Point, in kilometres, for occurrences() when the query gives none

INaturalistSource::getName()

public function getName(): string

INaturalistSource::capabilities()

public function capabilities(): array

INaturalistSource::entity()

public function entity(Identifier|string $id): ?Entity

A taxon by its id (41964, inaturalist:41964, its page) or a name iNaturalist matches exactly - a scientific name, a synonym ("Felis leo" gives Panthera leo) or a common name; an observation by its number (inaturalist.observation:332912788, its page): one call, two for a name.

INaturalistSource::search()

public function search(Query $query): Page

iNaturalist's search of its taxa's names - scientific, common, former -, active taxa only, its order (the most observed first, broadly), page by page. A domain other than taxonomy answers nothing.

INaturalistSource::occurrences()

public function occurrences(OccurrenceQuery $query): Page

The observations of the place and the period, each an entity with its time and its place, its taxon related: research grade unless the query or the source's option says otherwise; only the georeferenced.

A BBox is the box (across the antimeridian too: iNaturalist reads it); a Point, the circle of the query's radius around it (the configured one, 10 km, by default); no place, the world. The period: a bound at midnight is its whole day, any other the instant. Filters: OccurrenceQuery::TAXON (an id, inaturalist:41964 - its subordinate taxa included -, or a name iNaturalist matches), LICENSE (cc0, cc-by, cc-by-nc... or a list: the observation's licence) and quality_grade (research, needs_id, casual, a list, or "any"). Sort: none, the observations latest added first (paged by id, no depth limit), or NEWEST / OLDEST by the day observed (paged by number, 10,000 deep). 200 a page at most; the total is iNaturalist's count, on the first page.

INaturalistSourceFactory class

final class INaturalistSourceFactory extends SourceFactory INaturalistSourceFactory.php:23

iNaturalist: taxa by id or name, their rank, common name, conservation status, lineage and default photo with its licence; and the observations of a place and a period, research grade by default - no key needed.

options: mailto: 'support@glitchr.io' # in the User-Agent: iNaturalist blocks, without notice, a use it does not recognise locale: 'en' # the language of the common names (and of a taxon's Wikipedia summary) quality_grade: 'research' # the observations answered when a query does not say: research, needs_id, casual, or any radius_km: 10 # the circle around a Point, for occurrences() when the query gives none throttle: 1.0 # seconds between two calls: iNaturalist asks for 60 a minute at most (it blocks beyond 100), 10,000 a day base_uri: 'https://api.inaturalist.org/'

Options