Developer Documentation

Integrate NihonshuFYI data into your applications. Access sake products, breweries, grades, rice varieties, glossary terms, and guides through our JSON APIs and machine-readable endpoints.

API Demo

API Endpoints

All API endpoints return JSON responses with Content-Type: application/json. No authentication is required. Free to use.

Endpoint	Description	Cache
`GET /api/sake/{slug}/`	Full sake detail with brewery, grade, rice, yeast, flavor profile	1h
`GET /api/brewery/{slug}/`	Brewery detail with prefecture, toji school, production	1h
`GET /api/search/?q=`	Search across 8 entity types (English + Japanese names)	5m
`GET /api/term/{slug}/`	Glossary term with Japanese translation and related terms	1h
`GET /api/compare/?slug1=&slug2=`	Compare two sake grades (polishing, alcohol, serving)	1h
`GET /api/grade/{slug}/`	Sake grade classification detail	1h
`GET /api/rice/{slug}/`	Sake rice variety with grain characteristics	1h
`GET /api/yeast/{slug}/`	Yeast strain with aroma and fermentation profile	1h
`GET /api/random/`	Random sake with full detail	none
`GET /api/openapi.json`	OpenAPI 3.1.0 spec (CORS enabled)	none

Search API

Searches both English and Japanese names across all entity types.

GET /api/search/?q={query}

curl "https://nihonshufyi.com/api/search/?q=junmai"

{
  "results": [
    {"name": "Junmai", "slug": "junmai", "type": "grade", "url": "/grades/junmai/"},
    {"name": "Junmai Daiginjo", "slug": "junmai-daiginjo", "type": "grade", "url": "/grades/junmai-daiginjo/"}
  ],
  "total": 2
}

Sake Detail

GET /api/sake/{slug}/

curl "https://nihonshufyi.com/api/sake/dassai-23/"

{
  "name": "Dassai 23",
  "slug": "dassai-23",
  "japanese_name": "\u7370\u796d \u4e8c\u5272\u4e09\u5206",
  "url": "/sake/dassai-23/",
  "brewery": {"name": "Asahi Shuzo", "slug": "asahi-shuzo", "japanese_name": "\u65ed\u9152\u9020"},
  "grade": {"name": "Junmai Daiginjo", "slug": "junmai-daiginjo", "japanese_name": "\u7d14\u7c73\u5927\u541f\u91b8"},
  "rice": {"name": "Yamada Nishiki", "slug": "yamada-nishiki", "japanese_name": "\u5c71\u7530\u9326"},
  "yeast_strains": [],
  "polishing_ratio": 23.0,
  "abv": 16.0,
  "smv": 4,
  "acidity": 1.1,
  "amino_acid": null,
  "flavor_profile": {
    "fruity": 9.0, "floral": 8.5, "rice": 3.0, "umami": 4.0,
    "earthy": 1.0, "herbal": 1.5, "lactic": 0.5, "aged": 0.5,
    "sweet": 5.0, "dry": 6.0
  }
}

Glossary Term

GET /api/term/{slug}/

curl "https://nihonshufyi.com/api/term/koji/"

{
  "term": "Koji",
  "slug": "koji",
  "japanese_term": "\u9eb9",
  "definition": "A mold (Aspergillus oryzae) cultivated on steamed rice to convert starch into fermentable sugars.",
  "extended_description": "...",
  "category": "Brewing Process",
  "related_terms": [{"term": "Koji-kin", "slug": "koji-kin", "url": "/glossary/koji-kin/"}],
  "url": "/glossary/koji/"
}

AI / LLM Integration

NihonshuFYI provides machine-readable content summaries following the llms.txt standard. These endpoints help AI models understand and reference our content.

/llms.txt text/plain

A concise summary of NihonshuFYI's content structure and key pages. Designed for AI models to quickly understand what the site offers and how it is organized.

Markdown Endpoints: Append .md to any page URL to get a machine-readable markdown version. Example: nihonshufyi.com/sake/dassai-23.md

SEO & Standards

Standard endpoints for search engines, crawlers, and security researchers.

Endpoint	Standard	Description
/sitemap.xml	Sitemaps 0.9	Sitemap index with per-section sitemaps covering all content types
/robots.txt	REP	Crawler directives with explicit AI bot permissions
/.well-known/security.txt	RFC 9116	Security vulnerability reporting contact information

Structured Data

Every page includes JSON-LD structured data for rich search results:

Product — sake detail pages with brewery, grade, and tasting notes
Article — guide pages with author, dates, and reading time
DefinedTerm — glossary terms with Japanese translations
BreadcrumbList — navigation breadcrumbs on all pages
WebSite — with SearchAction for sitelinks search box

Internationalization

All content pages include hreflang alternate links for 15 languages: English (default), Korean, Japanese, Chinese (Simplified), Spanish, French, German, Portuguese, Russian, Arabic, Hindi, Thai, Vietnamese, Indonesian, and Turkish.

OpenAPI Specification

A machine-readable OpenAPI 3.1.0 specification is available for our JSON APIs. Use it with tools like Swagger UI, Postman, or code generators.

Download openapi.json

Fetch via command line

# Download the OpenAPI spec
curl "https://nihonshufyi.com/api/openapi.json" -o openapi.json

# Pretty-print
curl -s "https://nihonshufyi.com/api/openapi.json" | python -m json.tool

Rate Limits & Usage

Our APIs are free to use with no authentication required. To ensure fair access for everyone, please follow these guidelines:

Keep requests under 60 requests per minute per IP address
Include a descriptive User-Agent header identifying your application
Cache responses locally when possible — our API responses include Cache-Control headers
For bulk data access, use the sitemap to discover all URLs, then scrape individual pages

If you need higher-volume access or have integration questions, reach out via the contact in our security.txt.

Quick Reference

Sake Detail /api/sake/{slug}/

Brewery Detail /api/brewery/{slug}/

Search /api/search/?q=...

Glossary Term /api/term/{slug}/

Compare Grades /api/compare/?slug1=&slug2=

Grade Detail /api/grade/{slug}/

Rice Detail /api/rice/{slug}/

Yeast Detail /api/yeast/{slug}/

Random Sake /api/random/

OpenAPI Spec /api/openapi.json

llms.txt /llms.txt

Markdown any-page.md