Developer Documentation

Integrate VinoFYI data into your applications. Access wines, grape varieties, regions, wineries, and guides through our JSON APIs and machine-readable endpoints.

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/wine/{slug}/`	Full wine detail with grapes and food pairings	1h
`GET /api/grape/{slug}/`	Grape variety with sensory profile and aromas	1h
`GET /api/region/{slug}/`	Wine region with terroir and classification	1h
`GET /api/winery/{slug}/`	Winery detail with top-rated wines	1h
`GET /api/search/?q=`	Search across 6 entity types (grapes, regions, wines, wineries, countries, glossary)	5m
`GET /api/term/{slug}/`	Glossary term tooltip (definition, pronunciation)	1h
`GET /api/compare/?slug_a=&slug_b=`	Compare two grape varieties (sensory profiles, key differences)	1h
`GET /api/pairing/?food=`	Food pairing recommendations (wine styles for a food category)	1h
`GET /api/vintage/?region=`	Vintage chart for a wine region (quality scores by year)	1h
`GET /api/openapi.json`	OpenAPI 3.1.0 spec (CORS enabled)	none

Search API

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

curl "https://vinofyi.com/api/search/?q=cabernet"

{
  "results": [
    {"name": "Cabernet Sauvignon", "slug": "cabernet-sauvignon", "type": "grape", "url": "/grape/cabernet-sauvignon/"},
    {"name": "Cabernet Franc", "slug": "cabernet-franc", "type": "grape", "url": "/grape/cabernet-franc/"}
  ],
  "total": 2
}

Wine Detail

GET /api/wine/{slug}/

{
  "name": "Opus One 2019",
  "slug": "opus-one-2019",
  "wine_type": "Red",
  "abv": 14.5,
  "body": "Full",
  "acidity": "Medium",
  "region": "Napa Valley",
  "winery": {"name": "Opus One", "slug": "opus-one"},
  "grapes": [
    {"name": "Cabernet Sauvignon", "slug": "cabernet-sauvignon", "percentage": 84.0, "is_primary": true},
    {"name": "Petit Verdot", "slug": "petit-verdot", "percentage": 7.0, "is_primary": false}
  ],
  "food_pairings": [
    {"name": "Beef", "slug": "beef", "affinity_score": 95}
  ]
}

Food Pairing

Get wine style recommendations for a food category.

GET /api/pairing/?food={slug}

curl "https://vinofyi.com/api/pairing/?food=beef"

{
  "food": {"name": "Beef", "slug": "beef"},
  "pairings": [
    {"style": {"name": "Bordeaux Red", "slug": "bordeaux-red"}, "affinity_score": 95, "explanation": "..."}
  ]
}

Glossary Term

GET /api/term/{slug}/

curl "https://vinofyi.com/api/term/terroir/"

{
  "term": "Terroir",
  "slug": "terroir",
  "definition": "The complete natural environment in which wine is produced.",
  "pronunciation": "teh-RWAHR",
  "category": "Viticulture",
  "difficulty_level": "intermediate",
  "url": "/glossary/terroir/"
}

AI / LLM Integration

VinoFYI 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 VinoFYI's content structure and key pages. Designed for AI models to quickly understand what the site offers and how it is organized.

/llms-full.txt text/plain

Extended version with complete URL patterns, i18n language codes, and page-level structure.

AI Crawler Policy: Our robots.txt explicitly allows GPTBot, ClaudeBot, and Google-Extended crawlers.

SEO & Standards

Endpoint	Standard	Description
/sitemap.xml	Sitemaps 0.9	Sitemap index with 20 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

BreadcrumbList — navigation breadcrumbs on all pages
WebSite — with SearchAction for sitelinks search box
Article — guide pages with author, dates, and word count
DefinedTerm — glossary terms with definitions
Place — wine regions with coordinates
Organization — winery profiles

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://vinofyi.com/api/openapi.json" -o openapi.json

# Pretty-print
curl -s "https://vinofyi.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

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

Quick Reference

Wine Detail /api/wine/{slug}/

Grape Detail /api/grape/{slug}/

Region Detail /api/region/{slug}/

Winery Detail /api/winery/{slug}/

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

Glossary Term /api/term/{slug}/

Compare Grapes /api/compare/?slug_a=&slug_b=

Food Pairing /api/pairing/?food=...

Vintage Chart /api/vintage/?region=...

OpenAPI Spec /api/openapi.json

llms.txt /llms.txt