Inaturalist Get Species Counts
inaturalist_get_species_countsRead-only
Rank leaf taxa recorded in an area and period, most-observed first. Includes hybrids and coarser identifications; subspecies roll up to their species. An area is given in exactly one form: place_id, the lat/lng/radius triple in kilometres, or a four-corner bounding box. Narrow to a clade by passing taxon_id, e.g. the birds of a park, or to one observer or one project by user_id, user_login, or project_id. Defaults to research-grade, wild-only records and echoes those defaults back. For the most active people rather than the most recorded taxa, use inaturalist_get_leaderboard.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| d1 | No | Earliest observation date, YYYY-MM-DD. Inclusive. Must be on or before d2. | |
| d2 | No | Latest observation date, YYYY-MM-DD. Inclusive. | |
| csi | No | IUCN-normalised conservation status codes. Matches global statuses plus statuses listed at exactly place_id, excluding ancestor-place listings; decode with inaturalist_list_reference topic conservation_status_codes. | |
| lat | No | Latitude of the search centre, in decimal degrees. Requires lng and radius. | |
| lng | No | Longitude of the search centre, in decimal degrees. Requires lat and radius. | |
| page | No | Page number. Defaults to 1. | |
| rank | No | Exact identification rank. Unlike hrank/lrank, species does not also select hybrid. | |
| hrank | No | Highest (coarsest) identification rank level to accept. Must be at or above lrank. | |
| lrank | No | Lowest (finest) identification rank level to accept. Equal bounds select a level, including ranks sharing that level such as species and hybrid. | |
| month | No | Observed calendar months, 1–12, matched as alternatives. | |
| nelat | No | North-east corner latitude of the bounding box, at or north of swlat. All four corners or none. | |
| nelng | No | North-east corner longitude of the bounding box. All four corners or none. West of swlng is accepted: it describes a box crossing the antimeridian. | |
| swlat | No | South-west corner latitude of the bounding box. All four corners or none. | |
| swlng | No | South-west corner longitude of the bounding box. All four corners or none. | |
| native | No | Filter the observation’s indexed taxon as native at its location. | |
| radius | No | Search radius around lat/lng, in KILOMETRES, greater than 0. Requires lat and lng. Ceiling: 20040; oversized values are clamped with notice. | |
| captive | No | True returns captive and cultivated records only — zoo animals, garden plantings; false returns wild records only. Defaults to false. | |
| endemic | No | Filter the observation’s indexed taxon as endemic at its location. | |
| term_id | No | Annotation attribute ids, from inaturalist_list_reference topic controlled_terms — e.g. 1 for Life Stage. Multiple ids match any one annotation, not all annotations; arrays are membership sets, not positional pairs. | |
| user_id | No | Restrict to one observer, by numeric user id from inaturalist_resolve_name type user. Mutually exclusive with user_login. | |
| per_page | No | Taxa per page. Raise page to continue the ranking. Ceiling: 50; oversized values are clamped. | |
| place_id | No | Numeric iNaturalist place id from inaturalist_find_places. Mutually exclusive with the lat/lng/radius triple and the bounding box. A non-numeric value answers HTTP 500 upstream. | |
| taxon_id | No | Restrict to this taxon and its descendants. Resolve a name to an id with inaturalist_resolve_name. | |
| introduced | No | Filter the observation’s indexed taxon as introduced at its location. | |
| project_id | No | Restrict to observations in one project, by numeric project id from inaturalist_resolve_name type project. | |
| threatened | No | Filter the observation’s indexed taxon as threatened at its location. | |
| user_login | No | Restrict to one observer, by login — the login on an inaturalist_resolve_name user candidate, a leaderboard entry, or an observation’s observer. Mutually exclusive with user_id. | |
| iconic_taxa | No | Broad organism groups, by their scientific iconic-taxon name. A common-name value such as "Birds" matches nothing upstream, so only the listed values are accepted. | |
| quality_grade | No | Identification confidence tiers to include, normalized to unique values in first-appearance order. Defaults to research-grade only; adding "needs_id" roughly doubles the corpus and lowers identification confidence. | |
| term_value_id | No | Annotation value ids, from the same attribute listing — e.g. 6 for Larva. Requires term_id; sent alone it is ignored upstream and the unfiltered corpus comes back. Multiple ids match any one annotation with an attribute in term_id and a value in this set, not both annotations. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| cap | No | The per_page that was applied. | |
| error | No | Present when the call failed. Absent on success. | |
| shown | No | How many taxa this page carries. | |
| notice | No | Guidance when nothing matched, when the page is past the last one holding taxa, or how to reach the taxa beyond this page. | |
| species | No | The taxa, ranked by observation_count, most-observed first, each at its absolute position. | |
| truncated | No | True when the page filled per_page and more taxa follow. | |
| total_results | No | How many taxa match. An estimate over a live index — it drifts between calls seconds apart. | |
| applied_filters | No | The server-applied defaults that determine what this answer means. | |
| truncationCeiling | No | Observation count of the last taxon shown. The ranking is descending, so no taxon left off this page exceeds it. |