Tea knowledge API client for Python. Search 60 tea varieties, 15 origin countries, 15 teaware items, and tea terminology from TeaFYI -- the comprehensive tea reference with 120 expert guides covering oxidation science, processing methods, brewing parameters, and the world's tea traditions.
Explore tea at teafyi.com -- Tea Varieties | Origins | Teaware | Tea Guides
- Install
- Quick Start
- What You'll Find on TeaFYI
- API Endpoints
- Command-Line Interface
- MCP Server (Claude, Cursor, Windsurf)
- API Client
- Learn More About Tea
- Beverage FYI Family
- License
pip install teafyi[api] # API client (httpx)
pip install teafyi[cli] # + CLI (typer, rich)
pip install teafyi[mcp] # + MCP server
pip install teafyi[all] # Everythingfrom teafyi.api import TeaFYI
with TeaFYI() as api:
# Search tea varieties, origins, teaware, glossary terms
results = api.search("matcha")
print(results)
# Look up a glossary term
term = api.glossary_term("oxidation")
print(term["definition"])TeaFYI is a comprehensive tea reference covering 60 tea varieties, 15 origin countries, 15 teaware items, and 120 expert guides. All true tea comes from a single plant species -- Camellia sinensis -- and the vast differences between a delicate white tea and a robust black tea are created entirely through processing, particularly the degree of oxidation.
Tea is classified into six major categories based on oxidation level -- the enzymatic browning process that occurs when tea leaves are exposed to oxygen after picking. Oxidation is the single most important factor determining a tea's character:
| Category | Oxidation | Processing | Characteristics |
|---|---|---|---|
| Green | 0-5% | Kill-green (pan-fired or steamed), rolled, dried | Vegetal, grassy, sweet, bright green liquor |
| White | 0-10% | Minimal processing, withered and dried | Delicate, floral, honey, subtle sweetness |
| Yellow | 5-15% | Kill-green, wrapped/heaped (men huan), dried | Mellow, smooth, less grassy than green |
| Oolong | 15-85% | Withered, bruised, partial oxidation, shaped | Complex range from floral to toasty |
| Black | 85-100% | Withered, rolled, fully oxidized, dried | Malty, robust, tannic, amber-red liquor |
| Pu-erh | Post-fermented | Microbial fermentation (sheng or shou) | Earthy, woody, complex, ages for decades |
Herbal infusions (chamomile, rooibos, peppermint) are technically tisanes, not tea, as they do not come from Camellia sinensis. TeaFYI covers both categories.
Learn more: Browse Tea Categories · Tea Encyclopedia
Beyond oxidation, specific processing steps create the diversity within each tea category:
| Process | Description | Applied To |
|---|---|---|
| Kill-Green (Sha Qing) | Heat stops oxidation -- pan-fired or steamed | Green, Yellow |
| Withering | Leaves lose moisture, become pliable | White, Oolong, Black |
| Rolling/Shaping | Breaks cell walls, releases oils, shapes leaf | Green, Oolong, Black |
| CTC (Cut-Tear-Curl) | Machine processing for consistent, strong brew | CTC Black (tea bags) |
| Orthodox | Hand-plucked, gentle processing, whole leaf | Specialty loose leaf |
| Pile Fermentation (Wo Dui) | Accelerated microbial aging in humid conditions | Shou (Ripe) Pu-erh |
The distinction between CTC and orthodox processing is fundamental: CTC produces small, uniform granules that brew quickly and strongly (ideal for tea bags and chai), while orthodox processing preserves whole leaves with more nuanced, complex flavor (ideal for gongfu brewing).
Learn more: Processing Methods · Tea Glossary
TeaFYI catalogs 15 teaware items with materials, origins, and recommended uses. The brewing vessel profoundly affects tea character -- porous Yixing clay absorbs tea oils over time, while glass and porcelain offer neutral, clean extraction:
| Teaware | Material | Origin | Best For |
|---|---|---|---|
| Gaiwan | Porcelain | China | Universal, gongfu brewing |
| Yixing Teapot | Zisha clay | Yixing, China | Oolong, Pu-erh, dedicated to one tea type |
| Kyusu | Ceramic | Japan | Japanese green tea (sencha, gyokuro) |
| Tetsubin | Cast iron | Japan | Boiling water, heat retention |
| Glass Teapot | Borosilicate | Modern | Flowering tea, visual appreciation |
| Chasen | Bamboo whisk | Japan | Matcha preparation |
Learn more: Teaware Guide · Brewing Guides
| Concept | Description |
|---|---|
| First Flush | First spring harvest, prized for freshness and delicacy (Darjeeling, Shincha) |
| Second Flush | Summer harvest, fuller body and muscatel character |
| Terroir | Altitude, soil, climate, and fog patterns that create regional character |
| Gongfu Cha | Chinese brewing method: small vessel, high leaf ratio, multiple short infusions |
| Caffeine Content | Varies by processing: matcha highest (~70mg/cup), white tea lowest (~15-30mg/cup) |
| L-Theanine | Amino acid unique to tea, promotes calm alertness, highest in shade-grown teas |
Learn more: Tea Science · Tea Compounds
All endpoints are free, require no authentication, and return JSON with CORS enabled.
| Method | Endpoint | Description |
|---|---|---|
| GET | /api/v1/teas/ |
List all 60 tea varieties |
| GET | /api/v1/teas/{slug}/ |
Tea variety detail with brewing params |
| GET | /api/v1/origins/ |
List all 15 origin countries |
| GET | /api/v1/origins/{slug}/ |
Origin detail with regions, climate |
| GET | /api/v1/teaware/ |
List all 15 teaware items |
| GET | /api/v1/teaware/{slug}/ |
Teaware detail with materials, use |
| GET | /api/v1/glossary/ |
List all tea terminology |
| GET | /api/v1/glossary/{slug}/ |
Glossary term definition |
| GET | /api/v1/search/?q={query} |
Search across all content |
| GET | /api/v1/compare/{slug1}/{slug2}/ |
Compare two tea varieties |
| GET | /api/v1/random/ |
Random tea variety |
| GET | /api/v1/guides/ |
List all 120 guides |
| GET | /api/v1/guides/{slug}/ |
Guide detail |
| GET | /api/v1/openapi.json |
OpenAPI 3.1.0 specification |
curl -s "https://teafyi.com/api/v1/teas/matcha/"{
"slug": "matcha",
"name": "Matcha",
"category": "Green",
"description": "Stone-ground Japanese green tea powder made from shade-grown tencha leaves, whisked with hot water for a rich, umami-forward brew.",
"origin": "Japan",
"oxidation": "0%",
"caffeine": "high",
"flavor_profile": ["umami", "vegetal", "sweet", "creamy"],
"brewing": {
"temperature": "70-80C",
"amount": "2g per 60ml",
"method": "Whisk with chasen until frothy"
},
"url": "https://teafyi.com/teas/matcha/"
}Full API documentation: teafyi.com/developers/. OpenAPI 3.1.0 spec: teafyi.com/api/v1/openapi.json.
# Search tea varieties, origins, teaware
teafyi search "matcha"
teafyi search "oolong"
teafyi search "gongfu ceremony"
teafyi search "darjeeling"
# Look up tea terminology
teafyi term "oxidation"
teafyi term "first-flush"
teafyi term "gaiwan"The CLI displays results in formatted tables with rich terminal output.
Run as an MCP server for AI-assisted tea queries:
python -m teafyi.mcp_serverClaude Desktop (~/.claude/claude_desktop_config.json):
{
"mcpServers": {
"teafyi": {
"command": "uvx",
"args": ["--from", "teafyi[mcp]", "python", "-m", "teafyi.mcp_server"]
}
}
}Tools: tea_search, tea_glossary_term
from teafyi.api import TeaFYI
with TeaFYI() as api:
# Search across teas, origins, teaware, glossary
results = api.search("oolong")
# Look up tea terminology
term = api.glossary_term("gongfu")
print(term["definition"])
# Compare two tea varieties
comparison = api.compare("sencha", "matcha")
# Get a random tea variety
random_tea = api.random()- Reference: Tea Varieties | Origins | Teaware
- Glossary: Tea Terminology
- Guides: Tea Guides
- Compare: Tea Comparisons
- API: Developer Docs | OpenAPI Spec
Part of the FYIPedia open-source developer tools ecosystem -- world beverages from cocktails to sake.
| Site | Domain | Focus |
|---|---|---|
| CocktailFYI | cocktailfyi.com | 636 cocktails, ABV, calories, flavor profiles |
| VinoFYI | vinofyi.com | Wines, grapes, regions, wineries, food pairings |
| BeerFYI | beerfyi.com | 112 beer styles, hops, malts, yeast, BJCP |
| BrewFYI | brewfyi.com | 72 coffee varieties, roasting, 21 brew methods |
| WhiskeyFYI | whiskeyfyi.com | 80 whiskey expressions, distilleries, regions |
| TeaFYI | teafyi.com | 60 tea varieties, teaware, brewing guides |
| NihonshuFYI | nihonshufyi.com | 80 sake, rice varieties, 50 breweries |
MIT