teafyi 0.1.1

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
• FYIPedia Developer Tools
• 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

Site	Domain	Focus
CocktailFYI	cocktailfyi.com	636 cocktail recipes, ABV, calories, flavor profiles
VinoFYI	vinofyi.com	Wines, grapes, regions, wineries, food pairings
BeerFYI	beerfyi.com	112 beer styles, hops, malts, yeast, brewing guides
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

FYIPedia Developer Tools

Package	PyPI	npm	Description
colorfyi	PyPI	npm	Color conversion, WCAG contrast, harmonies -- colorfyi.com
emojifyi	PyPI	npm	Emoji encoding & metadata for 3,953 emojis -- emojifyi.com
symbolfyi	PyPI	npm	Symbol encoding in 11 formats -- symbolfyi.com
unicodefyi	PyPI	npm	Unicode lookup with 17 encodings -- unicodefyi.com
fontfyi	PyPI	npm	Google Fonts metadata & CSS -- fontfyi.com
distancefyi	PyPI	npm	Haversine distance & travel times -- distancefyi.com
timefyi	PyPI	npm	Timezone ops & business hours -- timefyi.com
namefyi	PyPI	npm	Korean romanization & Five Elements -- namefyi.com
unitfyi	PyPI	npm	Unit conversion, 220 units -- unitfyi.com
holidayfyi	PyPI	npm	Holiday dates & Easter calculation -- holidayfyi.com
cocktailfyi	PyPI	--	Cocktail ABV, calories, flavor -- cocktailfyi.com
vinofyi	PyPI	--	Wine API client -- grapes, regions, wineries -- vinofyi.com
beerfyi	PyPI	--	Beer styles, hops, malts API -- beerfyi.com
brewfyi	PyPI	--	Coffee varieties, brew methods API -- brewfyi.com
whiskeyfyi	PyPI	--	Whiskey expressions, distilleries API -- whiskeyfyi.com
teafyi	PyPI	--	Tea varieties, teaware API -- teafyi.com
nihonshufyi	PyPI	--	Sake grades, breweries API -- nihonshufyi.com
drinkfyi	PyPI	--	Unified beverage hub -- 7 sites -- fyipedia.com
fyipedia	PyPI	--	Unified CLI: fyi color info FF6B35 -- fyipedia.com
fyipedia-mcp	PyPI	--	Unified MCP hub for AI assistants -- fyipedia.com

License

MIT