# Vivino Scraper (`crawlerbros/vivino-scraper`) Actor Scrape Vivino - the world's largest wine app. Search wines by name, explore by type and country, look up wines by ID, or scrape all wines from a specific winery. Returns ratings, prices, grapes, tasting notes, food pairings, and more. - **URL**: https://apify.com/crawlerbros/vivino-scraper.md - **Developed by:** [Crawler Bros](https://apify.com/crawlerbros) (community) - **Categories:** Automation, E-commerce, Integrations - **Stats:** 1 total users, 0 monthly users, 100.0% runs succeeded, NaN bookmarks - **User rating**: No ratings yet ## Pricing from $3.00 / 1,000 results This Actor is paid per event and usage. You are charged both the fixed price for specific events and for Apify platform usage. 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 Scraper Extract wine data from **Vivino** — the world's largest wine community with 60M+ users and 14M+ wines. Retrieve ratings, prices, tasting notes, grapes, food pairings, winery information, and more. ### What You Can Scrape - **Search** wines by name, producer, or region - **Explore** wines by type, country, or price range - **Lookup** specific wines by their Vivino ID - **Browse** all wines from a specific winery ### Use Cases - Wine research and discovery - Price comparison and market analysis - Building wine recommendation systems - Tracking ratings and reviews trends - Competitive analysis for wineries and wine retailers ### Input Configuration | Field | Type | Description | |-------|------|-------------| | `mode` | select | `search`, `explore`, `byWineId`, or `winery` | | `searchQuery` | string | Free-text query (mode=search). E.g. `barolo`, `napa cabernet` | | `wineIds` | array | List of Vivino wine IDs (mode=byWineId) | | `wineryId` | integer | Vivino winery ID (mode=winery) | | `wineType` | select | Filter by type: Red, White, Sparkling, Rosé, Dessert, Fortified | | `country` | select | Filter by country of origin (2-letter ISO code) | | `minRating` / `maxRating` | number | Rating range filter (0–5 scale) | | `minPrice` / `maxPrice` | number | Price range filter in USD | | `orderBy` | select | Sort by: most reviewed, highest rated, or price | | `maxItems` | integer | Maximum number of records to return (default 50, max 2000) | #### Example Input — Search Mode ```json { "mode": "search", "searchQuery": "barolo", "maxItems": 50 } ```` #### Example Input — Explore Mode (Top Rated Italian Reds) ```json { "mode": "explore", "wineType": "1", "country": "it", "minRating": 4.0, "orderBy": "ratings_average", "maxItems": 100 } ``` #### Example Input — Winery Mode ```json { "mode": "winery", "wineryId": 11472, "maxItems": 50 } ``` ### Output Fields Each record contains the following fields (only populated fields are included): | Field | Type | Description | |-------|------|-------------| | `wineId` | integer | Vivino internal wine ID | | `vintageId` | integer | Vivino vintage ID | | `name` | string | Wine name | | `fullName` | string | Full vintage name including winery and year | | `vintage` | integer | Vintage year | | `winery` | string | Winery / producer name | | `wineryUrl` | string | Vivino winery page URL | | `type` | string | Wine type: red, white, sparkling, rose, dessert, fortified | | `typeId` | integer | Vivino wine type ID | | `isNatural` | boolean | Whether this is a natural wine | | `country` | string | Country of origin | | `countryCode` | string | 2-letter ISO country code | | `region` | string | Wine region | | `style` | string | Wine style name (e.g. "Italian Barolo") | | `styleDescription` | string | Detailed style description | | `grapes` | array | Grape varieties used | | `foodPairing` | array | Recommended food pairings | | `tastingNotes` | array | Flavor and tasting note keywords | | `tasteAcidity` | number | Acidity score (1–5) | | `tasteTannin` | number | Tannin score (1–5) | | `tasteSweetness` | number | Sweetness score (1–5) | | `tasteIntensity` | number | Intensity score (1–5) | | `tasteFizziness` | number | Fizziness score (sparkling wines) | | `body` | integer | Body score (1–5) | | `bodyDescription` | string | Body description text | | `acidity` | integer | Acidity level | | `acidityDescription` | string | Acidity description text | | `rating` | number | Average vintage rating (1–5) | | `ratingsCount` | integer | Number of ratings for this vintage | | `wineRating` | number | Average rating across all vintages | | `wineRatingsCount` | integer | Total ratings across all vintages | | `price` | number | Listed price in USD | | `currency` | string | Currency code (USD) | | `imageUrl` | string | Wine label image URL | | `wineUrl` | string | Vivino wine page URL | | `vintageUrl` | string | Vivino vintage page URL | | `topListRankings` | array | Top list appearances (award lists) | | `sourceUrl` | string | Canonical source URL | | `scrapedAt` | string | ISO 8601 timestamp when scraped | | `recordType` | string | Always `wine` | #### Example Output Record ```json { "wineId": 82199, "vintageId": 2459253, "name": "Barolo Riserva Monfortino", "fullName": "Giacomo Conterno Barolo Riserva Monfortino 2013", "vintage": 2013, "winery": "Giacomo Conterno", "type": "red", "country": "Italy", "countryCode": "it", "region": "Barolo", "style": "Italian Barolo", "grapes": ["Nebbiolo"], "foodPairing": ["Beef", "Lamb"], "tastingNotes": ["leather", "tar", "tobacco", "cherry"], "rating": 4.7, "ratingsCount": 528, "wineRating": 4.7, "price": 2307.0, "currency": "USD", "imageUrl": "https://images.vivino.com/thumbs/abc_pl_375x500.png", "wineUrl": "https://www.vivino.com/wines/82199-barolo-riserva-monfortino", "sourceUrl": "https://www.vivino.com/wines/82199-barolo-riserva-monfortino", "scrapedAt": "2026-06-06T12:00:00+00:00", "recordType": "wine" } ``` ### Frequently Asked Questions **Q: How many wines can I scrape?** Set `maxItems` up to 2000 per run. For larger datasets, run multiple times with different search queries or filters. **Q: Can I filter by grape variety?** Use the `searchQuery` field with the grape name (e.g. `nebbiolo`, `pinot noir`). Vivino's search understands grape names. **Q: How do I find a winery's Vivino ID?** Visit the winery's page on vivino.com — the ID appears in the URL, e.g. `https://www.vivino.com/wineries/11472-giacomo-conterno`. **Q: How do I find a wine's Vivino ID?** The wine ID appears in the Vivino wine URL, e.g. `https://www.vivino.com/wines/82199`. **Q: Are prices always in USD?** Yes, prices are standardized to USD for consistency across markets. **Q: Does this scraper require login?** No. Vivino's public API is used and no credentials are required. **Q: How fresh is the data?** Data is fetched live from Vivino at the time of each run. ### Data Source Data is scraped from Vivino's public web API (`vivino.com/api/explore/explore`). No authentication is required. This actor respects Vivino's public data endpoints and does not bypass any access controls. # Actor input Schema ## `mode` (type: `string`): What to fetch. `search` runs a free-text query; `explore` browses wines by type, country or price range; `byWineId` fetches specific wines by Vivino vintage ID (from the vintageId field in search results, or from the URL vivino.com/vintages/{id}); `winery` scrapes all wines from a winery. ## `searchQuery` (type: `string`): Free-text wine search query (mode=search). Example: `barolo`, `chateau petrus`, `napa valley cabernet`. ## `wineIds` (type: `array`): List of Vivino vintage IDs to look up (mode=byWineId). The ID appears in the vintage URL, e.g. https://www.vivino.com/vintages/18745256 → use 18745256. You can get these IDs from the vintageId field in search/explore results. ## `wineryId` (type: `integer`): Vivino winery ID (mode=winery). The ID appears in the winery's Vivino URL path. ## `wineType` (type: `string`): Filter by wine type (applies to search and explore modes). ## `country` (type: `string`): Filter wines by country of origin using 2-letter ISO country code (e.g. `it` for Italy, `fr` for France, `us` for USA). Case-insensitive. ## `minRating` (type: `number`): Filter to wines with rating equal to or above this value (0–5 scale). ## `maxRating` (type: `number`): Filter to wines with rating equal to or below this value (0–5 scale). ## `minPrice` (type: `number`): Filter to wines priced at or above this value in USD. ## `maxPrice` (type: `number`): Filter to wines priced at or below this value in USD. ## `orderBy` (type: `string`): How to sort explore/search results. ## `maxItems` (type: `integer`): Maximum number of wine records to emit. ## Actor input object example ```json { "mode": "search", "searchQuery": "barolo", "wineIds": [ "18745256", "87183621" ], "wineType": "", "country": "", "maxPrice": 500, "orderBy": "ratings_count", "maxItems": 50 } ``` # Actor output Schema ## `wines` (type: `string`): Dataset containing all scraped Vivino wine records. # 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 = { "mode": "search", "searchQuery": "barolo", "wineIds": [ "18745256", "87183621" ], "wineType": "", "country": "", "maxPrice": 500, "orderBy": "ratings_count", "maxItems": 50 }; // Run the Actor and wait for it to finish const run = await client.actor("crawlerbros/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 = { "mode": "search", "searchQuery": "barolo", "wineIds": [ "18745256", "87183621", ], "wineType": "", "country": "", "maxPrice": 500, "orderBy": "ratings_count", "maxItems": 50, } # Run the Actor and wait for it to finish run = client.actor("crawlerbros/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 '{ "mode": "search", "searchQuery": "barolo", "wineIds": [ "18745256", "87183621" ], "wineType": "", "country": "", "maxPrice": 500, "orderBy": "ratings_count", "maxItems": 50 }' | apify call crawlerbros/vivino-scraper --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "command": "npx", "args": [ "mcp-remote", "https://mcp.apify.com/?tools=crawlerbros/vivino-scraper", "--header", "Authorization: Bearer " ] } } } ``` ## OpenAPI specification ```json { "openapi": "3.0.1", "info": { "title": "Vivino Scraper", "description": "Scrape Vivino - the world's largest wine app. Search wines by name, explore by type and country, look up wines by ID, or scrape all wines from a specific winery. Returns ratings, prices, grapes, tasting notes, food pairings, and more.", "version": "1.0", "x-build-id": "ag6ZgIb1VBsb0dbwT" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/crawlerbros~vivino-scraper/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-crawlerbros-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/crawlerbros~vivino-scraper/runs": { "post": { "operationId": "runs-sync-crawlerbros-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/crawlerbros~vivino-scraper/run-sync": { "post": { "operationId": "run-sync-crawlerbros-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", "required": [ "mode" ], "properties": { "mode": { "title": "Mode", "enum": [ "search", "explore", "byWineId", "winery" ], "type": "string", "description": "What to fetch. `search` runs a free-text query; `explore` browses wines by type, country or price range; `byWineId` fetches specific wines by Vivino vintage ID (from the vintageId field in search results, or from the URL vivino.com/vintages/{id}); `winery` scrapes all wines from a winery.", "default": "search" }, "searchQuery": { "title": "Search query", "type": "string", "description": "Free-text wine search query (mode=search). Example: `barolo`, `chateau petrus`, `napa valley cabernet`.", "default": "barolo" }, "wineIds": { "title": "Vivino Vintage IDs (mode=byWineId)", "type": "array", "description": "List of Vivino vintage IDs to look up (mode=byWineId). The ID appears in the vintage URL, e.g. https://www.vivino.com/vintages/18745256 → use 18745256. You can get these IDs from the vintageId field in search/explore results.", "default": [], "items": { "type": "string" } }, "wineryId": { "title": "Winery ID (mode=winery)", "minimum": 1, "type": "integer", "description": "Vivino winery ID (mode=winery). The ID appears in the winery's Vivino URL path." }, "wineType": { "title": "Wine type filter", "enum": [ "", "1", "2", "3", "4", "7", "24" ], "type": "string", "description": "Filter by wine type (applies to search and explore modes).", "default": "" }, "country": { "title": "Country code filter", "enum": [ "", "it", "fr", "us", "es", "de", "pt", "ar", "cl", "au", "nz", "za", "gr", "at", "hu", "ro", "hr", "bg", "si", "rs", "mk", "al", "ge", "am", "az", "md", "ua", "tr", "il", "lb", "cn", "jp", "in", "br", "mx", "ca", "gb" ], "type": "string", "description": "Filter wines by country of origin using 2-letter ISO country code (e.g. `it` for Italy, `fr` for France, `us` for USA). Case-insensitive.", "default": "" }, "minRating": { "title": "Minimum rating", "minimum": 0, "maximum": 5, "type": "number", "description": "Filter to wines with rating equal to or above this value (0–5 scale)." }, "maxRating": { "title": "Maximum rating", "minimum": 0, "maximum": 5, "type": "number", "description": "Filter to wines with rating equal to or below this value (0–5 scale)." }, "minPrice": { "title": "Minimum price (USD)", "minimum": 0, "type": "number", "description": "Filter to wines priced at or above this value in USD." }, "maxPrice": { "title": "Maximum price (USD)", "minimum": 0, "type": "number", "description": "Filter to wines priced at or below this value in USD.", "default": 500 }, "orderBy": { "title": "Sort order", "enum": [ "ratings_count", "ratings_average", "price" ], "type": "string", "description": "How to sort explore/search results.", "default": "ratings_count" }, "maxItems": { "title": "Max items", "minimum": 1, "maximum": 2000, "type": "integer", "description": "Maximum number of wine records to emit.", "default": 50 } } }, "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 } } } } } } } } } } ```