# Vivino Wine Scraper - Ratings, Prices & Vintages (`mrbridge/vivino-powerful-scraper`) Actor Extract wine data from Vivino: ratings, reviews, prices, vintages, taste profiles. Filter by region (Burgundy, Bordeaux, Champagne...), grape variety, producer. Use it for wine list building, market research, cellar tracking, or producer comparison. - **URL**: https://apify.com/mrbridge/vivino-powerful-scraper.md - **Developed by:** [MrBridge](https://apify.com/mrbridge) (community) - **Categories:** E-commerce, Automation - **Stats:** 74 total users, 4 monthly users, 100.0% runs succeeded, 0 bookmarks - **User rating**: 5.00 out of 5 stars ## Pricing from $3.00 / 1,000 results This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events. Since this Actor supports Apify Store discounts, the price gets lower the higher subscription plan you have. Learn more: https://docs.apify.com/platform/actors/running/actors-in-store#pay-per-event ## What's an Apify Actor? Actors are a software tools running on the Apify platform, for all kinds of web data extraction and automation use cases. In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours, and optionally produces a well-defined JSON output, datasets with results, or files in key-value store. In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server. Actors are written with capital "A". ## How to integrate an Actor? If asked about integration, you help developers integrate Actors into their projects. You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready. The best way to integrate Actors is as follows. In JavaScript/TypeScript projects, use official [JavaScript/TypeScript client](https://docs.apify.com/api/client/js.md): ```bash npm install apify-client ``` In Python projects, use official [Python client library](https://docs.apify.com/api/client/python.md): ```bash pip install apify-client ``` In shell scripts, use [Apify CLI](https://docs.apify.com/cli/docs.md): ````bash # MacOS / Linux curl -fsSL https://apify.com/install-cli.sh | bash # Windows irm https://apify.com/install-cli.ps1 | iex ```bash In AI frameworks, you might use the [Apify MCP server](https://docs.apify.com/platform/integrations/mcp.md). If your project is in a different language, use the [REST API](https://docs.apify.com/api/v2.md). For usage examples, see the [API](#api) section below. For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt). # README ## Vivino Wine Scraper Scrape **wine data at scale** from Vivino (60M+ users, 12M+ wines). No browser, no account, no API key. HTTP only. **Filter by region (299 appellations, 32 countries), producer, grape, price or rating.** Get ratings, prices, taste profiles and year-by-year vintages in JSON, CSV or Excel. ![Vivino Scraper Input Interface](https://api.apify.com/v2/key-value-stores/ubtJJKNAtk8w6dJt2/records/vivino-apify.png) ### Which wine scraper should I use? | Need | Best scraper | What it does | |------|-----------|-------------| | Browse wines by region (Bourgogne, Italy, Napa...) | **Vivino Wine Scraper** (this one) | Scrape any region, grape, or producer; ratings, prices, taste profiles, vintages | | Look up specific wines by name or URL | [Vivino Wine Data Scraper](https://apify.com/mrbridge/vivino-wine-data-scraper?fpr=mrbridge) | Search Vivino by wine name or paste Vivino URLs | | Critic ratings (Parker, Spectator, Decanter...) | [Millesima Wine Scraper](https://apify.com/mrbridge/millesima-wine-scraper?fpr=mrbridge) | Prices + scores from 18 major critics | | Grape popularity, scores & prices | [Wine-Searcher Grape Scraper](https://apify.com/mrbridge/wine-searcher-grape-scraper?fpr=mrbridge) | Popularity, critic scores & prices by grape variety on Wine-Searcher | | Popularity, scores & prices for a known wine list | [Wine-Searcher Scraper from List](https://apify.com/mrbridge/wine-searcher-scraper-from-list?fpr=mrbridge) | Wine-Searcher data by wine name, URL or LWIN code | **In short**: use **this actor** to discover wines in a region; use the **Vivino Wine Data Scraper** when you already know which wines you want. ### At a glance: input form Five primary filters at the top of the form, followed by six dedicated sections. Just pick what you need and click **Start**. ```text ┌──── PRIMARY FILTERS ────────────────────────────────────── │ Wine Region ▸ Bourgogne ▾ (299 options) │ Wine Type ▸ White ▾ (Red, White, Sparkling…) │ Grape Variety ▸ All Grapes ▾ (21 options) │ Producer / Winery ▸ (text input, partial match) │ Maximum Wines ▸ 10 000 (default: fetch all) │ ├──── ▾ Rating Range ────────────── filter wines by rating │ Minimum Rating ▸ 3.5 │ Maximum Rating ▸ 5.0 │ ├──── ▾ Price Range ─────────────── filter wines by price │ Minimum Price ▸ (empty = no minimum) │ Maximum Price ▸ (empty = no maximum) │ ├──── ▾ Regional Settings ───────── country & currency for prices │ Market Country ▸ France ▾ (15 markets) │ Currency ▸ EUR ▾ (8 currencies) │ ├──── ▾ Output Settings ─────────── sorting order │ Sort By ▸ Highest Rated ▾ │ Sort Order ▸ Descending ▾ │ ├──── ▾ Vintage Analysis ────────── year-by-year ratings (slower) │ Include All Vintages [ ] │ Vintage Start Year 2005 │ └──── ▾ Advanced ────────────────── developer options Debug Mode [ ] ```` → See [Input Parameters](#input-parameters) below for the full reference. ### Why use this scraper? Vivino lists 60M+ users and 12M+ wines. Use this scraper for: - **Market research**: analyze wine trends, pricing, and consumer preferences - **Inventory monitoring**: track ratings and popularity for your wine selection - **Investment analysis**: monitor vintage ratings for fine wine investments - **Producer comparison**: compare producers and regions side by side - **Cellar tracking**: build a database of highly-rated wines to taste *** ### Key features #### Pick filters in the UI No coding required. Pick filters from dropdown menus and click Start. #### Filters available | Filter | Description | |--------|-------------| | **Region** | 299 wine regions across 32 countries: France, Italy, Spain, Portugal, Germany, USA, Argentina, Australia... | | **Sub-regions** | Drill down to specific appellations: Meursault, Pauillac, Barolo, Napa Valley, Rioja Alta, and more | | **Wine Type** | Red, White, Sparkling, Rosé, Dessert, Fortified | | **Grape Variety** | 21 varietals: Pinot Noir, Chardonnay, Cabernet Sauvignon, Syrah, Nebbiolo, Tempranillo... | | **Producer** | Search by winery name (partial match supported) | | **Rating** | Filter by minimum/maximum Vivino rating (1-5 stars) | | **Price** | Set price range in your preferred currency | #### Vintage analysis Enable **"Include All Vintages"** to get ratings for every vintage year of each wine. Useful for: - Tracking vintage quality variations - Finding the best years for a specific wine - Investment-grade wine analysis #### Includes wines without prices Unlike other scrapers that only return wines with marketplace listings, this scraper uses Vivino's winery API to include **all wines**, even those not currently for sale. *** ### Input parameters The input form mirrors the Apify console UI: five primary filters at the top, followed by six grouped option sections. #### Primary Filters | Parameter | Type | Default | Description | |-----------|------|---------|-------------| | `region` | Select | All Regions | Wine region or appellation; 299 regions across 32 countries with sub-regions for France, Italy, and Spain | | `wineType` | Select | All Types | Red, White, Sparkling, Rose, Dessert, or Fortified | | `grape` | Select | All Grapes | Grape variety; 21 options: Pinot Noir, Chardonnay, Cabernet Sauvignon, Syrah, Nebbiolo, Tempranillo, and more | | `wineryName` | Text | - | Producer/winery name. Examples: `Coche-Dury`, `Romanee-Conti`, `Rayas`. Partial match supported. | | `maxWines` | Number | 10,000 | Maximum wines to scrape (1–10,000). Default fetches all matching wines. Lower for quick tests. | #### Rating Range *Filter wines by rating (optional)* | Parameter | Type | Default | Description | |-----------|------|---------|-------------| | `minRating` | Number | 3.5 | Minimum Vivino rating (1–5 stars) | | `maxRating` | Number | 5 | Maximum Vivino rating (1–5 stars) | #### Price Range *Filter wines by price (optional)* | Parameter | Type | Default | Description | |-----------|------|---------|-------------| | `priceRangeMin` | Number | - | Minimum price in selected currency | | `priceRangeMax` | Number | - | Maximum price in selected currency | #### Regional Settings *Configure country and currency for prices* | Parameter | Type | Default | Description | |-----------|------|---------|-------------| | `countryCode` | Select | France | Country for price availability and currency conversion | | `currencyCode` | Select | EUR | Currency for displaying prices | #### Output Settings *Configure sorting order* | Parameter | Type | Default | Description | |-----------|------|---------|-------------| | `orderBy` | Select | Highest Rated | Sort by rating, popularity, price, or discount | | `order` | Select | Descending | Descending (highest first) or ascending (lowest first) | #### Vintage Analysis *Enable to get year-by-year ratings for each wine* | Parameter | Type | Default | Description | |-----------|------|---------|-------------| | `includeAllVintages` | Checkbox | No | Fetch ratings for all vintage years per wine. Creates one row per vintage. Significantly slower, but useful for investment analysis. | | `vintageStartYear` | Number | 2005 | Start year for vintage scanning (min: 1970) | #### Advanced *Developer options* | Parameter | Type | Default | Description | |-----------|------|---------|-------------| | `debug` | Checkbox | No | Enable verbose logging for troubleshooting | *** ### Output data Each wine record includes: ```json { "wineName": "Meursault Blanc", "wineryName": "Domaine Coche-Dury", "vintageYear": 2019, "fullName": "Domaine Coche-Dury Meursault Blanc 2019", "rating": 4.6, "ratingsCount": 245, "price": 450, "regionName": "Meursault", "wineType": "White", "isNatural": false, "sweetness": 1.8, "tannin": null, "imageUrl": "https://images.vivino.com/thumbs/..._375x500.jpg", "wineUrl": "https://www.vivino.com/meursault-blanc/w/85904", "vintageUrl": "https://www.vivino.com/domaine-coche-dury-meursault-blanc/v/2019", "wineId": 85904, "vintageId": 12345678, "wineryId": 11620, "regionId": 2246, "countryName": "France", "currency": "EUR", "alcohol": null, "acidity": 3.2, "intensity": 3.7, "fizziness": null, "tasteProfile": [ { "group": "earth", "count": 35, "primaryKeywords": [ { "name": "minéraux", "count": 18 }, { "name": "cuir", "count": 8 } ], "secondaryKeywords": [ { "name": "vanille", "count": 3 } ] }, { "group": "citrus_fruit", "count": 34, "primaryKeywords": [ { "name": "citron", "count": 18 }, { "name": "agrume", "count": 10 } ], "secondaryKeywords": [] } ], "scrapedAt": "2026-04-06T12:00:00.000Z" } ``` **27 fields per wine**, grouped into: - **Identity**: `wineName`, `wineryName`, `fullName`, `vintageYear`, `wineUrl`, `vintageUrl`, `imageUrl`, `wineId`, `vintageId`, `wineryId`, `regionId` - **Region**: `regionName`, `countryName`, `wineType`, `isNatural` - **Market**: `price`, `currency` - **Ratings**: `rating`, `ratingsCount` - **Taste structure**: `sweetness`, `tannin`, `acidity`, `intensity`, `fizziness`, `alcohol` - **Taste profile**: `tasteProfile` (flavor groups with primary/secondary keywords and mention counts) - **Metadata**: `scrapedAt` **Vintage mode** (`includeAllVintages: true`) produces one row per vintage with a `year` field instead of `vintageYear`, plus per-vintage `rating` and `ratingsCount`. *** ### Usage examples #### Example 1: top Burgundy white wines Find the best-rated white Burgundy wines: ```json { "region": "bourgogne", "wineType": "white", "minRating": 4.2, "maxWines": 200 } ``` #### Example 2: specific producer with all vintages Get all wines and vintages from Domaine de la Romanée-Conti: ```json { "wineryName": "Romanee-Conti", "includeAllVintages": true, "maxWines": 50 } ``` #### Example 3: affordable Châteauneuf-du-Pape Find value wines under €50: ```json { "region": "chateauneuf-du-pape", "minRating": 4.0, "priceRangeMax": 50, "orderBy": "ratings_average", "maxWines": 100 } ``` #### Example 4: Pinot Noir comparison Compare Pinot Noir across regions: ```json { "grape": "pinot-noir", "minRating": 4.0, "maxWines": 500, "orderBy": "ratings_count" } ``` *** ### Supported regions (299 regions, 32 countries) The full list is available in the **Wine Region** dropdown in the Apify console. Coverage by country: | Country | Regions | Examples | |---------|--------:|---------| | **France** | 101 | Bourgogne (Meursault, Puligny-Montrachet, Vosne-Romanée…), Bordeaux (Margaux, Pauillac, Saint-Émilion, Pomerol…), Rhône (Châteauneuf-du-Pape, Côte-Rôtie, Hermitage…), Loire, Champagne, Beaujolais, Alsace, Provence, Languedoc, Jura, Corse | | **Italy** | 64 | Piemonte (Barolo, Barbaresco…), Toscana (Brunello di Montalcino, Chianti Classico, Bolgheri…), Veneto (Amarone, Prosecco, Soave), Sicilia (Etna), Lombardia (Franciacorta), Campania, Puglia, Umbria, Friuli | | **Spain** | 35 | Rioja, Ribera del Duero, Priorat, Cava, Navarra, Rías Baixas, Jerez | | **Portugal** | 9 | Douro, Porto, Alentejo, Dão, Vinho Verde, Madeira | | **Germany** | 9 | Mosel, Rheingau, Pfalz, Rheinhessen, Nahe | | **Austria** | 7 | Wachau, Kamptal, Burgenland | | **USA** | 11 | Napa Valley, Sonoma County, Willamette Valley, Paso Robles, Russian River Valley | | **Argentina** | 6 | Mendoza, Uco Valley, Salta, Patagonia | | **Chile** | 8 | Maipo Valley, Colchagua Valley, Casablanca Valley | | **Australia** | 10 | Barossa Valley, McLaren Vale, Margaret River, Yarra Valley, Hunter Valley | | **New Zealand** | 5 | Marlborough, Central Otago, Hawke's Bay | | **South Africa** | 8 | Stellenbosch, Swartland, Franschhoek, Hemel-en-Aarde | | **Greece** | 5 | Santorini, Naoussa, Nemea | | **+ 19 more countries** | 21 | Hungary, Georgia, Lebanon, Croatia, Israel, Slovenia, Canada, Brazil, Uruguay, Mexico, UK, Romania, Bulgaria, Moldova, Turkey, Japan, Morocco, India | France, Italy and Spain include sub-region drill-down (Bourgogne → Meursault, Piemonte → Barolo, Rioja → Rioja Alta…). Selecting a parent region automatically includes its sub-regions. *** ### Pricing This scraper uses Apify's **pay-per-event** pricing at **$0.003 per wine row extracted** (the `apify-default-dataset-item` event). You pay only for data delivered to the dataset, not for compute time or failed requests. #### Cost examples | Mode | Wines requested | Rows extracted | Cost | |------|-----------------|----------------|------| | Standard | 100 | 100 | $0.30 | | Standard | 1,000 | 1,000 | $3.00 | | Standard | 10,000 | 10,000 | $30.00 | | Vintage mode | 100 | ~1,000 to 2,000 (one row per vintage year, typically 10-20 per wine) | $3 to $6 | **Free tier**: the Apify Free plan includes $5 of credits per month, enough for ~1,600 wines in standard mode or ~150 to 300 wines in vintage mode. See the [pricing tab](https://apify.com/mrbridge/vivino-powerful-scraper/pricing?fpr=mrbridge) for the live billing config. #### Speed - **Standard mode**: ~2-3 wines/second - **Vintage mode**: ~1 wine/minute (checks years from 2005 onward, with early stop on missing data) *** ### Export formats Download your data in multiple formats: - **JSON**: for developers and APIs - **CSV**: for Excel and spreadsheets - **Excel**: direct .xlsx export - **XML**: for legacy systems *** ### Integrate into your workflow This actor runs on Apify and integrates natively with popular automation platforms and programming languages. #### API integration Call this actor programmatically using the [Apify API](https://docs.apify.com/api/v2?fpr=mrbridge). Get your API token from [Settings → Integrations](https://console.apify.com/settings/integrations?fpr=mrbridge). **cURL:** ```bash curl "https://api.apify.com/v2/acts/mrbridge~vivino-powerful-scraper/run-sync-get-dataset-items" \ -X POST \ -H "Content-Type: application/json" \ -H "Authorization: Bearer YOUR_APIFY_TOKEN" \ -d '{ "region": "bourgogne", "wineType": "white", "minRating": 4.0, "maxWines": 100 }' ``` **Node.js:** ```javascript import { ApifyClient } from 'apify-client'; const client = new ApifyClient({ token: 'YOUR_APIFY_TOKEN' }); const run = await client.actor('mrbridge/vivino-powerful-scraper').call({ region: 'bourgogne', wineType: 'white', minRating: 4.0, maxWines: 100, }); const { items } = await client.dataset(run.defaultDatasetId).listItems(); console.log(`Found ${items.length} wines`); ``` **Python:** ```python from apify_client import ApifyClient client = ApifyClient("YOUR_APIFY_TOKEN") run = client.actor("mrbridge/vivino-powerful-scraper").call(run_input={ "region": "bourgogne", "wineType": "white", "minRating": 4.0, "maxWines": 100, }) for wine in client.dataset(run["defaultDatasetId"]).iterate_items(): print(f"{wine['fullName']} - {wine['rating']}★ - {wine.get('price', 'N/A')} {wine.get('currency', '')}") ``` #### Scheduled runs: automated market monitoring Set up a schedule in the Apify Console to track regional wine data over time: 1. Create a **Task** with your saved input (region, filters, settings) 2. Go to the **Schedules** tab → Create schedule 3. Set a cron expression, e.g. `0 2 * * 1` for every Monday at 2 AM UTC | Schedule | Cron expression | Use case | |----------|----------------|----------| | Every Monday | `0 2 * * 1` | Weekly regional price report | | 1st of month | `0 0 1 * *` | Monthly market snapshot | | Daily at 6 AM | `0 6 * * *` | Active trading desk | #### Webhooks: push results to your system Get notified when a run completes. No polling needed: 1. Go to the actor's **Integrations** tab in the Apify Console 2. Select event: **Run succeeded** 3. Enter your endpoint URL 4. Apify sends a POST request with the `datasetId` and run metadata #### No-code integrations Connect this actor to your tools without writing code: | Platform | What it does | Setup | |----------|-------------|-------| | **[Google Sheets](https://docs.apify.com/platform/integrations?fpr=mrbridge)** | Export wine data to a Google Sheet automatically | Integrations tab → Google Drive | | **[Airtable](https://docs.apify.com/platform/integrations/airtable?fpr=mrbridge)** | Sync wines to an Airtable base with field mapping | Integrations tab → Airtable | | **[Zapier](https://docs.apify.com/platform/integrations/zapier?fpr=mrbridge)** | Trigger Zaps on run completion → push to 5,000+ apps | Apify Zapier connector | | **[Make](https://docs.apify.com/platform/integrations/make?fpr=mrbridge)** | Visual workflows: scrape → transform → insert into DB | Apify Make module | | **[n8n](https://docs.apify.com/platform/integrations/n8n?fpr=mrbridge)** | Self-hosted workflow automation with Apify trigger node | Apify n8n community node | For Zapier, Make and n8n setup, see the [Apify Integrations docs](https://docs.apify.com/platform/integrations?fpr=mrbridge). Actor ID for run-actor steps: `onpKx0FzTy6OfOjXg`. *** ### Tips for best results 1. **Use region filters** when searching for specific producers; speeds up the search significantly. 2. **Start with smaller `maxWines`** to test filters before large scrapes. 3. **Enable `includeAllVintages`** only when you need year-by-year data. Slower, but unique signal. 4. **Combine filters** for precise results: region + grape + rating range. 5. **Use `debug` mode** to see detailed logs if results look unexpected. *** ### Limitations - Vivino's API may rate-limit requests during high-traffic periods - Some wines without user reviews may not have rating data - Vintage data is limited to years with actual user reviews on Vivino - Price data is only available for wines currently listed for sale *** ### FAQ #### How much does it cost per wine? This scraper uses Apify's pay-per-event pricing at **$0.003 per wine extracted** (the `apify-default-dataset-item` event). 100 wines cost $0.30, 1,000 wines cost $3, 10,000 wines cost $30. The free Apify plan includes $5 of monthly credits, enough to extract ~1,600 wines per month at no cost. #### Is it legal to scrape Vivino? Yes, scraping publicly available data is legal in most jurisdictions, as confirmed by the [2022 US Ninth Circuit ruling in hiQ Labs v. LinkedIn](https://en.wikipedia.org/wiki/HiQ_Labs_v._LinkedIn). This scraper only reads pages any visitor can see without logging in. No private user data is collected. Review [Apify's web scraping legality guide](https://blog.apify.com/is-web-scraping-legal/) and ensure your specific use case complies with Vivino's Terms of Service and applicable laws (GDPR if you store review text from EU users). #### Can I use this scraper via MCP? The Actor exposes only a trivial Standby status endpoint, not a full MCP server. To use Vivino data inside an MCP workflow, run this scraper through the standard [Apify MCP integration](https://docs.apify.com/platform/integrations/mcp?fpr=mrbridge) by adding `mrbridge/vivino-powerful-scraper` to your client config. #### Why does the default `maxWines: 5` give such a small test run? The prefill is intentionally conservative so the first click on Start costs less than $0.02 and finishes in under a minute. Once you've verified the output shape, bump `maxWines` to 100, 1,000, or remove the cap entirely. #### Can I scrape wines that aren't currently for sale? Yes. The scraper falls back to the winery API for wines without active price listings, so you still get ratings, taste profile and vintage data. The `price` field will be `null` for those entries. #### What happens if Vivino rate-limits me? The scraper handles rate limits with exponential backoff and retries. Sustained 429 errors cause the run to exit gracefully (always SUCCEEDED) with whatever data was already collected. Lower the concurrency or run during off-peak hours if you hit limits repeatedly. *** ### Legal disclaimer This scraper is intended for personal use, research, and legitimate business purposes. Please respect Vivino's terms of service and rate limits. The data scraped belongs to Vivino and its users. *** ### Support & feedback - **Issues**: report bugs or request features on the Actor's **Issues** tab in Apify Console - **Questions**: contact us through Apify support *** # Actor input Schema ## `region` (type: `string`): Select a wine region or appellation. 299 regions across 32 countries with detailed sub-regions for France, Italy, and Spain. ## `wineType` (type: `string`): Filter by wine style: Red, White, Sparkling, Rose, Dessert, or Fortified wines. ## `grape` (type: `string`): Filter by grape variety (cepage). Popular options: Pinot Noir, Chardonnay, Cabernet Sauvignon, Merlot, Syrah, and more. ## `wineryName` (type: `string`): Search by producer name. Examples: 'Coche-Dury', 'Romanee-Conti', 'Rayas'. Partial match supported. ## `maxWines` (type: `integer`): Maximum number of wines to scrape. Default 10,000 (fetches all matching wines). Lower for quick tests. ## `minRating` (type: `number`): Filter wines by minimum Vivino rating (1-5 stars). Example: 4.0 for highly-rated wines, 4.5 for exceptional wines. ## `maxRating` (type: `number`): Filter wines by maximum rating. Leave empty for no upper limit. ## `priceRangeMin` (type: `integer`): Minimum price filter in selected currency. Leave empty for no minimum. ## `priceRangeMax` (type: `integer`): Maximum price filter. Example: 50 for wines under 50 EUR/USD. Leave empty for no maximum. ## `countryCode` (type: `string`): Country for price availability and currency conversion ## `currencyCode` (type: `string`): Currency for displaying prices ## `orderBy` (type: `string`): Sort results by rating, popularity, price, or discount ## `order` (type: `string`): Ascending or descending order ## `includeAllVintages` (type: `boolean`): Get ratings for vintage years of each wine (default: 2005 to today, configurable via Vintage Start Year). Creates one row per vintage. Useful for investment analysis and vintage-quality tracking. Significantly slower. ## `vintageStartYear` (type: `integer`): Start year for vintage scanning. Default: 2005. Set lower (e.g., 1970) for older vintages. ## `debug` (type: `boolean`): Enable verbose logging for troubleshooting ## Actor input object example ```json { "region": "bourgogne", "wineType": "white", "grape": "", "wineryName": "", "maxWines": 5, "minRating": 3.5, "maxRating": 5, "countryCode": "fr", "currencyCode": "EUR", "orderBy": "ratings_average", "order": "desc", "includeAllVintages": false, "vintageStartYear": 2005, "debug": false } ``` # Actor output Schema ## `wines` (type: `string`): No description # API You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup. ## JavaScript example ```javascript import { ApifyClient } from 'apify-client'; // Initialize the ApifyClient with your Apify API token // Replace the '' with your token const client = new ApifyClient({ token: '', }); // Prepare Actor input const input = { "region": "bourgogne", "wineType": "white", "maxWines": 5, "minRating": 3.5, "vintageStartYear": 2005 }; // Run the Actor and wait for it to finish const run = await client.actor("mrbridge/vivino-powerful-scraper").call(input); // Fetch and print Actor results from the run's dataset (if any) console.log('Results from dataset'); console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`); const { items } = await client.dataset(run.defaultDatasetId).listItems(); items.forEach((item) => { console.dir(item); }); // 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs ``` ## Python example ```python from apify_client import ApifyClient # Initialize the ApifyClient with your Apify API token # Replace '' with your token. client = ApifyClient("") # Prepare the Actor input run_input = { "region": "bourgogne", "wineType": "white", "maxWines": 5, "minRating": 3.5, "vintageStartYear": 2005, } # Run the Actor and wait for it to finish run = client.actor("mrbridge/vivino-powerful-scraper").call(run_input=run_input) # Fetch and print Actor results from the run's dataset (if there are any) print("💾 Check your data here: https://console.apify.com/storage/datasets/" + run["defaultDatasetId"]) for item in client.dataset(run["defaultDatasetId"]).iterate_items(): print(item) # 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start ``` ## CLI example ```bash echo '{ "region": "bourgogne", "wineType": "white", "maxWines": 5, "minRating": 3.5, "vintageStartYear": 2005 }' | apify call mrbridge/vivino-powerful-scraper --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "command": "npx", "args": [ "mcp-remote", "https://mcp.apify.com/?tools=mrbridge/vivino-powerful-scraper", "--header", "Authorization: Bearer " ] } } } ``` ## OpenAPI specification ```json { "openapi": "3.0.1", "info": { "title": "Vivino Wine Scraper - Ratings, Prices & Vintages", "description": "Extract wine data from Vivino: ratings, reviews, prices, vintages, taste profiles. Filter by region (Burgundy, Bordeaux, Champagne...), grape variety, producer. Use it for wine list building, market research, cellar tracking, or producer comparison.", "version": "2.1", "x-build-id": "lvprfvcrouiiHReWQ" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/mrbridge~vivino-powerful-scraper/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-mrbridge-vivino-powerful-scraper", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for its completion, and returns Actor's dataset items in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } }, "/acts/mrbridge~vivino-powerful-scraper/runs": { "post": { "operationId": "runs-sync-mrbridge-vivino-powerful-scraper", "x-openai-isConsequential": false, "summary": "Executes an Actor and returns information about the initiated run in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/runsResponseSchema" } } } } } } }, "/acts/mrbridge~vivino-powerful-scraper/run-sync": { "post": { "operationId": "run-sync-mrbridge-vivino-powerful-scraper", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for completion, and returns the OUTPUT from Key-value store in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } } }, "components": { "schemas": { "inputSchema": { "type": "object", "properties": { "region": { "title": "Wine Region", "enum": [ "", "sep-france", "alsace", "cremant-dalsace", "alsace-grand-cru", "beaujolais", "brouilly", "cote-de-brouilly", "fleurie", "morgon", "moulin-a-vent", "saint-amour", "bordeaux", "castillon-cotes-de-bordeaux", "fronsac", "graves", "haut-medoc", "lalande-de-pomerol", "margaux", "medoc", "moulis-en-medoc", "pauillac", "pessac-leognan", "pomerol", "saint-emilion", "saint-estephe", "saint-julien", "sauternes", "bourgogne", "chablis", "chambolle-musigny", "chassagne-montrachet", "cote-de-beaune", "cote-de-nuits", "gevrey-chambertin", "maconnais", "marsannay", "meursault", "nuits-saint-georges", "pommard", "pouilly-fuisse", "puligny-montrachet", "saint-veran", "volnay", "vosne-romanee", "champagne", "cote-des-blancs", "champagne-grand-cru", "champagne-premier-cru", "corse", "patrimonio", "jura", "arbois", "banyuls", "corbieres", "faugeres", "fitou", "minervois", "picpoul-de-pinet", "saint-chinian", "languedoc-roussillon", "loire", "anjou", "bourgueil", "chinon", "coteaux-du-layon", "menetou-salon", "muscadet", "pouilly-fume", "sancerre", "saumur", "saumur-champigny", "savennieres", "touraine", "vouvray", "provence", "bandol", "cotes-de-provence", "les-baux-de-provence", "cairanne", "chateauneuf-du-pape", "condrieu", "cornas", "cote-rotie", "cotes-du-rhone", "crozes-hermitage", "gigondas", "hermitage", "lirac", "rasteau", "saint-joseph", "tavel", "vacqueyras", "ventoux", "savoie", "sud-ouest", "bergerac", "cahors", "gascogne", "jurancon", "madiran", "rhone", "sep-italy", "abruzzo", "montepulciano-dabruzzo", "basilicata", "calabria", "campania", "fiano-di-avellino", "greco-di-tufo", "taurasi", "emilia-romagna", "friuli-venezia-giulia", "colli-orientali-del-friuli", "collio", "friuli-grave", "lazio", "lombardia", "franciacorta", "lugana", "oltrepo-pavese", "valtellina", "marche", "piemonte", "barbaresco", "barbera-dalba", "barbera-dasti", "barolo", "gattinara", "gavi", "langhe", "moscato-dasti", "roero", "puglia", "primitivo-di-manduria", "salento", "salice-salentino", "sardegna", "sicilia", "cerasuolo-di-vittoria", "etna", "marsala", "toscana", "bolgheri", "brunello-di-montalcino", "carmignano", "chianti", "chianti-classico", "maremma-toscana", "morellino-di-scansano", "vernaccia-di-san-gimignano", "vino-nobile-di-montepulciano", "alto-adige", "trentino-alto-adige", "umbria", "montefalco-sagrantino", "orvieto", "valle-daosta", "veneto", "amarone", "bardolino", "conegliano-valdobbiadene", "prosecco", "soave", "valpolicella", "valpolicella-ripasso", "sep-spain", "jerez", "montilla-moriles", "calatayud", "campo-de-borja", "carinena", "somontano", "canaries", "castilla-y-leon", "bierzo", "rueda", "toro", "la-mancha", "manchuela", "valdepenas", "emporda", "montsant", "penedes", "terra-alta", "cava", "rias-baixas", "ribeira-sacra", "majorque", "jumilla", "yecla", "navarra", "priorat", "ribera-del-duero", "rioja", "rioja-alavesa", "rioja-alta", "txakoli", "alicante", "utiel-requena", "madrid", "sep-portugal", "alentejo", "bairrada", "dao", "douro", "lisboa", "madeira", "porto", "setubal", "vinho-verde", "sep-germany", "ahr", "baden", "franken", "mosel", "nahe", "pfalz", "rheingau", "rheinhessen", "wurttemberg", "sep-austria", "burgenland", "kamptal", "kremstal", "sudsteiermark", "wachau", "wagram", "weinviertel", "sep-usa", "alexander-valley", "central-coast", "columbia-valley", "lodi", "napa-valley", "paso-robles", "russian-river-valley", "santa-barbara-county", "sonoma-county", "stags-leap-district", "willamette-valley", "sep-argentina", "cafayate-valley", "lujan-de-cuyo", "mendoza", "patagonia", "salta", "uco-valley", "sep-chile", "aconcagua-valley", "casablanca-valley", "colchagua-valley", "leyda-valley", "limari-valley", "maipo-valley", "maule-valley", "rapel-valley", "sep-australia", "adelaide-hills", "barossa-valley", "clare-valley", "coonawarra", "eden-valley", "hunter-valley", "margaret-river", "mclaren-vale", "tasmania", "yarra-valley", "sep-new-zealand", "central-otago", "hawkes-bay", "marlborough", "martinborough", "waipara", "sep-south-africa", "constantia", "elgin", "franschhoek", "hemel-en-aarde-valley", "paarl", "stellenbosch", "swartland", "walker-bay", "sep-greece", "crete", "naoussa", "nemea", "peloponnesos", "santorini", "sep-hungary", "eger", "szekszard", "tokaj", "villany", "sep-georgia", "kakheti", "sep-lebanon", "bekaa-valley", "sep-croatia", "dalmatian-coast", "istria-croatia", "sep-israel", "galilee", "judean-hills", "sep-slovenia", "goriska-brda", "sep-canada", "niagara-peninsula", "okanagan-valley", "sep-brazil", "serra-gaucha", "sep-uruguay", "maldonado", "sep-mexico", "valle-de-guadalupe", "sep-united-kingdom", "england", "sep-romania", "transylvania", "sep-bulgaria", "thracian-valley", "sep-moldova", "moldova", "sep-turkey", "thrace-turkey", "sep-japan", "yamanashi", "sep-morocco", "meknes", "sep-india", "nashik" ], "type": "string", "description": "Select a wine region or appellation. 299 regions across 32 countries with detailed sub-regions for France, Italy, and Spain.", "default": "" }, "wineType": { "title": "Wine Type", "enum": [ "", "red", "white", "sparkling", "rose", "dessert", "fortified" ], "type": "string", "description": "Filter by wine style: Red, White, Sparkling, Rose, Dessert, or Fortified wines.", "default": "" }, "grape": { "title": "Grape Variety", "enum": [ "", "pinot-noir", "chardonnay", "cabernet-sauvignon", "merlot", "syrah", "grenache", "gamay", "cabernet-franc", "sauvignon-blanc", "riesling", "pinot-gris", "gewurztraminer", "viognier", "chenin-blanc", "muscadet", "semillon", "sangiovese", "nebbiolo", "tempranillo", "malbec", "mourvedre" ], "type": "string", "description": "Filter by grape variety (cepage). Popular options: Pinot Noir, Chardonnay, Cabernet Sauvignon, Merlot, Syrah, and more.", "default": "" }, "wineryName": { "title": "Producer / Winery", "type": "string", "description": "Search by producer name. Examples: 'Coche-Dury', 'Romanee-Conti', 'Rayas'. Partial match supported.", "default": "" }, "maxWines": { "title": "Maximum Wines", "minimum": 1, "maximum": 10000, "type": "integer", "description": "Maximum number of wines to scrape. Default 10,000 (fetches all matching wines). Lower for quick tests.", "default": 10000 }, "minRating": { "title": "Minimum Rating", "minimum": 1, "maximum": 5, "type": "number", "description": "Filter wines by minimum Vivino rating (1-5 stars). Example: 4.0 for highly-rated wines, 4.5 for exceptional wines.", "default": 3.5 }, "maxRating": { "title": "Maximum Rating", "minimum": 1, "maximum": 5, "type": "number", "description": "Filter wines by maximum rating. Leave empty for no upper limit.", "default": 5 }, "priceRangeMin": { "title": "Minimum Price", "minimum": 0, "type": "integer", "description": "Minimum price filter in selected currency. Leave empty for no minimum." }, "priceRangeMax": { "title": "Maximum Price", "minimum": 0, "type": "integer", "description": "Maximum price filter. Example: 50 for wines under 50 EUR/USD. Leave empty for no maximum." }, "countryCode": { "title": "Market Country", "enum": [ "fr", "us", "gb", "de", "it", "es", "pt", "be", "nl", "ch", "at", "au", "ca", "br", "jp" ], "type": "string", "description": "Country for price availability and currency conversion", "default": "fr" }, "currencyCode": { "title": "Currency", "enum": [ "EUR", "USD", "GBP", "CHF", "AUD", "CAD", "JPY", "BRL" ], "type": "string", "description": "Currency for displaying prices", "default": "EUR" }, "orderBy": { "title": "Sort By", "enum": [ "ratings_average", "ratings_count", "price", "discount" ], "type": "string", "description": "Sort results by rating, popularity, price, or discount", "default": "ratings_average" }, "order": { "title": "Sort Order", "enum": [ "desc", "asc" ], "type": "string", "description": "Ascending or descending order", "default": "desc" }, "includeAllVintages": { "title": "Include All Vintages", "type": "boolean", "description": "Get ratings for vintage years of each wine (default: 2005 to today, configurable via Vintage Start Year). Creates one row per vintage. Useful for investment analysis and vintage-quality tracking. Significantly slower.", "default": false }, "vintageStartYear": { "title": "Vintage Start Year", "minimum": 1970, "maximum": 2026, "type": "integer", "description": "Start year for vintage scanning. Default: 2005. Set lower (e.g., 1970) for older vintages.", "default": 2005 }, "debug": { "title": "Debug Mode", "type": "boolean", "description": "Enable verbose logging for troubleshooting", "default": false } } }, "runsResponseSchema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "actId": { "type": "string" }, "userId": { "type": "string" }, "startedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "finishedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "status": { "type": "string", "example": "READY" }, "meta": { "type": "object", "properties": { "origin": { "type": "string", "example": "API" }, "userAgent": { "type": "string" } } }, "stats": { "type": "object", "properties": { "inputBodyLen": { "type": "integer", "example": 2000 }, "rebootCount": { "type": "integer", "example": 0 }, "restartCount": { "type": "integer", "example": 0 }, "resurrectCount": { "type": "integer", "example": 0 }, "computeUnits": { "type": "integer", "example": 0 } } }, "options": { "type": "object", "properties": { "build": { "type": "string", "example": "latest" }, "timeoutSecs": { "type": "integer", "example": 300 }, "memoryMbytes": { "type": "integer", "example": 1024 }, "diskMbytes": { "type": "integer", "example": 2048 } } }, "buildId": { "type": "string" }, "defaultKeyValueStoreId": { "type": "string" }, "defaultDatasetId": { "type": "string" }, "defaultRequestQueueId": { "type": "string" }, "buildNumber": { "type": "string", "example": "1.0.0" }, "containerUrl": { "type": "string" }, "usage": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "integer", "example": 1 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 } } }, "usageTotalUsd": { "type": "number", "example": 0.00005 }, "usageUsd": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "number", "example": 0.00005 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 } } } } } } } } } } ```