Public catalogue API

Licence

The catalogue's facts as compiled here (roasters, places, coffees, origins, processes, prices and dates) may be reused with attribution to Best Coffee Roaster and a link to bestcoffeeroaster.com. Merchants' photographs and product descriptions belong to them and are not covered. Licence: CC BY 4.0. The site's own endpoints are described in /openapi.json; a summary for language models is at /llms.txt.

Explained discovery on this site

GET /discovery.json?brew=filter&taste=fruity&budget=6 returns the same bounded recommendations as the visible guide, including reasons, preference gaps, source links and observed dates. Optional country means roaster country, not delivery. These are suggestions with evidence, not quality ratings. An incomplete flag identifies upstream source failures.

GET /coffee-stops.json?city=amsterdam returns the researched public coffee stops, with operator sources and regular opening hours. Unsupported cities return an empty result, rather than a different location.

Discovery and city guides also render their initial content in HTML. Catalogue feeds retain real next-page links alongside continuous scrolling. Personal shelves are browser-local and are not exposed through these endpoints.

The wider catalogue

The catalogue is available as a read-only JSON API. No key is required. Please cache responses and request small pages.

Base URL: https://oaztfhjtlfauzsnbwwde.supabase.co/functions/v1/agent-api

• GET /openapi.json — OpenAPI 3.1 description.
• GET /coffees — search: q, origin, process, roaster, roaster_country, ships_to, min_eur_per_100g, max_eur_per_100g, named_producer, green, sort, limit, offset.
• GET /coffees/{id} — detail with offers, origin and merchant.
• GET /roasters — q, country, seller_kind, specialty, limit, offset.
• GET /producers — q, country, limit, offset.

List responses are { results: [...] } without totals; page with limit and offset.