{ "openapi": "3.0.1", "info": { "title": "Wine Data Scraper for Vivino - Ratings, Reviews & Prices", "description": "Search Vivino wines by name or with Explore filters: ratings, taste and flavor notes, food pairings, grapes, awards, critic scores, prices and every shop offer for your market and U.S. state, community reviews and price monitoring. Independent tool, not affiliated with Vivino.", "version": "0.1", "x-build-id": "eObMbzhajWp5bpg9T" }, "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": { "searchTerms": { "title": "Search by name", "type": "array", "description": "Find wines by name, like Vivino's own search box: a wine, a winery, a grape or a region in words, e.g. opus one, caymus cabernet, barolo. Each term is its own search, best match first, and the filters below still apply. Leave empty to browse with the filters only.", "items": { "type": "string" } }, "wineTypes": { "title": "Wine types", "type": "array", "description": "Only these wine types. Leave empty for every type.", "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 wines made in these countries. Pick from the list, or type a 2-letter code (fr) or a country name (France). Leave empty for every origin.", "items": { "type": "string", "enumSuggestedValues": [ "fr", "it", "es", "us", "pt", "de", "ar", "cl", "au", "nz", "za", "at", "gr", "hu", "ca", "br", "uy", "il", "ro", "ge", "hr", "si", "lb", "mx", "ch", "gb", "bg", "md", "cn", "jp" ], "enumTitles": [ "France (fr)", "Italy (it)", "Spain (es)", "United States (us)", "Portugal (pt)", "Germany (de)", "Argentina (ar)", "Chile (cl)", "Australia (au)", "New Zealand (nz)", "South Africa (za)", "Austria (at)", "Greece (gr)", "Hungary (hu)", "Canada (ca)", "Brazil (br)", "Uruguay (uy)", "Israel (il)", "Romania (ro)", "Georgia (ge)", "Croatia (hr)", "Slovenia (si)", "Lebanon (lb)", "Mexico (mx)", "Switzerland (ch)", "United Kingdom (gb)", "Bulgaria (bg)", "Moldova (md)", "China (cn)", "Japan (jp)" ] } }, "minRating": { "title": "Minimum rating", "type": "string", "description": "Only wines with at least this Vivino average rating, from 1.0 to 5.0, e.g. 4.0 or 4.2." }, "priceMin": { "title": "Min price", "minimum": 0, "type": "integer", "description": "Only wines priced at or above this amount, in the currency below." }, "priceMax": { "title": "Max price", "minimum": 0, "type": "integer", "description": "Only wines priced at or below this amount, in the currency below." }, "discountedOnly": { "title": "On sale only", "type": "boolean", "description": "Only wines whose offer is discounted right now (Vivino's own deals filter). Each row then carries regularPrice and discountPercent.", "default": false }, "vintageYears": { "title": "Vintage years", "type": "array", "description": "Only these vintages, e.g. 2019, 2020. Leave empty for every year.", "items": { "type": "string" } }, "naturalOnly": { "title": "Natural wines only", "type": "boolean", "description": "Only wines Vivino lists as natural.", "default": false }, "sortBy": { "title": "Sort order", "enum": [ "mostPopular", "topRated", "priceAsc", "priceDesc", "relevance", "biggestDiscount" ], "type": "string", "description": "How to order the wines. With search terms, Most rated means best match first (Vivino's relevance order); pick another order to change it.", "default": "mostPopular" }, "grapes": { "title": "Grapes (by name)", "type": "array", "description": "Only wines made from these grapes, by name, e.g. Pinot Noir, Malbec, Nebbiolo. Names are matched to Vivino's own grape list; a name Vivino does not know stops the run before any wine is billed, with suggestions.", "items": { "type": "string" } }, "regions": { "title": "Regions (by name)", "type": "array", "description": "Only wines from these regions, by name, e.g. Napa Valley, Bordeaux, Rioja, Tuscany, Barolo.", "items": { "type": "string" } }, "wineStyles": { "title": "Wine styles (by name)", "type": "array", "description": "Only wines of these Vivino styles, e.g. Californian Pinot Noir, Spanish Rioja Red, Napa Valley Cabernet Sauvignon.", "items": { "type": "string" } }, "foods": { "title": "Food pairings", "type": "array", "description": "Only wines Vivino pairs with these foods.", "items": { "type": "string", "enum": [ "Beef", "Lamb", "Veal", "Pork", "Game (deer, venison)", "Poultry", "Mushrooms", "Cured Meat", "Goat's Milk Cheese", "Mature and hard cheese", "Mild and soft cheese", "Blue cheese", "Pasta", "Spicy food", "Shellfish", "Lean fish", "Rich fish (salmon, tuna etc)", "Vegetarian", "Appetizers and snacks", "Aperitif", "Sweet desserts", "Fruity desserts", "Any junk food will do" ] } }, "grapeIds": { "title": "Grape IDs", "type": "array", "description": "Advanced: Vivino grape IDs, e.g. 1 Shiraz/Syrah, 2 Cabernet Sauvignon, 5 Chardonnay, 8 Grenache, 9 Malbec, 10 Merlot, 12 Nebbiolo, 14 Pinot Noir, 15 Riesling, 16 Sangiovese, 17 Sauvignon Blanc, 19 Tempranillo, 21 Zinfandel. Grapes (by name) above is easier.", "items": { "type": "string" } }, "regionIds": { "title": "Region IDs", "type": "array", "description": "Advanced: Vivino region IDs, e.g. 25 Napa Valley, 26 Sonoma County, 383 Bordeaux, 385 Bourgogne, 394 Toscana, 409 Champagne, 454 Mendoza, 492 Rioja, 504 Barolo.", "items": { "type": "string" } }, "foodIds": { "title": "Food pairing IDs", "type": "array", "description": "Advanced: Vivino food IDs, e.g. 4 Beef, 8 Lamb, 9 Veal, 10 Pork, 20 Poultry, 34 Mushrooms, 15 Spicy food, 17 Mature and hard cheese, 5 Pasta, 13 Shellfish.", "items": { "type": "string" } }, "wineStyleIds": { "title": "Wine style IDs", "type": "array", "description": "Advanced: Vivino wine-style IDs, e.g. 157 Californian Pinot Noir. Wine styles (by name) above is easier.", "items": { "type": "string" } }, "marketCountry": { "title": "Market country", "type": "string", "description": "The market whose shops, prices and availability you want. Vivino sells in US, CA, GB, DE, FR, IT, ES, PT, NL, BE, LU, CH, AT, DK, SE, FI, CZ, AU, JP, HK, SG and BR (codes or names). The actor sets this market with Vivino's own ship-to setting, so no proxy in that country is needed.", "default": "US" }, "marketState": { "title": "State or province (US and Canada)", "type": "string", "description": "U.S. shops and prices differ by state (California lists about 73,000 red wines, Utah about 8,000). Leave empty for California, or pick the state you ship to. For Canada, a province is optional." }, "currency": { "title": "Currency", "type": "string", "description": "Currency for every price (ISO code), e.g. USD, EUR, GBP. When it differs from the market's own currency, each row also carries marketCurrency and medianPriceLocal.", "default": "USD" }, "includeMedianPrice": { "title": "Include median market price", "type": "boolean", "description": "Add Vivino's median market price next to the featured offer's price (one extra batched request per page of results).", "default": true }, "includeAllOffers": { "title": "Include every shop's offer", "type": "boolean", "description": "List every shop selling the wine in your market in offers (shop name, price, bottle size, link), not only the featured offer. Adds one request per wine; popular wines have 50 or more shops.", "default": false }, "startUrls": { "title": "Vivino links", "type": "array", "description": "Paste Vivino links: wine pages (https://www.vivino.com/<slug>/w/1234567, add ?year=2019 for a vintage), vintage pages (/wines/<id>), Explore pages (every filter in the link is kept) or search pages (/search/wines?q=...). The Console's file import and link-to-file options work too.", "items": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string", "title": "URL of a web page", "format": "uri" } } } }, "urlsFromFile": { "title": "Import links or IDs from a file", "type": "string", "description": "Paste a list of Vivino links and/or wine IDs (one per line), or one link to a .txt/.csv file or a Google Sheet that holds them." }, "wineIds": { "title": "Wine IDs", "type": "array", "description": "Vivino wine IDs to scrape directly (the number in a /w/<id> link), e.g. 1136137.", "items": { "type": "string" } }, "includeAllVintages": { "title": "Include all vintages (links and IDs)", "type": "boolean", "description": "For wines given by link or ID, deliver every vintage year (one row per year) instead of one: price and rating by year.", "default": false }, "includeWineDetails": { "title": "Include full wine detail", "type": "boolean", "description": "Add each wine's full detail: description, grape shares, vintage ABV, allergens, awards, critic reviews, ratings distribution, drinking window and advice, rankings, winery rating and the shop's name. Turn off for a faster run with the search card only (ratings, taste, region, winery, price, image). The price per wine is the same either way.", "default": true }, "includeReviews": { "title": "Include user reviews", "type": "boolean", "description": "Deliver Vivino community reviews for each wine as separate rows: stars, review text, language, date, likes, the flavor words the taster used, and the taster's name, profile and rating counts.", "default": false }, "maxReviewsPerWine": { "title": "Max reviews per wine", "minimum": 1, "maximum": 1000, "type": "integer", "description": "Up to this many reviews per wine (Vivino has thousands for popular wines).", "default": 10 }, "reviewsSort": { "title": "Reviews order", "enum": [ "helpful", "recent" ], "type": "string", "description": "Most helpful first (Vivino's default), or newest first, which is best for collecting new reviews on a schedule.", "default": "helpful" }, "reviewsLanguage": { "title": "Reviews language", "type": "string", "description": "Only reviews in this language (a code such as en, fr, de, or a name such as French). any keeps Vivino's default, which for most-helpful reviews means mostly English reviews.", "default": "any" }, "reviewStars": { "title": "Review stars", "type": "array", "description": "Only reviews with these star ratings (2 means 2.0 to 2.9). Leave empty for every rating. For example 1 and 2 collect the critical reviews.", "items": { "type": "string", "enum": [ "1", "2", "3", "4", "5" ], "enumTitles": [ "1 star", "2 stars", "3 stars", "4 stars", "5 stars" ] } }, "maxResults": { "title": "Max wines", "minimum": 1, "type": "integer", "description": "Maximum number of wine rows across all searches, links and IDs (reviews are extra rows). 100 if left empty; a run with nothing to search returns a 25-wine sample." }, "maxPagesPerSearch": { "title": "Max Explore pages per search", "minimum": 1, "maximum": 3000, "type": "integer", "description": "Read at most this many Explore pages of 24 wines per search (10 pages = up to 240 wines per search). Vivino's Explore lists about 2,000 wines per search at most; split bigger searches with a price band, country or rating.", "default": 10 }, "deduplicateWines": { "title": "Deduplicate wines", "type": "boolean", "description": "Deliver each vintage once per run, even when several searches find it.", "default": true }, "monitorMode": { "title": "Monitor mode (only new or changed)", "type": "boolean", "description": "Remember wines across runs and deliver only wines that are new or whose price or rating changed since the last run, each with a changeType: new, price_drop, price_rise, rating_up, rating_down or changed. Each search watches its first wines (up to Max wines within Max Explore pages); unchanged wines are skipped and not billed. Pair it with an Apify Schedule for price-drop alerts.", "default": false }, "monitorKey": { "title": "Monitor key", "type": "string", "description": "Names the monitor's memory so you can run several independent monitors (for example one per search). Reuse the same key to keep tracking the same wines.", "default": "default" }, "maxConcurrency": { "title": "Max concurrency", "minimum": 1, "maximum": 8, "type": "integer", "description": "Wines read in parallel.", "default": 4 }, "proxyConfiguration": { "title": "Proxy configuration", "type": "object", "description": "Optional. The actor picks a working connection itself (a direct connection first, Apify Residential as the fallback) and sets your market with Vivino's own ship-to setting, so the proxy country does not change prices. Your own proxy URLs, if you add them, are tried first. Turning Apify Proxy off keeps the run on the direct connection only.", "default": { "useApifyProxy": true } } } }, "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 }, "PROXY_UNBLOCKER_UNITS": { "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 }, "PROXY_UNBLOCKER_UNITS": { "type": "integer", "example": 0 } } } } } } } } } }