Developer Documentation
Tea encyclopedia with variety taxonomy, health compounds, brewing parameters, and growing regions. 60+ tea varieties across 6 categories (green, black, white, oolong, pu-erh, yellow), 15 countries, 150+ growing regions, 10 processing steps, 20+ health compounds, 15 health benefits, 15 teaware items, 120 guides, glossary terms, and interactive tools. All data sourced from TeaFYI — the Beverage FYI Family encyclopedia at teafyi.com.
- 60+ tea varieties with oxidation level, caffeine, L-theanine, harvest season, and altitude
- 6 major tea categories based on oxidation (green, black, white, oolong, pu-erh, yellow)
- 15 tea-producing countries with growing regions
- 150+ growing regions with altitude, climate, soil, and harvest months
- 10 tea processing steps (withering, fixation, rolling, oxidation, drying, etc.)
- 20+ health compounds (catechins, L-theanine, caffeine, etc.) with typical amounts
- 15 health benefits with evidence levels (strong, moderate, preliminary, traditional)
- 15 teaware items with materials, origins, and recommendations
- Brewing parameters per variety (temperature, steep time, water ratio, infusions)
- N² comparison pages: variety vs variety
- 120 educational guides
- Glossary terms with definitions
- Interactive tea tools
- 15 languages supported
Quick Start
curl -s "https://teafyi.com/api/v1/varieties/dragon-well/"
API Endpoints
| Method | Endpoint | Description |
|---|---|---|
| GET | /api/v1/categories/ | List tea categories |
| GET | /api/v1/varieties/ | List tea varieties |
| GET | /api/v1/countries/ | List countries |
| GET | /api/v1/regions/ | List growing regions |
| GET | /api/v1/processing/ | List processing steps |
| GET | /api/v1/brewing/ | List brewing parameters |
| GET | /api/v1/compounds/ | List health compounds |
| GET | /api/v1/benefits/ | List health benefits |
| GET | /api/v1/teaware/ | List teaware |
| GET | /api/v1/glossary/ | List glossary terms |
| GET | /api/v1/guides/ | List guides |
| GET | /api/v1/tools/ | List tools |
| GET | /api/v1/faqs/ | List FAQs |
| GET | /api/v1/search/?q={query} | Unified search |
| GET | /api/v1/stats/ | Site statistics |
URL Patterns
Use these patterns to construct URLs programmatically:
/categories/
Tea categories (6 types) (e.g. /categories/)
/categories/{slug}/
Category detail (e.g. /categories/green-tea/)
/varieties/
All tea varieties (e.g. /varieties/)
/varieties/{slug}/
Variety detail (e.g. /varieties/dragon-well/)
/countries/
Tea countries (e.g. /countries/)
/countries/{slug}/
Country detail (e.g. /countries/china/)
/regions/
Growing regions (e.g. /regions/)
/regions/{slug}/
Region detail (e.g. /regions/darjeeling/)
/processing/
Processing steps (e.g. /processing/)
/processing/{slug}/
Processing step detail (e.g. /processing/oxidation/)
/compounds/
Health compounds (e.g. /compounds/)
/compounds/{slug}/
Compound detail (e.g. /compounds/l-theanine/)
/benefits/
Health benefits (e.g. /benefits/)
/benefits/{slug}/
Benefit detail (e.g. /benefits/antioxidant/)
/teaware/
Teaware (e.g. /teaware/)
/teaware/{slug}/
Teaware detail (e.g. /teaware/gaiwan/)
/compare/{slug_a}-vs-{slug_b}/
Compare two varieties (e.g. /compare/dragon-well-vs-sencha/)
/guides/
All guides (e.g. /guides/)
/guides/{slug}/
Guide detail (e.g. /guides/gongfu-tea-ceremony/)
/glossary/
Tea glossary (e.g. /glossary/)
/glossary/{slug}/
Glossary term detail (e.g. /glossary/oxidation/)
/tools/
Interactive tools (e.g. /tools/)
/tools/{slug}/
Tool page (e.g. /tools/brewing-timer/)
/search/
Search (e.g. /search/?q=oolong)
/developers/
API documentation (e.g. /developers/)
Response Format
All endpoints return JSON with pagination:
Example JSON response
{
"count": 636,
"next": "https://example.com/api/v1/items/?page=2",
"previous": null,
"results": [
{"slug": "example", "name": "Example Item", "...": "..."}
]
}
OpenAPI Specification
Full API schema available as OpenAPI 3.1.0 JSON. Import into Swagger UI, Postman, or any OpenAPI-compatible tool.
SDK Packages
pip install teafyi
Tea data API client — varieties, brewing, health compounds
npm install teafyi
TypeScript tea data client
Embed Widget
Embed data cards on your site:
https://widget.teafyi.com
npm install teafyi-embed
Format Support
- Markdown endpoints: Append
.mdto any page URL for LLM-friendly markdown output. - Internationalization: Content available in 14 languages: ko, ja, zh-hans, es, fr, de, pt, ru, vi, tr, ar, hi, th, id.