API Reference

TheWineTrip REST API — access wine regions, winery data, and itineraries programmatically

Download OpenAPI Spec View in Swagger UI ↗

Base URL

https://thewinetrip.com/api/v1

Authentication

Free Tier

No API key required · 100 requests/day · All region endpoints

Pro Tier ($29/mo)

10,000 requests/day · Full winery dataset · Affiliate URLs · Priority support

Rate-Limit Headers

Every API response includes informational rate-limit headers. Enforcement is applied per API key on Pro tier.

X-RateLimit-Limit: 100

X-RateLimit-Plan: free

X-RateLimit-Reset: 1741996800 // epoch seconds — next UTC midnight

Endpoints

GET/api/v1/regions/{slug}

Returns region metadata, wine guide data, and up to 50 wineries with affiliate URLs.

Available regions

napa bordeaux tuscany rioja barossa champagne burgundy douro mendoza willamette alsace mosel priorat rioja-alta mclaren-vale hunter-valley stellenbosch wachau

Example request

curl \

"$https://thewinetrip.com/api/v1/regions/napa"

GET/api/v1/wineries?region={slug}

Search GPS-mapped wineries for a region. Optional q (name search) and limit (max 200) params.

// Search Napa wineries by name

GET /api/v1/wineries?region=napa&q=opus&limit=10

GET/api/v1/plan?region={slug}&days={n}&style={style}

Generate a structured day-by-day itinerary via query params. Identical response shape to POST. Styles: romantic, serious, budget, luxury. Days default to 3 if omitted.

// Quick GET — no body needed

GET /api/v1/plan?region=napa&days=3&style=romantic

GET /api/v1/plan?region=douro&days=4&style=luxury&interests=Port wine,river cruises

POST/api/v1/plan

Generate a structured day-by-day itinerary via JSON body. Returns JSON suitable for AI agents, apps, and direct rendering.

// Request body

{

"region": "douro",

"days": 4,

"style": "luxury",

"interests": ["Port wine", "river cruises"]

}

POST/api/save-trip

Save a trip itinerary. Returns an ID that can be used to share the trip via /trip/{id}.

// Request body

{

"region": "napa",

"days": 3,

"style": "romantic",

"interests": ["Tasting rooms", "Food pairing"]

}

MCP Server

thewinetrip-mcp-server

Compatible with Claude Desktop, Claude API, and any MCP-capable AI agent. Access wine region data directly from your AI workflow.

npm install -g thewinetrip-mcp-server

Claude Desktop config:

{ "mcpServers": { "thewinetrip": { "command": "npx", "args": ["-y", "thewinetrip-mcp-server"] } } }

Tools: list_regions · get_region · get_wineries · generate_itinerary

AI Compatibility

✓

Claude (Anthropic)

✓

ChatGPT / GPT-4

✓

Any OpenAPI client

API Reference

TheWineTrip REST API — access wine regions, winery data, and itineraries programmatically

Base URL

https://thewinetrip.com/api/v1

Authentication

Free Tier

No API key required · 100 requests/day · All region endpoints

Pro Tier ($29/mo)

10,000 requests/day · Full winery dataset · Affiliate URLs · Priority support

Rate-Limit Headers

Every API response includes informational rate-limit headers. Enforcement is applied per API key on Pro tier.

X-RateLimit-Limit: 100

X-RateLimit-Plan: free

X-RateLimit-Reset: 1741996800 // epoch seconds — next UTC midnight

Endpoints

GET/api/v1/regions/{slug}

Returns region metadata, wine guide data, and up to 50 wineries with affiliate URLs.

Available regions

napa bordeaux tuscany rioja barossa champagne burgundy douro mendoza willamette alsace mosel priorat rioja-alta mclaren-vale hunter-valley stellenbosch wachau

Example request

curl \

"$https://thewinetrip.com/api/v1/regions/napa"

GET/api/v1/wineries?region={slug}

Search GPS-mapped wineries for a region. Optional q (name search) and limit (max 200) params.

// Search Napa wineries by name

GET /api/v1/wineries?region=napa&q=opus&limit=10

GET/api/v1/plan?region={slug}&days={n}&style={style}

Generate a structured day-by-day itinerary via query params. Identical response shape to POST. Styles: romantic, serious, budget, luxury. Days default to 3 if omitted.

// Quick GET — no body needed

GET /api/v1/plan?region=napa&days=3&style=romantic

GET /api/v1/plan?region=douro&days=4&style=luxury&interests=Port wine,river cruises

POST/api/v1/plan

Generate a structured day-by-day itinerary via JSON body. Returns JSON suitable for AI agents, apps, and direct rendering.

// Request body

{

"region": "douro",

"days": 4,

"style": "luxury",

"interests": ["Port wine", "river cruises"]

}

POST/api/save-trip

Save a trip itinerary. Returns an ID that can be used to share the trip via /trip/{id}.

// Request body

{

"region": "napa",

"days": 3,

"style": "romantic",

"interests": ["Tasting rooms", "Food pairing"]

}

MCP Server

thewinetrip-mcp-server

Compatible with Claude Desktop, Claude API, and any MCP-capable AI agent. Access wine region data directly from your AI workflow.

npm install -g thewinetrip-mcp-server

Claude Desktop config:

{ "mcpServers": { "thewinetrip": { "command": "npx", "args": ["-y", "thewinetrip-mcp-server"] } } }

Tools: list_regions · get_region · get_wineries · generate_itinerary

AI Compatibility

✓

Claude (Anthropic)

✓

ChatGPT / GPT-4

✓

Any OpenAPI client