Market intelligence
Market analytics
Analytics is a product surface on Purveyors, not a standalone public API family, with session-auth roast analysis helpers behind the scenes.
The /analytics page delivers market intelligence derived from the same normalized catalog that powers the public API. Public visitors can browse the core market overview: origin price trends, processing mix, origin price ranges, and the supplier/listing/origin stat bar. Parchment Intelligence users get the deeper supplier comparison, supplier health, arrivals, delistings, and extended trend modules.
Analytics is important to the product story, but only the aggregate /v1/price-index subset is exposed as a stable API-key contract. Keep the distinction between product UI, internal helpers, and public REST contract explicit.
What is public today
- /analytics is a web product surface, while /v1/price-index is the API-key contract for the aggregate price-index subset backed by price_index_snapshots.
- /v1/price-index intentionally starts with JSON pagination only. Do not document CSV, alerts, watchlists, webhooks, or supplier-level raw rows as supported.
- Logged-out visitors and logged-in viewers share the same core analytics view. The server resolves Parchment Intelligence access separately and uses it to decide whether to load the gated modules.
- Public chart data includes 90 days of price-index snapshots, current stocked processing distribution, current origin price ranges, recent-arrival/delisting counts for the upgrade preview, and the latest market summary counts.
- Parchment Intelligence expands the same page to 365 days of snapshot history plus supplier comparison, supplier health, recent arrivals, recent delistings, and origin-level aggregate modules.
- The public catalog and public analytics should be cross-linked because they describe the same coffee market from different angles: raw records versus curated analysis.
- Authenticated and premium analytics views may expose deeper app features, but only aggregate price-index snapshots currently ride through the stable public REST schema.
Roast analysis helpers
| Route | Methods | Auth | Purpose |
|---|---|---|---|
| /api/roast-chart-data | GET | Session | Sampled roast telemetry and metadata for chart rendering |
| /api/roast-chart-settings | GET | Session | Saved chart axis ranges |
| /api/ai/classify-roast | POST | Session + member role | AI-assisted roast-to-inventory matching |
| /api/clear-roast | DELETE | Session + ownership | Clear imported roast data for a flow reset |
Cross-links that should stay coherent
- /analytics, /catalog, /api, /docs, and /docs/api/catalog should tell one consistent product story.
- When analytics positioning changes, check /api copy and docs copy together so the public contract does not accidentally expand on paper.
- If analytics later becomes a first-class API family, introduce a new public namespace instead of silently overloading internal /api/* helpers.