Vivino API: List recommended wines
Lists top-rated wines of a chosen type within a budget, from bottles offered in the United States, optionally limited to one grape and country of origin. Prices are in USD.
Unofficial. Not affiliated with or endorsed by Vivino.
Inputs
Values from the run on Oct 31, 2026, shown under Output.
- Grape optional
grape Grape variety, for example Pinot Noir. Omit for any grape.
Not set
- Country optional
country Country of origin, for example Italy. Omit for any country.
Not set
- Max Price optional
max_price Highest USD bottle price, for example 50. Omit for no practical price limit.
30
Number 0 or more.
- Wine Type, required
wine_type Wine type, for example red.
white
One of
red,white,sparkling,rose,dessert,fortified.- Min Rating optional
min_rating Minimum average rating out of five, for example 4.0.
3.5
Number from 1 to 5. Default
3.5.- Max Results optional
max_results Maximum wines to return, for example 20 (up to 50).
30
Whole number from 1 to 50. Default
20.
Input as JSON
{ "max_price": 30, "wine_type": "white", "min_rating": 3.5, "max_results": 30}Output
{ "wines": [ { "price": 22.6, "region": "Napa Valley", "winery": "Black Stallion", "country": "United States", "vintage": "2024", "currency": "USD", "wine_name": "Chardonnay", "vivino_link": "https://www.vivino.com/en/black-stallion-chardonnay-napa-valley/w/13819478?year=2024&price_id=42123915" , "average_rating": 4.6, "bottle_photo_link": null, "number_of_ratings": 28 }, { "price": 19.95, "region": "Picpoul de Pinet", "winery": "Le Jade", "country": "France", "vintage": "2024", "currency": "USD", "wine_name": "Picpoul de Pinet", "vivino_link": "https://www.vivino.com/en/le-jade-picpoul-de-pinet/w/1827746?year=2024&price_id=43440665" , "average_rating": 4.5, "bottle_photo_link": "https://images.vivino.com/thumbs/HK6-9S8oT8K_c3a9BtOiqA_pb_x600.png" , "number_of_ratings": 45 }, { "price": 29.99, "region": "Weinviertel", "winery": "Ruttenstock", "country": "Austria", "vintage": "2025", "currency": "USD", "wine_name": "Ried Reipersberg", "vivino_link": "https://www.vivino.com/en/ruttenstock-weinviertel-reipersberg-gruner-veltliner/w/2910395?year=2025&price_id=42426364" , "average_rating": 4.5, "bottle_photo_link": "https://images.vivino.com/thumbs/2KqZsLy7RsK5SNDPog5Nhw_pb_x600.png" , "number_of_ratings": 26 } ]}Code
curl https://api.fous.com/v1/runs \ -H "Authorization: Bearer $FOUS_API_KEY" \ -H "Content-Type: application/json" \ -d '{"method":"vivino.com/list_recommended_wines","input":{"max_price":30,"wine_type":"white","min_rating":3.5,"max_results":30}}' # Save as fous.py, then run: python3 fous.pyimport json, os, timefrom urllib.error import HTTPErrorfrom urllib.request import Request, urlopenAPI = "https://api.fous.com/v1/runs" KEY = os.environ["FOUS_API_KEY"]HEADERS = { "Authorization": f"Bearer {KEY}", "Content-Type": "application/json" ,}def call(url, body=None): data = json.dumps(body).encode() if body else None request = Request(url, data, HEADERS) try: with urlopen(request, timeout=120) as r: return r.status, json.load(r) except HTTPError as error: message = json.load(error)["error"]["message"] raise RuntimeError(message) from errorstatus, run = call(API, { "method": "vivino.com/list_recommended_wines" , "input": { "max_price": 30, "wine_type": "white", "min_rating": 3.5, "max_results": 30 }})# 202: still going after 30 s. Ask again until it ends.while status == 202: time.sleep(2) status, run = call(f"{API}/{run['id']}")print(json.dumps(run["data"], indent=2))// Save as fous.mjs, then run: node fous.mjsconst api = "https://api.fous.com/v1/runs" ;const headers = { Authorization: `Bearer ${process.env.FOUS_API_KEY}`, "Content-Type": "application/json" ,};let response = await fetch(api, { method: "POST", headers, body: JSON.stringify({ "method": "vivino.com/list_recommended_wines" , "input": { "max_price": 30, "wine_type": "white", "min_rating": 3.5, "max_results": 30 } }), signal: AbortSignal.timeout(120_000),});let run = await response.json();// 202: still going after 30 s. Ask again until it ends.while (response.status === 202) { await new Promise((done) => setTimeout(done, 2_000)); response = await fetch(`${api}/${run.id}`, { headers }); run = await response.json();}if (!response.ok) throw new Error(run.error.message);console.log(run.data);# Connect your agent to Fous once, over MCP (Streamable HTTP):# https://api.fous.com/mcp# Set FOUS_API_KEY first: create a key at https://app.fous.com/keys.# Claude Codeclaude mcp add \ --scope user \ --transport http fous https://api.fous.com/mcp \ --header "Authorization: Bearer ${FOUS_API_KEY:?Set FOUS_API_KEY to your Fous API key}"# Codexcodex mcp add fous \ --url https://api.fous.com/mcp \ --bearer-token-env-var FOUS_API_KEY# Cursor, VS Code, Windsurf, Cline and morenpx -y add-mcp https://api.fous.com/mcp -g -n fous \ --header "Authorization: Bearer ${FOUS_API_KEY:?Set FOUS_API_KEY to your Fous API key}"# Then ask your agent:# "Use Fous to run vivino.com/list_recommended_wines# with {"max_price":30,"wine_type":"white","min_rating":3.5,"max_results":30}"Over HTTP, the answer’s data holds the output. A run still going after 30 seconds answers 202 with its id: ask GET /v1/runs/{id} until it ends.
Schema
Input schema
{ "type": "object", "required": [ "wine_type" ], "properties": { "grape": { "type": "string", "description": "Grape variety, for example Pinot Noir. Omit for any grape." }, "country": { "type": "string", "description": "Country of origin, for example Italy. Omit for any country." }, "max_price": { "type": "number", "minimum": 0, "description": "Highest USD bottle price, for example 50. Omit for no practical price limit." }, "wine_type": { "enum": [ "red", "white", "sparkling", "rose", "dessert", "fortified" ], "type": "string", "description": "Wine type, for example red." }, "min_rating": { "type": "number", "default": 3.5, "maximum": 5, "minimum": 1, "description": "Minimum average rating out of five, for example 4.0." }, "max_results": { "type": "integer", "default": 20, "maximum": 50, "minimum": 1, "description": "Maximum wines to return, for example 20 (up to 50).", "x-fous-developer": true } }}Output schema
{ "type": "object", "required": [ "wines" ], "properties": { "wines": { "type": "array", "items": { "type": "object", "required": [ "wine_name", "winery", "vintage", "region", "country", "average_rating", "number_of_ratings", "price", "currency", "bottle_photo_link", "vivino_link" ], "properties": { "price": { "type": "number", "description": "Offered bottle price." }, "region": { "type": [ "string", "null" ], "description": "Wine region." }, "winery": { "type": [ "string", "null" ], "description": "Winery name." }, "country": { "type": [ "string", "null" ], "description": "Country of origin." }, "vintage": { "type": [ "string", "null" ], "description": "Vintage year or N.V. if available." }, "currency": { "type": "string", "description": "Price currency code." }, "wine_name": { "type": [ "string", "null" ], "description": "Name of the wine." }, "vivino_link": { "type": "string", "description": "Wine page URL." }, "average_rating": { "type": [ "number", "null" ], "description": "Average rating out of five." }, "bottle_photo_link": { "type": [ "string", "null" ], "description": "Bottle image URL." }, "number_of_ratings": { "type": [ "integer", "null" ], "description": "Number of ratings." } }, "additionalProperties": false }, "description": "Highest-rated matching wines first." } }, "additionalProperties": false}- Price
- 1 credit per completed run (1¢ with pay as you go); failed runs are free.
- Method
vivino.com/list_recommended_wines- Returns
- wine name, winery, vintage, region, country, average rating, number of ratings, price, bottle photo, Vivino link
Use it from your agent
Give your agent this line. It reads SKILL.md, gets a Fous API key and connects the Fous MCP server. Its run then takes the method vivino.com/list_recommended_wines with the inputs above.
Ask your agent
- Find me some highly rated Malbecs from Argentina under $25 a bottle that I can buy in the US.
- What are the best-rated sparkling wines on Vivino for under $40, rated at least 4.0?
- I need a good dry rosé for a summer party, nothing over $20, any country is fine.
- Show me the top 10 Italian red wines made from Nebbiolo, priced up to $75, with ratings of 4.2 or higher.
- Looking for well-reviewed dessert wines available in the United States under $50 — pull the top picks from vivino.com with photos and links.
See more
All Vivino methodsFinds Vivino wines matching a wine name (optionally with the winery and a vintage year), in Vivino relevance order, with ratings, vintage, origin, bottle photo and the US price when shown.
vivino.com/search_winesSearches public Vinted listings in one country with brand, size, condition, price and sorting filters. Returns up to 96 available items with seller usernames when the public profile is available.
vinted.com/search_listingsLists Tripadvisor's ranked restaurants in a city from the first results page, optionally filtered by cuisine and price category. Sponsored listings are left out; up to 30 restaurants with rating, review count, cuisines, price range and address.
tripadvisor.com/list_top_restaurantsFinds tours and experiences in a city on Viator, with optional keywords, date, currency and sorting. Prices are starting prices.
viator.com/search_toursLists Michelin Guide restaurants in a city or region, in Guide order, optionally filtered by distinction and cuisine, with each restaurant's address, description and photo. Results may include the surrounding area as labeled by the Guide.
guide.michelin.com/search_restaurantsSearch Chewy products by words, pet type, and sort order. Returns up to 72 products in Chewy's order, including listed and first-order Autoship prices when shown.
chewy.com/search_productsSearches AliExpress listings by product words, shipping destination, price range and sort order. Unpriced promotional cards are omitted; free shipping is marked only when the listing explicitly says so.
aliexpress.com/search_productsSearches IKEA products in a chosen country and returns current prices, details, photos and reviews in IKEA's result order.
ikea.com/search_products