Inaturalist Get Species Counts
inaturalist_get_species_countsRead-only
Rank the distinct species recorded in an area and period, most-observed first — the "what lives here" answer, without paging through individual sightings. 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. Defaults to research-grade, wild-only records and echoes those defaults back. For the most active people rather than the most recorded species, use inaturalist_get_leaderboard.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| d1 | No | Earliest observation date, YYYY-MM-DD. Inclusive. | |
| d2 | No | Latest observation date, YYYY-MM-DD. Inclusive. | |
| 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. | |
| nelat | No | North-east corner latitude of the bounding box. All four corners or none. | |
| nelng | No | North-east corner longitude of the bounding box. All four corners or none. | |
| 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. | |
| radius | No | Search radius around lat/lng, in KILOMETRES. Requires lat and lng. The upstream publishes no bound; 500 is a verified ceiling this server imposes. | |
| captive | No | Whether to include captive and cultivated records — zoo animals, garden plantings. Defaults to wild organisms only. | |
| term_id | No | Annotation attribute ids, from inaturalist_list_reference topic controlled_terms — e.g. 1 for Life Stage. | |
| per_page | No | Species per page, maximum 50. A ranked species costs roughly 860 bytes across structuredContent and the rendered text together, so 50 is a full page near 43 KB. Upstream would serve 500 in one page — raise page rather than asking for it. | |
| 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. | |
| 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. 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. |
Output Schema
TableJSON 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 species this page carries. | |
| notice | No | Guidance when nothing matched, or how to reach the species beyond this page. | |
| species | No | The species, ranked by observation_count, most-observed first. | |
| truncated | No | True when the page filled per_page and more species follow. | |
| total_results | No | How many distinct species 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 species shown. The ranking is descending, so no species left off this page exceeds it. |