io.github.andrewschristison/pondlog-npn

Place-aware shortcut: 'what phenology has been recorded near these coordinates?' Composes a WKT bounding box from coords+radius, finds NPN stations inside, haversine-filters to true radius, and returns the closest stations' site-level phenometric records over the requested years (sorted by most-recent meanLastYesDate). Each entry includes `distanceKm` from the query point. Note: NPN station coverage is patchy. Eastern US and Arizona are dense; the Pacific Northwest is sparser. Use `get_station_count_by_state` to gauge regional coverage. For raw observation records, use `get_observations`. For state-wide phenometric summaries, use `get_site_level_data`.

Status / intensity observation records, individual observer reports of whether a phenophase was 'yes' (1), 'no' (0), or 'uncertain' (-1) on a given date. This is the rawest NPN data type. REQUIRES a year filter and at least one narrowing filter (species/station/state/genus/family/order/class). Unfiltered queries can return tens of MB. For 'is this in phenology now?' aggregated answers prefer `get_site_level_data`. For a place-aware 'what's recently active' shortcut prefer `get_active_phenology_nearby`.

Per-site phenometric aggregates: for each (site, species, phenophase, year), returns the mean first/last 'yes' date (when phenophase began and ended on average across observed individuals). This is the right granularity for 'when do magnolias typically bloom in WA?', much smaller than `get_observations`. REQUIRES a year filter and at least one of species_ids/station_ids/states. Site-level dates are returned as both julian-day (mean*Julian) and ISO date (mean*Date). Sample size fields (firstYesSampleSize, lastYesSampleSize) tell you how many individuals contributed to the mean.

Returns the number of USA-NPN stations per US state (a quick map of NPN's geographic coverage). Useful for deciding which state to query for phenology data, eastern US states (NY, MA, ME) and Arizona have the densest coverage; Pacific Northwest is sparser.

Returns NPN stations inside a Well-Known Text polygon. NPN's spatial filter is WKT-based, not lat/lng/radius. WKT format example: 'POLYGON((-123.7 47.9, -123.0 47.9, -123.0 48.3, -123.7 48.3, -123.7 47.9))', coordinate pairs are 'lng lat', the polygon must close (first point repeated as last). For most use cases prefer `get_active_phenology_nearby` which builds the WKT from coords + radius internally.

List all USA-NPN observation stations in a given US state. Returns each station's NPN station_id, name, coordinates, and (when applicable) network ID. Pass `state_code` to narrow. NPN's unfiltered list is ~50,000 stations. Use station_ids returned here to filter `get_observations` or `get_site_level_data`.

Returns all NPN stations that have observations for any of the given species. Use to answer 'where in the US can I find phenology data for saguaro?' Note: due to a known upstream NPN bug, some species (notably species_id=3, red maple) return an empty result; the tool surfaces these as empty arrays rather than errors.

Search the USA-NPN species catalog (~1,900 species). Returns matching species with NPN species_id, scientific name, common name, kingdom (Plantae/Animalia/Fungi). Use this first to look up a species_id before calling other tools that take species filters. All filters are case-insensitive. Filters compound: passing query + kingdom narrows further.