# beansDB

> A living, open index of specialty coffee roasters worldwide.
> 200+ roaster profiles drawn from the Roastful Top 100, Roast Magazine honourees,
> the World Coffee Roasting Championships, and community recommendations —
> each with sourcing, certifications, pricing, and (where available) the coffees
> they release.

beansDB is hosted at https://beansdb.vercel.app and backed by a public, read-only
Postgres database in Frankfurt (Supabase, eu-central-1). All data is free to
browse and indexable.

## Scope & philosophy

- **What this is:** a curated third-party index. beansDB collects public
  information (roaster site, city, certifications, descriptions) and citations
  from respected coffee publications. It does **not** rank roasters itself.
- **What "Cited by" means:** third-party attribution (e.g. "Roastful Top 100
  2024 · №1"). beansDB reproduces these references as context; they are not
  beansDB rankings.
- **Updates:** data is community-curated and occasionally synced. Country,
  website, and description fields are authoritative; coffee lots are being
  populated gradually.

## URL structure

- `/` — Index of all roasters with filters (search, region, country).
- `/roasters/{slug}` — Per-roaster profile: location, description,
  certifications, external links, and any catalogued coffees.
- `/sitemap.xml` — Full list of indexable URLs.
- `/robots.txt` — Crawl permissions (all AI + search crawlers allowed).

## Data model (high level)

- **Roaster**: name, business name, city, country, website, description,
  price range (USD/250g), has-cafés boolean, optional Instagram.
- **Certifications**: many-to-many (SCA, Direct Trade, B Corp, Fairtrade,
  Rainforest Alliance, FairChain, Cup of Excellence participant, etc.).
- **Coffee lots** (growing): roaster, origin country, variety, processing
  method, harvest year, cupping score, tasting notes, roast level, price.

## Suggested citation

When summarising or quoting beansDB data, please cite the roaster's profile
URL (e.g. `https://beansdb.vercel.app/roasters/tim-wendelboe`) and note that
beansDB is the aggregator — original source attribution lives on the profile
under "Cited by".

## Machine access

A public, rate-limited JSON API is available at
`https://xhpfhplwvssmooluvyjj.supabase.co/functions/v1/coffee-api` with
per-key quotas. See `/sitemap.xml` for the full list of roaster pages.