@pondlog/source-inaturalist

iNaturalist API client library: typed, Zod-validated, rate-limited. Returns Result<T> instead of throwing.

Source

npm

Version: 0.1.0

Version published: 4 months ago

Maintainers: 1

Created: 4 months ago

Source

@pondlog/source-inaturalist

iNaturalist API client. Typed, Zod-validated, rate-limited, returns Result<T> instead of throwing. Part of pondlog.

No API key required — iNaturalist reads are open. The library handles the 100 req/min rate limit internally and backs off on 429.

Install

npm install @pondlog/source-inaturalist @pondlog/core

Functions

Function	Endpoint	Returns
`searchObservations(params)`	`GET /observations`	`Result<Observation[]>`
`getObservation(id)`	`GET /observations/{id}`	`Result<ObservationDetail>`
`getSpeciesCounts(params)`	`GET /observations/species_counts`	`Result<SpeciesCount[]>`
`getNearbyObservations(coords, radius?, days?)`	`GET /observations` (geo)	`Result<Observation[]>`
`searchTaxa(query)`	`GET /taxa`	`Result<Taxon[]>`
`getTaxon(id)`	`GET /taxa/{id}`	`Result<TaxonDetail>`
`getIconicTaxaSummary(coords, radius?, days?)`	`GET /observations/species_counts` (grouped)	`Result<IconicTaxaSummary>`
`searchPlaces(query)`	`GET /places/autocomplete`	`Result<Place[]>`
`getObservers(coords, radius?, days?)`	`GET /observations/observers`	`Result<Observer[]>`

Defaults: radius = 25 km, days = 7.

Example

import { getNearbyObservations } from "@pondlog/source-inaturalist";

const result = await getNearbyObservations(
  { lat: 48.118, lng: -123.4307 }, // Port Angeles, WA
  25,                               // km
  7,                                // days
);

if (!result.ok) {
  console.error(result.error.message);
  process.exit(1);
}

for (const obs of result.data) {
  console.log(obs.commonName, obs.taxonName, obs.observedAt);
}