teafyi 0.1.3

Tea knowledge API client — search tea varieties, processing methods, and terms from TeaFYI.

teafyi

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

Table of Contents

• Install
• Quick Start
• What You'll Find on TeaFYI
  • Tea Categories by Oxidation
  • Processing Methods
  • Teaware
  • Key Tea Concepts
• API Endpoints
• Command-Line Interface
• MCP Server (Claude, Cursor, Windsurf)
• API Client
• Learn More About Tea
• Beverage FYI Family
• License

Install

pip install teafyi[api]     # API client (httpx)
pip install teafyi[cli]     # + CLI (typer, rich)
pip install teafyi[mcp]     # + MCP server
pip install teafyi[all]     # Everything

Quick Start

from 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"])

What You'll Find on TeaFYI

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 Categories by 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

Processing Methods

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

Teaware

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

Key Tea Concepts

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

API Endpoints

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

Example

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.

Command-Line Interface

# 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.

MCP Server (Claude, Cursor, Windsurf)

Run as an MCP server for AI-assisted tea queries:

python -m teafyi.mcp_server

Claude 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

API Client

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()

Learn More About Tea

• Reference: Tea Varieties | Origins | Teaware
• Glossary: Tea Terminology
• Guides: Tea Guides
• Compare: Tea Comparisons
• API: Developer Docs | OpenAPI Spec

Beverage FYI Family

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

License

MIT