# Vivino Scraper - Wines, Ratings, Reviews & Prices (`scrapesage/vivino-scraper`) Actor Discover wines on Vivino by type, country, region, grape, price & rating: ratings, taste profile, flavor notes, food pairings, awards, critic & user reviews, live + median prices, and price/rating monitoring. - **URL**: https://apify.com/scrapesage/vivino-scraper.md - **Developed by:** [Scrape Sage](https://apify.com/scrapesage) (community) - **Categories:** E-commerce, Automation, Other - **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks - **User rating**: No ratings yet ## Pricing from $5.00 / 1,000 wine scrapeds This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events. 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/docs.md): ```bash npm install apify-client ``` In Python projects, use official [Python client library](https://docs.apify.com/api/client/python/docs.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/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 Scraper — Wines, Ratings, Reviews & Prices (Taste Profiles, Rankings & Price Tracking) Extract **complete wine data from [Vivino](https://www.vivino.com)** — the world's largest wine marketplace and community. Discover wines exactly like Vivino's own **Explore** page (by type, country, region, grape, price and rating) and get the fields other scrapers leave empty: **average rating and ratings count, full taste structure, flavor notes, food pairings, grape composition, alcohol, awards, professional critic reviews, recommended drinking window, global/country/region/winery rankings, the live lowest price, the median market price, every merchant offer, and the community reviews**. No login, no cookies, no browser — fast JSON extraction straight from Vivino's own back end. ### Why this Vivino scraper? Most Vivino scrapers return a name, a rating and a price. This actor reads Vivino's explore, vintage-detail, price and review endpoints and ships the **richest dataset in the category** — the same data a wine buyer, sommelier, retailer or collector actually needs to make a decision. | Data | Typical scrapers | This actor | |---|---|---| | Wine name, year, type, rating | ✅ | ✅ | | Ratings **count** + reviews count + ratings distribution | partial | ✅ | | **Taste structure** (acidity, intensity, sweetness, tannin, fizziness) | ❌ | ✅ | | **Flavor notes** (oak, black fruit, earth… with keywords) | ❌ | ✅ | | **Food pairings** | ❌ | ✅ | | Region, country, winery + **grape composition** | partial | ✅ | | Alcohol %, wine style, closure | ❌ | ✅ | | **Awards** + **professional critic reviews** | ❌ | ✅ opt-in | | Recommended **drinking window** | ❌ | ✅ | | Global / country / region / **winery ranking** | ❌ | ✅ | | Live **lowest price** + **median market price** + every merchant offer | partial | ✅ | | Community **reviews** (rating, text, taster, flavor words) | ❌ | ✅ opt-in | | **All vintages** of a wine (price/rating by year) | ❌ | ✅ opt-in | | Price / rating **monitoring** (only new or changed) | ❌ | ✅ | ### Use cases - **Wine retail & e-commerce** — enrich product catalogs with ratings, taste, region, grapes and food pairings; benchmark competitive pricing against the live lowest and median market price; reprice on a schedule. - **Price tracking & investing** — watch fine-wine prices and ratings over time, with drinking windows and global rankings for cellar and investment decisions. - **Wine apps, marketplaces & content sites** — power discovery, recommendations and affiliate pages with clean, LLM-ready wine data and real community reviews. - **Restaurants & sommeliers** — build and curate wine lists by rating, region, grape, price band and food pairing. - **Market & trend research** — analyze ratings, pricing and popularity across countries, regions, grapes and price tiers. - **Catalog & monitoring** — schedule recurring runs to capture new vintages, price drops and rating changes automatically. ### How to use 1. [Sign up for Apify](https://console.apify.com/sign-up) — the free plan is enough to try this actor. 2. Open the **Vivino Scraper**, choose your Explore filters (wine type, country, price, rating…) or paste Vivino wine URLs, and click **Start**. 3. Watch results stream into the dataset table. 4. **Export** as JSON, CSV, Excel, XML, or RSS — or pull results programmatically via the [Apify API](https://docs.apify.com/api/v2). ### Input ```json { "wineTypes": ["red"], "wineCountries": ["us"], "minRating": "4.0", "priceMin": 20, "priceMax": 80, "sortBy": "mostPopular", "marketCountry": "US", "currency": "USD", "includeWineDetails": true, "includeReviews": true, "maxReviewsPerWine": 10, "maxResults": 100 } ```` - **wineTypes** — `red`, `white`, `sparkling`, `rose`, `dessert`, `fortified` (empty = all). - **wineCountries** — origin countries (ISO codes): `us`, `fr`, `it`, `es`, `pt`, `ar`, `cl`, `au`, `de`… - **minRating / priceMin / priceMax** — narrow by Vivino average rating and price band. - **sortBy** — `mostPopular` (most rated), `topRated`, `priceAsc`, `priceDesc`. - **grapeIds / regionIds / foodIds / wineStyleIds** — advanced numeric facets (find them in any Vivino Explore URL); map 1:1 to Vivino's own filters. - **marketCountry / currency** — the pricing market and currency for live + median prices. - **startUrls** — Vivino wine page URLs (`/w/`); **wineIds** — wine IDs directly. - **includeWineDetails** *(default true)* — full detail: description, food pairings, grape composition, alcohol, awards, critic reviews, ratings distribution, drinking window, rankings. - **includeReviews** *(default false)* — community reviews per wine as separate records. - **includeAllVintages** *(default false)* — for direct wines, emit every vintage year (price/rating by year). - **includeMedianPrice** *(default true)* — add the median market price alongside the live lowest price. - **monitorMode / monitorKey** — emit only new or changed wines across runs (see below). ### Output One record per wine (`type: "wine"`), plus optional community review records (`type: "review"`): ```json { "type": "wine", "vintageId": 164821583, "wineId": 5978015, "name": "Hundred Acre Wraith Cabernet Sauvignon 2017", "wineName": "Wraith Cabernet Sauvignon", "year": 2017, "url": "https://www.vivino.com/w/5978015?year=2017", "wineType": "Red", "rating": 4.9, "ratingsCount": 77, "reviewsCount": 16, "wineRating": 4.8, "wineRatingsCount": 881, "ratingsDistribution": { "1": 0, "2": 0, "3": 0, "4": 34, "5": 43 }, "wineryName": "Hundred Acre", "regionName": "Napa Valley", "countryCode": "US", "countryName": "United States", "grapes": ["Cabernet Sauvignon"], "grapeComposition": { "Cabernet Sauvignon": 100 }, "alcohol": 15.5, "style": "Napa Valley Cabernet Sauvignon", "foodPairings": ["Beef", "Lamb", "Poultry", "Game (deer, venison)", "Mature and hard cheese"], "taste": { "acidity": 3.01, "intensity": 4.75, "sweetness": 2.04, "tannin": 3.1 }, "flavorGroups": [{ "group": "oak", "keywords": ["vanilla", "oak", "coffee"] }], "flavorKeywords": ["vanilla", "oak", "coffee", "black fruit", "dark chocolate"], "drinkingWindowFrom": 2022, "drinkingWindowTo": 2032, "ranking": { "global": { "rank": 292, "total": 12225908 }, "country": { "rank": 115, "total": 1323232 }, "winery": { "rank": 20, "total": 229 } }, "price": 695, "currency": "USD", "medianPrice": 1004, "merchant": "vinfolio.com", "merchantUrl": "https://vinfolio.com/product/…", "offers": [{ "amount": 695, "merchant": "vinfolio.com", "bottleType": "Bottle (0.75l)", "url": "https://vinfolio.com/product/…" }], "labelImage": "https://images.vivino.com/thumbs/…_pl_375x500.png", "image": "https://images.vivino.com/thumbs/…_pb_x960.png", "scrapedAt": "2026-06-19T12:00:00.000Z" } ``` A review record (`type: "review"`) carries `rating`, `note` (text), `language`, `createdAt`, `userAlias`, `flavorKeywords`, plus `wineId`/`vintageId`/`wineName`/`year` and the `wineUrl`. #### What to expect (field coverage) Vivino is community- and merchant-sourced, so a few fields are populated only when the data exists. Verified live, you can typically expect: | Field | Coverage | |---|---| | name, year, type, rating, ratingsCount, region, country, winery, taste, image | ~100% | | grapes, food pairings, alcohol, style, ratings distribution, drinking window, ranking | ~90% (with detail on) | | price / merchant offers | present when the wine is sold in the chosen market | | medianPrice | present when enough market prices exist | | awards, critic reviews | present for wines that have them (typically higher-end wines) | A blank field means Vivino doesn't publish that value — not that scraping failed. Nothing is dropped, so you always get the richest dataset available. ### Automate & schedule Run this actor on autopilot and pull results into your own stack: - **[Apify API](https://docs.apify.com/api/v2)** — start runs, fetch datasets, and manage schedules over REST. - **[apify-client for JavaScript](https://docs.apify.com/api/client/js/)** and **[apify-client for Python](https://docs.apify.com/api/client/python/)** — official SDKs. - **[Schedules](https://docs.apify.com/platform/schedules)** — run it daily/weekly to track prices, ratings and new vintages; perfect for repricing and price-drop alerts. - **[Webhooks](https://docs.apify.com/platform/integrations/webhooks)** — trigger downstream actions (catalog sync, Slack alert, price-drop email) the moment a run finishes. ```js import { ApifyClient } from 'apify-client'; const client = new ApifyClient({ token: 'MY_APIFY_TOKEN' }); const run = await client.actor('scrapesage/vivino-scraper').call({ wineTypes: ['red'], wineCountries: ['fr'], minRating: '4.2', priceMax: 60, includeReviews: true, maxResults: 100, }); const { items } = await client.dataset(run.defaultDatasetId).listItems(); console.log(`Got ${items.length} wines & reviews`); ``` ### Monitor mode (only new or changed wines) Turn on **monitorMode** to remember wines across runs in a named key-value store and emit **only** wines that are new or whose **price or rating changed** since the last run — each tagged with a `changeType` (`new`, `price_drop`, `price_rise`, `rating_up`, `rating_down`). It complements [Apify Schedules](https://docs.apify.com/platform/schedules): the schedule starts the run, and monitor mode dedupes against prior runs — so a daily schedule becomes a hands-off price-drop and rating-change feed. Use different `monitorKey` values to run several independent watches. ### Integrate with any app Connect the dataset to 5,000+ apps — no code required: - **[Make](https://docs.apify.com/platform/integrations/make)** — multi-step automation scenarios. - **[Zapier](https://docs.apify.com/platform/integrations/zapier)** — push new wines or price drops straight into your tools. - **[Slack](https://docs.apify.com/platform/integrations/slack)** — get notified when a monitored wine drops in price. - **[Google Drive / Sheets](https://docs.apify.com/platform/integrations/drive)** — auto-export every run to a spreadsheet. - **[Airbyte](https://docs.apify.com/platform/integrations/airbyte)** — pipe results into your data warehouse. - **[GitHub](https://docs.apify.com/platform/integrations/github)** — trigger runs from commits or releases. ### Use with AI assistants (MCP) The output is clean, LLM-ready JSON. Call this actor from Claude, ChatGPT, or any agent framework through the **[Apify MCP server](https://docs.apify.com/platform/integrations/mcp)** — ask your assistant to "find top-rated Napa Cabernets under $80 with their tasting notes and where to buy them" and let it run the scraper for you. ### Agent-ready: autonomous payments (x402 & Skyfire) This actor is **agent-ready** — AI agents can discover it, run it, and **pay for it autonomously**, with no Apify account and no human in the loop. It uses [pay-per-event](https://docs.apify.com/platform/actors/publishing/monetize/pay-per-event) pricing and [limited permissions](https://docs.apify.com/platform/actors/development/permissions), so it qualifies for Apify's agentic-payment standards: - **[x402](https://docs.apify.com/platform/integrations/x402)** — an open, HTTP-native payment protocol. Agents pay per run in USDC on the Base network directly through the [Apify MCP server](https://docs.apify.com/platform/integrations/mcp) — no account, no API key. - **[Skyfire](https://docs.apify.com/platform/integrations/skyfire)** — agent-to-service payments for fully autonomous AI-agent workflows. Building an AI agent, MCP tool, or autonomous data pipeline? This scraper is ready to plug in and pay as it goes. ### More scrapers from scrapesage Build a complete **product, price & marketplace intelligence stack**: - **[Amazon Scraper](https://apify.com/scrapesage/amazon-scraper)** — products, prices, reviews & sellers. - **[eBay Scraper](https://apify.com/scrapesage/ebay-scraper)** — listings, sold prices & seller leads. - **[Catawiki Scraper](https://apify.com/scrapesage/catawiki-scraper)** — collectibles auctions (incl. wine) with bids & estimates. - **[Discogs Scraper](https://apify.com/scrapesage/discogs-scraper)** — records, prices, artists & sellers. - **[Goodreads Scraper](https://apify.com/scrapesage/goodreads-scraper)** — books, authors, ratings & reviews. - **[Reverb Scraper](https://apify.com/scrapesage/reverb-scraper)** — music gear listings, price guide & sellers. - **[AliExpress Scraper](https://apify.com/scrapesage/aliexpress-scraper)** — products, prices, orders & suppliers. - **[Poshmark Scraper](https://apify.com/scrapesage/poshmark-scraper)** — listings, sold comps & seller leads. ### Tips - **Explore like Vivino does** — combine `wineTypes`, `wineCountries`, `minRating` and a price band, then sort by `mostPopular` or `topRated`. Vivino Explore returns 24 wines per page; raise `maxPagesPerSearch` to go deeper. - **Best value finds** — set `sortBy: "topRated"` with a tight `priceMax` to surface the highest-rated wines you can actually afford. - **All vintages** — paste a wine URL and turn on `includeAllVintages` to get every year of that wine with its own price and rating. - **Reviews** — enable `includeReviews` for community tasting notes and flavor words; add `reviewsLanguage` to keep one language. - **Proxies** — keep the default RESIDENTIAL proxy group; Vivino throttles datacenter IPs. ### FAQ **How do I find wines by region, grape or food pairing?** Use the Explore filters: `wineCountries` for origin, and the advanced `regionIds` / `grapeIds` / `foodIds` facets (the same numeric IDs Vivino uses in its own Explore URLs). **Can I search for a specific wine by name?** Vivino's keyword search isn't a public data endpoint, so for a specific bottle paste its Vivino page URL into `startUrls` (or its wine ID into `wineIds`). For discovery, the Explore filters are the powerful, reliable path — they're exactly how Vivino's own Explore page works. **Does it need the Vivino API or a key?** No. This actor reads the same public data Vivino's own website uses — no key, login or browser required. **Where do prices come from?** From Vivino's merchant listings for the market you choose (`marketCountry` / `currency`): the live lowest price, the median market price and the individual merchant offers. Prices appear only for wines actually sold in that market. **Can I export to Google Sheets, CSV, or Excel?** Yes — one click in the dataset view, or automatically on every run via the [Google Drive integration](https://docs.apify.com/platform/integrations/drive). **How do I track price drops automatically?** Turn on `monitorMode`, then create a [Schedule](https://docs.apify.com/platform/schedules) (e.g. daily). Each run emits only new or changed wines; add a [webhook](https://docs.apify.com/platform/integrations/webhooks) or [Zapier zap](https://docs.apify.com/platform/integrations/zapier) to alert you on `price_drop`. **A field is empty — why?** Some wines have no awards or critic reviews, some aren't sold in your chosen market (no price), and some new wines have few ratings. Fields are blank only when Vivino doesn't publish them — never because the scraper skipped them. **Is scraping Vivino legal?** This actor collects publicly available data only. You're responsible for using the data in compliance with applicable laws (e.g. GDPR/CCPA for personal data) and Vivino's terms. ### Need help? Open an issue on the actor's **Issues** tab, or visit the [Apify help center](https://help.apify.com/). Feature requests are welcome — this actor is actively maintained. # Actor input Schema ## `wineTypes` (type: `array`): Filter discovery by wine type. Leave empty for all types. Combine with the other filters below to explore Vivino exactly like its own 'Explore wines' page. ## `wineCountries` (type: `array`): Only keep wines made in these countries (ISO codes, lowercase): e.g. us, fr, it, es, pt, ar, cl, au, de. Leave empty for all origins. ## `minRating` (type: `string`): Only keep wines with at least this Vivino average rating (1.0–4.9), e.g. 4.0. ## `priceMin` (type: `integer`): Only keep wines priced at or above this amount in the market currency. ## `priceMax` (type: `integer`): Only keep wines priced at or below this amount in the market currency. ## `sortBy` (type: `string`): How to order discovered wines. ## `grapeIds` (type: `array`): Advanced: filter by Vivino grape IDs (numeric). Common: 1 Shiraz/Syrah, 2 Cabernet Sauvignon, 5 Chardonnay, 9 Merlot, 10 Sangiovese, 14 Pinot Noir, 18 Sauvignon Blanc, 22 Tempranillo, 43 Riesling, 64 Nebbiolo. ## `regionIds` (type: `array`): Advanced: filter by Vivino region IDs (numeric), e.g. 25 Napa Valley. ## `foodIds` (type: `array`): Advanced: filter by Vivino food-pairing IDs (numeric), e.g. 20 Beef, 8 Lamb, 4 Pork, 9 Poultry, 17 Mushrooms, 10 Spicy food, 14 Mature & hard cheese. ## `wineStyleIds` (type: `array`): Advanced: filter by Vivino wine-style IDs (numeric), e.g. a specific regional style like 'Napa Valley Cabernet Sauvignon'. ## `marketCountry` (type: `string`): Pricing & availability market (ISO country code). Prices and median prices are computed for this market. Default US. ## `currency` (type: `string`): Currency for all prices (ISO code), e.g. USD, EUR, GBP. ## `startUrls` (type: `array`): Vivino wine page URLs to scrape directly, e.g. https://www.vivino.com/\/w/1234567 or https://www.vivino.com/w/1234567?year=2019. Used in addition to the Explore filters. ## `wineIds` (type: `array`): Vivino wine IDs to scrape directly (the number in a /w/\ URL), e.g. 5978015. ## `includeWineDetails` (type: `boolean`): Enrich each wine with the full detail: description, food pairings, grape composition, alcohol, awards, critic reviews, ratings distribution, recommended drinking window and global/country/region/winery rankings. Turn OFF for a faster/cheaper discovery run (ratings, taste, region, winery, price & image only). Adds one request per wine. ## `includeReviews` (type: `boolean`): Pull Vivino community reviews for each wine (star rating, review text, language, date, taster alias, flavor keywords) as separate review records. Adds one request per wine. ## `maxReviewsPerWine` (type: `integer`): Maximum number of user reviews to pull per wine when reviews are enabled. ## `reviewsLanguage` (type: `string`): Only keep reviews in this language (ISO code, e.g. en), or any for all languages. ## `includeAllVintages` (type: `boolean`): For wines provided via URL or ID, emit every available vintage year (one record per year) instead of just the featured vintage — perfect for price/rating-by-year analysis. ## `includeMedianPrice` (type: `boolean`): Add the median market price alongside the live lowest price for each wine (one extra batched request per page). ## `maxResults` (type: `integer`): Maximum number of wine records to scrape across all filters and URLs. Vivino Explore returns 24 wines per page. ## `maxPagesPerSearch` (type: `integer`): How many Explore result pages to page through (24 wines each). ## `deduplicateWines` (type: `boolean`): Drop duplicate wines (same vintage) that appear more than once in the same run. ## `monitorMode` (type: `boolean`): Remember wines across runs in a named key-value store and emit ONLY wines that are new OR whose price/rating changed since the last run (each carries a changeType: new / price\_drop / price\_rise / rating\_up / rating\_down). Pair with Apify Schedules for price-drop & rating alerts — it complements the scheduler (the schedule starts the run; monitor mode dedupes against prior runs). ## `monitorKey` (type: `string`): Names the monitor's memory store so you can run several independent monitors (e.g. one per filter). Reuse the same key to keep tracking the same feed. ## `maxConcurrency` (type: `integer`): Parallel requests. Keep moderate (3–5) for steady, reliable output. ## `proxyConfiguration` (type: `object`): Proxies to use. Vivino serves cleanly to Apify RESIDENTIAL proxies; keep the default. Datacenter IPs are throttled by Vivino and are not recommended. ## Actor input object example ```json { "wineTypes": [ "red" ], "sortBy": "mostPopular", "marketCountry": "US", "currency": "USD", "includeWineDetails": true, "includeReviews": false, "maxReviewsPerWine": 10, "reviewsLanguage": "any", "includeAllVintages": false, "includeMedianPrice": true, "maxResults": 100, "maxPagesPerSearch": 10, "deduplicateWines": true, "monitorMode": false, "monitorKey": "default", "maxConcurrency": 4, "proxyConfiguration": { "useApifyProxy": true, "apifyProxyGroups": [ "RESIDENTIAL" ] } } ``` # Actor output Schema ## `results` (type: `string`): All scraped Vivino wine records and optional user review records as JSON items in the default dataset. # 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 = { "wineTypes": [ "red" ], "proxyConfiguration": { "useApifyProxy": true, "apifyProxyGroups": [ "RESIDENTIAL" ] } }; // Run the Actor and wait for it to finish const run = await client.actor("scrapesage/vivino-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 = { "wineTypes": ["red"], "proxyConfiguration": { "useApifyProxy": True, "apifyProxyGroups": ["RESIDENTIAL"], }, } # Run the Actor and wait for it to finish run = client.actor("scrapesage/vivino-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 '{ "wineTypes": [ "red" ], "proxyConfiguration": { "useApifyProxy": true, "apifyProxyGroups": [ "RESIDENTIAL" ] } }' | apify call scrapesage/vivino-scraper --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "command": "npx", "args": [ "mcp-remote", "https://mcp.apify.com/?tools=scrapesage/vivino-scraper", "--header", "Authorization: Bearer " ] } } } ``` ## OpenAPI specification ```json { "openapi": "3.0.1", "info": { "title": "Vivino Scraper - Wines, Ratings, Reviews & Prices", "description": "Discover wines on Vivino by type, country, region, grape, price & rating: ratings, taste profile, flavor notes, food pairings, awards, critic & user reviews, live + median prices, and price/rating monitoring.", "version": "0.1", "x-build-id": "ZL9cNwnXs0sVrObvG" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/scrapesage~vivino-scraper/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-scrapesage-vivino-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/scrapesage~vivino-scraper/runs": { "post": { "operationId": "runs-sync-scrapesage-vivino-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/scrapesage~vivino-scraper/run-sync": { "post": { "operationId": "run-sync-scrapesage-vivino-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": { "wineTypes": { "title": "Wine types", "type": "array", "description": "Filter discovery by wine type. Leave empty for all types. Combine with the other filters below to explore Vivino exactly like its own 'Explore wines' page.", "items": { "type": "string", "enum": [ "red", "white", "sparkling", "rose", "dessert", "fortified" ], "enumTitles": [ "Red", "White", "Sparkling", "Rosé", "Dessert", "Fortified" ] } }, "wineCountries": { "title": "Wine origin countries", "type": "array", "description": "Only keep wines made in these countries (ISO codes, lowercase): e.g. us, fr, it, es, pt, ar, cl, au, de. Leave empty for all origins.", "items": { "type": "string" } }, "minRating": { "title": "Minimum rating", "type": "string", "description": "Only keep wines with at least this Vivino average rating (1.0–4.9), e.g. 4.0." }, "priceMin": { "title": "Min price", "minimum": 0, "type": "integer", "description": "Only keep wines priced at or above this amount in the market currency." }, "priceMax": { "title": "Max price", "minimum": 0, "type": "integer", "description": "Only keep wines priced at or below this amount in the market currency." }, "sortBy": { "title": "Sort order", "enum": [ "mostPopular", "topRated", "priceAsc", "priceDesc" ], "type": "string", "description": "How to order discovered wines.", "default": "mostPopular" }, "grapeIds": { "title": "Grape IDs", "type": "array", "description": "Advanced: filter by Vivino grape IDs (numeric). Common: 1 Shiraz/Syrah, 2 Cabernet Sauvignon, 5 Chardonnay, 9 Merlot, 10 Sangiovese, 14 Pinot Noir, 18 Sauvignon Blanc, 22 Tempranillo, 43 Riesling, 64 Nebbiolo.", "items": { "type": "string" } }, "regionIds": { "title": "Region IDs", "type": "array", "description": "Advanced: filter by Vivino region IDs (numeric), e.g. 25 Napa Valley.", "items": { "type": "string" } }, "foodIds": { "title": "Food pairing IDs", "type": "array", "description": "Advanced: filter by Vivino food-pairing IDs (numeric), e.g. 20 Beef, 8 Lamb, 4 Pork, 9 Poultry, 17 Mushrooms, 10 Spicy food, 14 Mature & hard cheese.", "items": { "type": "string" } }, "wineStyleIds": { "title": "Wine style IDs", "type": "array", "description": "Advanced: filter by Vivino wine-style IDs (numeric), e.g. a specific regional style like 'Napa Valley Cabernet Sauvignon'.", "items": { "type": "string" } }, "marketCountry": { "title": "Market country", "type": "string", "description": "Pricing & availability market (ISO country code). Prices and median prices are computed for this market. Default US.", "default": "US" }, "currency": { "title": "Currency", "type": "string", "description": "Currency for all prices (ISO code), e.g. USD, EUR, GBP.", "default": "USD" }, "startUrls": { "title": "Wine page URLs", "type": "array", "description": "Vivino wine page URLs to scrape directly, e.g. https://www.vivino.com/<slug>/w/1234567 or https://www.vivino.com/w/1234567?year=2019. Used in addition to the Explore filters.", "items": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string", "title": "URL of a web page", "format": "uri" } } } }, "wineIds": { "title": "Wine IDs", "type": "array", "description": "Vivino wine IDs to scrape directly (the number in a /w/<id> URL), e.g. 5978015.", "items": { "type": "string" } }, "includeWineDetails": { "title": "Include full wine detail", "type": "boolean", "description": "Enrich each wine with the full detail: description, food pairings, grape composition, alcohol, awards, critic reviews, ratings distribution, recommended drinking window and global/country/region/winery rankings. Turn OFF for a faster/cheaper discovery run (ratings, taste, region, winery, price & image only). Adds one request per wine.", "default": true }, "includeReviews": { "title": "Include user reviews", "type": "boolean", "description": "Pull Vivino community reviews for each wine (star rating, review text, language, date, taster alias, flavor keywords) as separate review records. Adds one request per wine.", "default": false }, "maxReviewsPerWine": { "title": "Max reviews per wine", "minimum": 1, "maximum": 100, "type": "integer", "description": "Maximum number of user reviews to pull per wine when reviews are enabled.", "default": 10 }, "reviewsLanguage": { "title": "Reviews language", "type": "string", "description": "Only keep reviews in this language (ISO code, e.g. en), or any for all languages.", "default": "any" }, "includeAllVintages": { "title": "Include all vintages (direct wines)", "type": "boolean", "description": "For wines provided via URL or ID, emit every available vintage year (one record per year) instead of just the featured vintage — perfect for price/rating-by-year analysis.", "default": false }, "includeMedianPrice": { "title": "Include median market price", "type": "boolean", "description": "Add the median market price alongside the live lowest price for each wine (one extra batched request per page).", "default": true }, "maxResults": { "title": "Max wines", "minimum": 1, "type": "integer", "description": "Maximum number of wine records to scrape across all filters and URLs. Vivino Explore returns 24 wines per page.", "default": 100 }, "maxPagesPerSearch": { "title": "Max Explore pages", "minimum": 1, "maximum": 100, "type": "integer", "description": "How many Explore result pages to page through (24 wines each).", "default": 10 }, "deduplicateWines": { "title": "Deduplicate wines", "type": "boolean", "description": "Drop duplicate wines (same vintage) that appear more than once in the same run.", "default": true }, "monitorMode": { "title": "Monitor mode (only new / changed)", "type": "boolean", "description": "Remember wines across runs in a named key-value store and emit ONLY wines that are new OR whose price/rating changed since the last run (each carries a changeType: new / price_drop / price_rise / rating_up / rating_down). Pair with Apify Schedules for price-drop & rating alerts — it complements the scheduler (the schedule starts the run; monitor mode dedupes against prior runs).", "default": false }, "monitorKey": { "title": "Monitor key", "type": "string", "description": "Names the monitor's memory store so you can run several independent monitors (e.g. one per filter). Reuse the same key to keep tracking the same feed.", "default": "default" }, "maxConcurrency": { "title": "Max concurrency", "minimum": 1, "maximum": 8, "type": "integer", "description": "Parallel requests. Keep moderate (3–5) for steady, reliable output.", "default": 4 }, "proxyConfiguration": { "title": "Proxy configuration", "type": "object", "description": "Proxies to use. Vivino serves cleanly to Apify RESIDENTIAL proxies; keep the default. Datacenter IPs are throttled by Vivino and are not recommended.", "default": { "useApifyProxy": true, "apifyProxyGroups": [ "RESIDENTIAL" ] } } } }, "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 } } } } } } } } } } ```