Inaturalist Get Histogram
inaturalist_get_histogramBuild a phenology histogram for a taxon in an area — which months, weeks, or years it is recorded in. The default month_of_year interval answers "when does this bloom or appear here" in twelve buckets; absolute intervals (year, month, week, day, hour) bucket real dates and disclose their window start. An area is given in exactly one form: place_id, the lat/lng/radius triple in kilometres, or a four-corner bounding box. Omit taxon_id to chart every taxon in the area. Narrow to one life stage or reproductive state with an annotation pair (term_id and term_value_id, e.g. Life Stage = Larva, or Flowers and Fruits = Flowers), or to broad groups with iconic_taxa. Defaults to research-grade, wild-only records and echoes those defaults back.
Tool call template
This tool declares no required parameters. Add optional parameters from the input schema as needed.
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {},
"name": "inaturalist_get_histogram"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| d1 | No | Earliest observation date, YYYY-MM-DD. Inclusive. Must be on or before d2. For absolute observed-date intervals, a missing d1 is derived from d2 or today UTC and disclosed as window_start. Wide ranges can exceed the 25000-bucket cap; continuation names d1, or created_d1 for upload-date bucketing. | |
| 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. | |
| 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. | |
| 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. Captive records are graded casual, so pair true with "casual" in quality_grade. | |
| 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. | |
| interval | No | Bucketing. month_of_year and week_of_year fold every year together into a seasonal curve. Absolute intervals default the selected date family's missing lower bound from its upper bound, otherwise today UTC: year/month subtract 100 calendar years, week 10 years, day one year, hour seven days. The start is disclosed; no upper bound is added. At most 25000 buckets are returned, oldest first, with continuation guidance when cut. | month_of_year |
| place_id | No | Numeric iNaturalist place id from inaturalist_find_places. Mutually exclusive with the lat/lng/radius triple and the bounding box. | |
| taxon_id | No | Restrict to this taxon and its descendants. Omit to chart every taxon in the area. Resolve a name to an id with inaturalist_resolve_name. | |
| created_d1 | No | Earliest upload date, YYYY-MM-DD. Inclusive. Must be on or before created_d2. | |
| created_d2 | No | Latest upload date, YYYY-MM-DD. Inclusive. | |
| date_field | No | Which date to bucket by: when the organism was observed, or when the record was uploaded. | observed |
| project_id | No | Restrict to observations in one project, by numeric project id from inaturalist_resolve_name type project. | |
| 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 — Aves, not "Birds"; inaturalist_list_reference topic iconic_taxa lists them. | |
| 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. 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 bucket cap that was applied. | |
| error | No | Present when the call failed. Absent on success. | |
| shown | No | How many buckets this response carries. | |
| total | No | Observations in the upstream histogram window: sum of every returned bucket count, including buckets past the cap; not an all-time taxon count. | |
| notice | No | Generated window start, filter guidance, and continuation when buckets are cut. | |
| buckets | No | Every bucket upstream returned, in order, including the zero ones — up to 25000, the first in upstream key order. See the truncated/shown/cap enrichment when more exist. | |
| interval | No | The bucketing that was applied. | |
| truncated | No | True when upstream returned more than 25000 buckets. | |
| applied_filters | No | Effective cohort defaults, bucketed date family, and absolute window start. |