Vivino API: Search wines
Finds 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.
Unofficial. Not affiliated with or endorsed by Vivino.
Inputs
Values from the run on Oct 31, 2026, shown under Output.
- Wine, required
wine Wine name, optionally including the winery. For example, Caymus Cabernet Sauvignon.
Dom Perignon
- Vintage optional
vintage Only return this vintage year, for example 2021. Omit for all vintages.
Not set
Whole number from 1800 to 2100.
- Max Results optional
max_results Maximum wines to return, for example 10; default 10 and maximum 25.
25
Whole number from 1 to 25. Default
10.
Input as JSON
{ "wine": "Dom Perignon", "max_results": 25}Output
{ "wines": [ { "region": "Champagne", "winery": "Dom Pérignon", "country": "France", "wine_name": "Brut Champagne", "wine_type": "Sparkling", "vivino_link": "https://www.vivino.com/en/dom-perignon-brut-champagne/w/86684?year=2009" , "vintage_year": 2009, "currency_code": "USD", "typical_price": 664, "average_rating": 4.6, "vivino_wine_id": 86684, "bottle_photo_link": "https://images.vivino.com/thumbs/s5aXYaQiTu-V_xEYI3KXRg_pb_x600.png" , "number_of_ratings": 16976 }, { "region": "Champagne", "winery": "Dom Pérignon", "country": "France", "wine_name": "Brut Champagne", "wine_type": "Sparkling", "vivino_link": "https://www.vivino.com/en/dom-perignon-brut-champagne/w/86684?year=1999" , "vintage_year": 1999, "currency_code": "USD", "typical_price": 836, "average_rating": 4.6, "vivino_wine_id": 86684, "bottle_photo_link": "https://images.vivino.com/thumbs/s5aXYaQiTu-V_xEYI3KXRg_pb_x600.png" , "number_of_ratings": 3508 }, { "region": "Champagne", "winery": "Dom Pérignon", "country": "France", "wine_name": "Brut Champagne", "wine_type": "Sparkling", "vivino_link": "https://www.vivino.com/en/dom-perignon-brut-champagne/w/86684?year=1993" , "vintage_year": 1993, "currency_code": "USD", "typical_price": 606, "average_rating": 4.6, "vivino_wine_id": 86684, "bottle_photo_link": "https://images.vivino.com/thumbs/s5aXYaQiTu-V_xEYI3KXRg_pb_x600.png" , "number_of_ratings": 1723 } ]}Code
curl https://api.fous.com/v1/runs \ -H "Authorization: Bearer $FOUS_API_KEY" \ -H "Content-Type: application/json" \ -d '{"method":"vivino.com/search_wines","input":{"wine":"Dom Perignon","max_results":25}}' # 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/search_wines" , "input": { "wine": "Dom Perignon", "max_results": 25 }})# 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/search_wines" , "input": { "wine": "Dom Perignon", "max_results": 25 } }), 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/search_wines# with {"wine":"Dom Perignon","max_results":25}"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" ], "properties": { "wine": { "type": "string", "minLength": 1, "description": "Wine name, optionally including the winery. For example, Caymus Cabernet Sauvignon." }, "vintage": { "type": "integer", "maximum": 2100, "minimum": 1800, "description": "Only return this vintage year, for example 2021. Omit for all vintages." }, "max_results": { "type": "integer", "default": 10, "maximum": 25, "minimum": 1, "description": "Maximum wines to return, for example 10; default 10 and maximum 25." } }}Output schema
{ "type": "object", "required": [ "wines" ], "properties": { "wines": { "type": "array", "items": { "type": "object", "required": [ "wine_name", "winery", "vintage_year", "wine_type", "region", "country", "average_rating", "number_of_ratings", "typical_price", "currency_code", "bottle_photo_link", "vivino_link", "vivino_wine_id" ], "properties": { "region": { "type": [ "string", "null" ], "description": "Wine region." }, "winery": { "type": [ "string", "null" ], "description": "Winery name." }, "country": { "type": [ "string", "null" ], "description": "Country of origin." }, "wine_name": { "type": "string", "description": "Wine name." }, "wine_type": { "type": [ "string", "null" ], "description": "Wine type, such as Red or Sparkling." }, "vivino_link": { "type": "string", "description": "Wine page on Vivino." }, "vintage_year": { "type": [ "integer", "null" ], "description": "Vintage year when known." }, "currency_code": { "type": [ "string", "null" ], "description": "Currency for the displayed price, normally USD." }, "typical_price": { "type": [ "number", "null" ], "description": "Price shown for US visitors, when available." }, "average_rating": { "type": [ "number", "null" ], "description": "Average Vivino rating out of 5." }, "vivino_wine_id": { "type": "integer", "description": "Vivino wine identifier.", "x-fous-developer": true }, "bottle_photo_link": { "type": [ "string", "null" ], "description": "Bottle photo link, when available." }, "number_of_ratings": { "type": [ "integer", "null" ], "description": "Number of Vivino ratings." } }, "additionalProperties": false }, "description": "Matching wines, most relevant first." } }, "additionalProperties": false}- Price
- 1 credit per completed run (1¢ with pay as you go); failed runs are free.
- Method
vivino.com/search_wines- Returns
- wine name, winery, vintage, type, region, country, average rating, rating count, US price, bottle photo, Vivino link, wine ID
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/search_wines with the inputs above.
Ask your agent
- Look up Opus One 2018 on Vivino and tell me its average rating and how many people rated it
- What's the US price and region for Cloudy Bay Sauvignon Blanc? Show me the top 5 matches
- Find ratings for Château Montelena Chardonnay, 2019 vintage only
- I'm holding a bottle of Duckhorn Merlot — pull up up to 15 Vivino listings with ratings, prices and bottle photos
- Search for Whispering Angel rosé and give me the winery, country, rating count and link for each result
See more
All Vivino methodsLists 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.
vivino.com/list_recommended_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_listingsFinds tours and experiences in a city on Viator, with optional keywords, date, currency and sorting. Prices are starting prices.
viator.com/search_toursSearch 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_productsFinds Rust crates on crates.io by keywords, sorted by relevance, total downloads, recent downloads, or newest creation.
crates.io/search_cratesSearches a named Instacart store's guest-visible grocery products for a US ZIP code. Prices are in USD and can differ from in-store prices; stock estimates can change.
instacart.com/search_productsSearches Sephora US beauty products in Sephora's order, with brand and USD price filters and shopper sort options. Loves counts are null when a product page cannot be loaded.
sephora.com/search_productsFinds iPhone and iPad apps by keyword in a chosen country's App Store, with ratings, prices, categories and App Store links.
apps.apple.com/search_apps