# HerbAPI

> Central reference database for permaculture and agroforestry planning,
> run by Sub-Net e.U. (https://herbapi.naturalised.at). Covers botanical families, plant species,
> cultivars, fungi (mushrooms), insects (beneficial & pest), other animals
> (molluscs, mammals, birds, arachnids, annelids, …), seed/plant suppliers,
> companion-planting relationships, a cross-domain interaction graph, and
> images. Data is trilingual — German (de), English (en) and botanical Latin
> names. Every organism links back to GBIF (and most to Wikidata/Wikipedia)
> for provenance and verification. All read endpoints are public and
> CORS-enabled, so other projects can consume HerbAPI directly as a shared
> source of truth for permaculture and nature data.

Taxonomy is three levels: **Family → Species → Cultivar**. Entities are
addressable by either a UUID or a URL `slug` (e.g. `fabaceae`,
`trifolium-pratense`). Responses are JSON. Write operations require an
authenticated session (Authentik OIDC, group `g-sn-herbapi-admin`); everything
under read access below needs no auth.

## Current contents

- Families: 67
- Species (plants): 412
- Cultivars: 2409
- Fungi: 14976
- Insects: 22814
- Animals (non-insect fauna): 32959
- Cross-domain interactions: 636645
- Suppliers: 5
- Companion relationships: 236
- Images: 13279

Live counts: https://herbapi.naturalised.at/api/v1/stats

## API

- [OpenAPI 3 spec](https://herbapi.naturalised.at/api/openapi.yaml): full machine-readable contract for every endpoint, parameter and schema
- [Swagger UI](https://herbapi.naturalised.at/api/docs): interactive browser for the API
- [Health](https://herbapi.naturalised.at/health): liveness probe (`{"status":"ok"}`)

### Read endpoints (public, base path `/api/v1`)

- `GET /api/v1/families` — list families; `GET /api/v1/families/{ref}` — one family by slug or UUID
- `GET /api/v1/species` — list species; `GET /api/v1/species/{ref}` — one species (botanical + common names, pH, drought tolerance, plant layer, native range, wildlife value, uses, toxicity, and seed handling & propagation: seed storage behaviour, longevity, stratification/scarification, germination temperature & time, sowing depth/months, propagation methods)
- `GET /api/v1/species/{ref}/companions` — companion-planting partners for a species
- `GET /api/v1/fungi` — list fungi (mushrooms); `GET /api/v1/fungi/{ref}` — one fungus (edibility, substrate, mycorrhizal host plants, fruiting season)
- `GET /api/v1/insects` — list insects; `GET /api/v1/insects/{ref}` — one insect (beneficial/pest role, host plants, prey, life cycle)
- `GET /api/v1/animals` — list non-insect fauna (molluscs, mammals, birds, arachnids, annelids, nematodes, …); `GET /api/v1/animals/{ref}` — one animal (role, diet, host plants, prey, eaten-by, IUCN conservation status); filter `?class=Mammalia` etc.
- `GET /api/v1/interactions?subject_kind=&object_kind=&predicate=` — cross-domain links (pollinates, preys_on, parasitizes, disperses_seeds_of, mycorrhizal_with, …); also `/{species|fungi|insects|animals}/{ref}/interactions`
- `GET /api/v1/cultivars` — list cultivars; `GET /api/v1/cultivars/{ref}` — one cultivar
- `GET /api/v1/cultivars/{ref}/suppliers` — where to buy a cultivar (SKUs, prices, product URLs)
- `GET /api/v1/suppliers` — list suppliers; `GET /api/v1/suppliers/{ref}` — one supplier
- `GET /api/v1/companions` — all companion relationships
- `GET /api/v1/images/{entity_type}/{entity_id}` — images for an entity (`entity_type` = `family`|`species`|`cultivar`|`fungus`|`insect`|`animal`)
- `POST /api/v1/upload/{kind}/{ref}` — **contribute an image** to a plant/organism by slug or UUID (`kind` = `species`|`cultivars`|`fungi`|`insects`|`animals`|`families`). Requires a `Bearer` API token with `write` scope. `multipart/form-data`: `file` (the image; transcoded to WebP), and optional `caption`, `license`, `source_url`, `photographer` (+ `photographer_url`) to credit the person who took the photo, `is_primary`. The uploader (bot/token name) is recorded automatically; re-uploading identical bytes is idempotent. Generic alternative: `POST /api/v1/images` with `entity_type` + `entity_id` form fields.
- `GET /api/v1/search?q=...` — weighted full-text search across families, species, cultivars, fungi, insects and animals
- `GET /api/v1/suggest?q=...` — fast fuzzy, accent-insensitive autocomplete (typo-tolerant) across all entity types
- `GET /api/v1/stats` — record counts
- `GET /api/v1/{family|species|cultivar}/{ref}/summary` — compact card (name, scientific, family/species, image, blurb, key facts) for tooltips/embeds
- `GET /api/v1/export` — full dataset as one JSON document (`?format=ndjson` for line-oriented ETL). Subset with `?include=` or `?exclude=` (comma-separated dataset keys: families, species, cultivars, suppliers, cultivar_suppliers, companions, images, fungi, insects, animals, interactions) — e.g. `?exclude=interactions` for a compact dump, or `?include=species,cultivars,families`

List endpoints return `{data, total, page, per_page}` and accept `?page=` /
`?per_page=` (max 100) plus, where relevant, `?search=` / `?family=` filters.
Add `?lang=de` or `?lang=en` to ANY JSON endpoint to collapse bilingual
`*_de`/`*_en` field pairs into single localized fields. All JSON responses carry
a weak `ETag`; send `If-None-Match` for cheap `304` polling. Images are served
via `GET /img/{path}` (S3 proxy).

## Embeddable hover tooltips

Other sites can show plant hover-cards (db.exil.es style) by including one
script — it auto-attaches to any link pointing at a HerbAPI family/species/
cultivar page:

```html
<script src="https://herbapi.naturalised.at/herbapi-tooltips.js" defer></script>
```

Set `window.HERBAPI_LANG = 'en'` (or use `<html lang>`) to control language.

## Examples

- All species: `https://herbapi.naturalised.at/api/v1/species`
- One species by slug: `https://herbapi.naturalised.at/api/v1/species/trifolium-pratense`
- Companions for a species: `https://herbapi.naturalised.at/api/v1/species/trifolium-pratense/companions`
- Search: `https://herbapi.naturalised.at/api/v1/search?q=clover`
- Where to buy a cultivar: `https://herbapi.naturalised.at/api/v1/cultivars/{slug}/suppliers`

## Pages (human-facing web UI)

Browseable HTML pages (Dioxus single-page app, same data as the API). Detail
pages live at `<list>/<slug>` and link out to GBIF + Wikidata.

- `https://herbapi.naturalised.at/` — home (search, live counts, quick filters, featured plants & fauna)
- `https://herbapi.naturalised.at/families` — botanical families
- `https://herbapi.naturalised.at/species` — plants (filterable: `?nitrogen_fixer=true`, `?plant_layer=`, `?min_nectar=`)
- `https://herbapi.naturalised.at/cultivars` — cultivars & varieties (sowing calendars, where to buy)
- `https://herbapi.naturalised.at/fungi` — fungi / mushrooms
- `https://herbapi.naturalised.at/insects` — insects (beneficial & pest)
- `https://herbapi.naturalised.at/animals` — non-insect fauna (molluscs, mammals, birds, arachnids, annelids, …; filter `?class=Mammalia`)
- `https://herbapi.naturalised.at/companions` — companion-planting relationships
- `https://herbapi.naturalised.at/search?q=` — search results
- `https://herbapi.naturalised.at/sources` — data sources & licences

## Optional

- [Web UI](https://herbapi.naturalised.at/): human-facing Dioxus frontend over the same API
- Languages: every name/description field carries `_de` and `_en` variants; species also expose Latin botanical names
- Data sources: Catalogue of Life (taxonomic backbone, CC BY), GBIF (taxonomy, occurrences, IUCN status, CC images), GloBI (the interaction graph), PFAF, NaturaDB, FloraWeb/Ellenberg, Wikidata/Wikipedia, Wikimedia Commons. Every organism carries a `gbif_id` (and most a `wikidata_qid`) for backlinks; images store their licence + dataset citation.
- Contact: florian.berthold@sub-net.at