{ "openapi": "3.0.1", "info": { "title": "Vivino Scraper & API: Wine Ratings and Prices in 22 Markets", "description": "Vivino scraper and unofficial Vivino API: wine ratings data and wine prices by any of 4,186 regions, 2,233 grapes or 747 styles, or look up your own wine list, in up to 10 of 22 markets per run, with price change monitoring. From USD 1.50 per 1,000.", "version": "1.0", "x-build-id": "2V4pUrO18bglW5Jq2" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/usefulapi~vivino-scraper/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-usefulapi-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/usefulapi~vivino-scraper/runs": { "post": { "operationId": "runs-sync-usefulapi-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/usefulapi~vivino-scraper/run-sync": { "post": { "operationId": "run-sync-usefulapi-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": { "markets": { "title": "Markets (ship-to countries)", "type": "array", "description": "Where the wine is sold. Vivino shows each wine with the price of a merchant in that market, so the same wine has a different price (or none) per market. Pick several to compare prices side by side: one row per wine per market. Up to 10.", "items": { "type": "string", "enum": [ "US", "CA", "GB", "FR", "DE", "AT", "CH", "IT", "ES", "PT", "NL", "BE", "LU", "DK", "SE", "FI", "CZ", "AU", "JP", "SG", "HK", "BR" ], "enumTitles": [ "United States (US)", "Canada (CA)", "United Kingdom (GB)", "France (FR)", "Germany (DE)", "Austria (AT)", "Switzerland (CH)", "Italy (IT)", "Spain (ES)", "Portugal (PT)", "Netherlands (NL)", "Belgium (BE)", "Luxembourg (LU)", "Denmark (DK)", "Sweden (SE)", "Finland (FI)", "Czech Republic (CZ)", "Australia (AU)", "Japan (JP)", "Singapore (SG)", "Hong Kong (HK)", "Brazil (BR)" ] }, "default": [ "US" ] }, "wines": { "title": "Wine lookup: Vivino URLs, wine IDs or names", "type": "array", "description": "Your own list of wines, one per line: a Vivino address (https://www.vivino.com/.../w/1911534?year=2015), a wine ID (1911534) or a name with an optional year (Opus One 2015, Chateau Margaux, Caymus Cabernet Sauvignon). Each wine gets its rating, the vintage's own rating and rating spread, Vivino's rankings, critic scores, drinking window, alcohol and grapes, plus the price in each market you picked. A Vivino address works for any wine, on sale or not; a name uses Vivino's search, which lists wines on sale in the market, and the row says which wine it took. Not found, ambiguous or invalid lines are saved and never billed. Up to 2,000.", "items": { "type": "string" } }, "includeAllVintages": { "title": "Add every vintage's rating (lookup)", "type": "boolean", "description": "With the wine lookup: add a column listing every vintage of the wine with its year, Vivino rating and number of ratings, at no extra cost.", "default": false }, "searchTerms": { "title": "Search by wine or producer name", "type": "array", "description": "Optional. Each term is searched on its own (Vivino's own search), for example Opus One, Sassicaia, Penfolds Grange. A wine appears once per market: if an earlier term already found it, a later term skips it. Combine with the filters below or use alone. Up to 25.", "items": { "type": "string" } }, "regions": { "title": "Regions", "type": "array", "description": "Any of Vivino's 4,186 regions by name: Napa Valley, Barolo, Bordeaux, Rioja, Champagne, Mosel... Sub-regions are included (Napa Valley also gives Oakville and Rutherford). A name used in two countries takes both; write \"Central Valley, Chile\" for one. A typo stops the run before any request, with suggestions.", "items": { "type": "string" } }, "countries": { "title": "Wine countries (origin)", "type": "array", "description": "Where the wine is made, by name or code: Italy or IT, France, US, Portugal... (not the market you buy in).", "items": { "type": "string" } }, "grapes": { "title": "Grapes", "type": "array", "description": "Any of 2,233 grapes by name: Pinot Noir, Nebbiolo, Syrah, Chardonnay, Riesling...", "items": { "type": "string" } }, "wineTypes": { "title": "Wine types", "type": "array", "description": "Red, white, sparkling, rosé, dessert or fortified. Several = any of them.", "items": { "type": "string", "enum": [ "red", "white", "sparkling", "rose", "dessert", "fortified" ], "enumTitles": [ "Red", "White", "Sparkling", "Rosé", "Dessert", "Fortified" ] } }, "styles": { "title": "Wine styles", "type": "array", "description": "Vivino's 747 wine styles by name, for example Napa Valley Cabernet Sauvignon, Italian Barolo, Spanish Rioja Red, Champagne.", "items": { "type": "string" } }, "foods": { "title": "Food pairing", "type": "array", "description": "Wines Vivino pairs with: Beef, Lamb, Pork, Poultry, Pasta, Shellfish, Spicy food, Mature and hard cheese...", "items": { "type": "string" } }, "minRating": { "title": "Minimum Vivino rating", "minimum": 1, "maximum": 5, "type": "number", "description": "From 1 to 5, for example 4 or 4.2. Wines without a published rating are left out when this is set." }, "minPrice": { "title": "Minimum price per bottle", "minimum": 0, "type": "integer", "description": "Per bottle, in the currency below, or else in each market's own (US = USD, GB = GBP, CH = CHF, euro markets = EUR). Leave empty for no minimum." }, "maxPrice": { "title": "Maximum price per bottle", "minimum": 0, "type": "integer", "description": "Per bottle, same currency as the minimum. With several markets in different currencies, set the currency below. Leave empty for no maximum." }, "currency": { "title": "Currency", "enum": [ "", "USD", "EUR", "GBP", "CHF", "CAD", "AUD", "JPY", "SGD", "HKD", "DKK", "SEK", "CZK", "BRL" ], "type": "string", "description": "Empty = each market's own currency. Set one (for example USD) to compare markets in a single currency (Vivino converts) or to use a price band across markets.", "default": "" }, "sortBy": { "title": "Sort by", "enum": [ "rating", "ratings_count", "price", "discount" ], "type": "string", "description": "Vivino's order. maxResults keeps the first ones in this order.", "default": "rating" }, "sortOrder": { "title": "Order", "enum": [ "desc", "asc" ], "type": "string", "description": "Highest first or lowest first, in the order chosen above.", "default": "desc" }, "maxResults": { "title": "Max wines per market and search", "minimum": 1, "maximum": 10000, "type": "integer", "description": "Each market (and each search term) gives up to this many wines. About 1,000 wines a minute. Up to 10,000.", "default": 100 }, "watch": { "title": "Watch name (monitoring)", "type": "string", "description": "Give the search a name (for example napa-cabs) and schedule the run. Each run is compared with the previous run of the same watch: every row gets change = new, price_down, price_up, rating_changed, unchanged or removed, with the old price and the change in %. The last run's wines are kept in your account's key-value store vivino-wines-watch. Changing the filters or the currency starts a new baseline. A watch keeps up to 50,000 wines." }, "onlyChanges": { "title": "Save only changes", "type": "boolean", "description": "With a watch: save only wines that are new, removed or changed in price or rating. Unchanged wines are not saved and are billed at USD 0.20 per 1,000 instead of USD 1.50. The first run of a watch saves every wine (the baseline).", "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 }, "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 } } } } } } } } } }