{
  "openapi": "3.0.1",
  "info": {
    "title": "Vivino Scraper - Wine Prices, Ratings, Reviews & Taste Profiles",
    "description": "Vivino wines by search, name list, URL, ID, winery or Explore filters (type, country, region, grape, food, rating, price): shop price in 28 markets, ratings, taste profile, food pairings, critic scores, ranks, shop offers. Reviews, monitor mode. $0.90 per 1,000 wines, no start fee.",
    "version": "0.1",
    "x-build-id": "SvzdaSZduGqOQQJBh"
  },
  "servers": [
    {
      "url": "https://api.apify.com/v2"
    }
  ],
  "paths": {
    "/acts/topapi~vivino-scraper/run-sync-get-dataset-items": {
      "post": {
        "operationId": "run-sync-get-dataset-items-topapi-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/topapi~vivino-scraper/runs": {
      "post": {
        "operationId": "runs-sync-topapi-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/topapi~vivino-scraper/run-sync": {
      "post": {
        "operationId": "run-sync-topapi-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": {
          "mode": {
            "title": "Mode",
            "enum": [
              "wines",
              "reviews"
            ],
            "type": "string",
            "description": "wines = one row per wine vintage found (default). reviews = only the community reviews of every wine found (no wine rows).",
            "default": "wines"
          },
          "searchQueries": {
            "title": "Search terms",
            "type": "array",
            "description": "Wine names, wineries, grapes or regions, one per line, as you would type them in Vivino's search box (e.g. Barolo, Caymus Cabernet, Tignanello 2019). Each term returns every matching vintage on sale in the market, up to Max results per search. A year in the term picks that vintage (see Vintage handling). A term Vivino's shop does not sell is looked up in Vivino's full wine index instead (no price then).",
            "items": {
              "type": "string"
            }
          },
          "wines": {
            "title": "Wines to look up (one best match each)",
            "type": "array",
            "description": "Your own list, one per line: a wine name with or without a year (Opus One 2018, Dom Perignon), a Vivino link or a wine ID. Each line returns its single best match (with matchScore); Advanced matching adds the runner-up. A name without a year returns the most-rated bottle on sale in the market, or the wine's all-vintages record when none is on sale.",
            "items": {
              "type": "string"
            }
          },
          "startUrls": {
            "title": "Vivino links",
            "type": "array",
            "description": "Any public Vivino link: wine page (https://www.vivino.com/US/en/tignanello/w/1652, add ?year=2019 for one vintage), vintage page (/wines/159365358), winery (/wineries/antinori-tuscany), Explore page with your filters (/explore?e=...), search (/search/wines?q=barolo), grape (/grapes/nebbiolo), region (/wine-regions/napa-valley), style (/wine-styles/...) or country (/wine-countries/italy). You can also upload a text file of links.",
            "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 (the number in a /w/1652 link), one per line. Each returns the wine's all-vintages row, or every vintage with Include all vintages.",
            "items": {
              "type": "string"
            }
          },
          "vintageIds": {
            "title": "Vintage IDs",
            "type": "array",
            "description": "Vivino vintage IDs (the number in a /wines/159365358 link or the vintageId of a row), one per line.",
            "items": {
              "type": "string"
            }
          },
          "wineries": {
            "title": "Wineries",
            "type": "array",
            "description": "Winery names, IDs or /wineries/ links, one per line. Each returns the winery's full catalogue: one all-vintages row per wine (or every vintage with Include all vintages), sold in the market or not.",
            "items": {
              "type": "string"
            }
          },
          "urlsFromFile": {
            "title": "Links and IDs from a list or file",
            "type": "string",
            "description": "Paste Vivino links and wine IDs (one per line), or one link to a .txt / .csv file or a public Google Sheet that holds them."
          },
          "wineTypes": {
            "title": "Wine types",
            "type": "array",
            "description": "Only these types. Leave empty for every type. Applies to Explore and to search terms.",
            "items": {
              "type": "string",
              "enum": [
                "red",
                "white",
                "sparkling",
                "rose",
                "dessert",
                "fortified"
              ],
              "enumTitles": [
                "Red",
                "White",
                "Sparkling",
                "Rosé",
                "Dessert",
                "Fortified"
              ]
            }
          },
          "countries": {
            "title": "Countries of origin",
            "type": "array",
            "description": "Where the wine is made: 2-letter codes (fr, it, us) or names (France, Italy). Not the market you buy in.",
            "items": {
              "type": "string"
            }
          },
          "regions": {
            "title": "Regions",
            "type": "array",
            "description": "Region names as Vivino names them (Napa Valley, Bordeaux, Barolo, Rioja, Toscana) or region IDs. Sub-regions are included by Vivino.",
            "items": {
              "type": "string"
            }
          },
          "grapes": {
            "title": "Grapes",
            "type": "array",
            "description": "Grape names (Pinot Noir, Nebbiolo, Malbec) or Vivino grape IDs.",
            "items": {
              "type": "string"
            }
          },
          "wineStyles": {
            "title": "Wine styles",
            "type": "array",
            "description": "Vivino style names (Californian Pinot Noir, Italian Barolo, Spanish Rioja Red) or style IDs.",
            "items": {
              "type": "string"
            }
          },
          "foods": {
            "title": "Food pairings",
            "type": "array",
            "description": "Only wines Vivino pairs with these foods: Beef, Lamb, Pork, Poultry, Pasta, Shellfish, Spicy food, Mature and hard cheese... (names or food IDs).",
            "items": {
              "type": "string"
            }
          },
          "minRating": {
            "title": "Minimum rating",
            "minimum": 1,
            "maximum": 5,
            "type": "number",
            "description": "Only wines with at least this Vivino average rating (1 to 5), e.g. 4 or 4.2."
          },
          "maxRating": {
            "title": "Maximum rating",
            "minimum": 1,
            "maximum": 5,
            "type": "number",
            "description": "Only wines rated at most this (1 to 5)."
          },
          "minRatingsCount": {
            "title": "Minimum number of ratings",
            "minimum": 0,
            "type": "integer",
            "description": "Only wines with at least this many community ratings (a 4.5 from 20 people is weaker than a 4.3 from 20,000)."
          },
          "priceMin": {
            "title": "Minimum price",
            "minimum": 0,
            "type": "number",
            "description": "Per bottle, in the currency below (or the market's own currency)."
          },
          "priceMax": {
            "title": "Maximum price",
            "minimum": 0,
            "type": "number",
            "description": "Per bottle, in the currency below (or the market's own currency)."
          },
          "vintageYears": {
            "title": "Vintage years",
            "type": "array",
            "description": "Only these vintages, e.g. 2019, 2020.",
            "items": {
              "type": "string"
            }
          },
          "discountedOnly": {
            "title": "Discounted wines only",
            "type": "boolean",
            "description": "Only wines whose featured offer is discounted right now (each row then carries discountedFrom and discountPercent).",
            "default": false
          },
          "naturalOnly": {
            "title": "Natural wines only",
            "type": "boolean",
            "description": "Only wines Vivino lists as natural.",
            "default": false
          },
          "sortBy": {
            "title": "Sort by",
            "enum": [
              "mostPopular",
              "topRated",
              "priceAsc",
              "priceDesc",
              "biggestDiscount",
              "bestPicks",
              "relevance"
            ],
            "type": "string",
            "description": "Vivino's own order for Explore and search terms. Max results keeps the first ones in this order.",
            "default": "mostPopular"
          },
          "countryCode": {
            "title": "Market (shop country)",
            "enum": [
              "US",
              "CA",
              "GB",
              "IE",
              "FR",
              "DE",
              "IT",
              "ES",
              "PT",
              "NL",
              "BE",
              "LU",
              "AT",
              "CH",
              "DK",
              "SE",
              "NO",
              "FI",
              "CZ",
              "PL",
              "AU",
              "NZ",
              "JP",
              "HK",
              "SG",
              "BR",
              "MX",
              "ZA"
            ],
            "type": "string",
            "description": "The country whose shops, prices and availability you want. Vivino shows each visitor the shops of the country they browse from, so the US market is read from the platform's own (US, Virginia) address and every other market through Apify's residential proxy in that country (included in the price).",
            "default": "US"
          },
          "markets": {
            "title": "Several markets (compare prices)",
            "type": "array",
            "description": "Up to 10 market country codes (US, GB, FR, DE...). Each market returns its own rows (the market field says which), so the same wine shows its price in each. Overrides Market.",
            "items": {
              "type": "string"
            }
          },
          "currencyCode": {
            "title": "Currency",
            "type": "string",
            "description": "ISO currency for every price (USD, EUR, GBP, CHF...). Empty = the market's own currency. Vivino converts the Explore and search prices; the median price stays in the market's currency (medianPriceCurrency)."
          },
          "includeTasteProfile": {
            "title": "Include taste profile",
            "type": "boolean",
            "description": "Body, acidity, tannins, sweetness, fizziness, the community's flavour notes and the style's body and acidity notes. No extra request for Explore and search rows.",
            "default": true
          },
          "includeStyleInfo": {
            "title": "Include style texts",
            "type": "boolean",
            "description": "Add the wine style's description, blurb and facts (the same texts on every wine of a style).",
            "default": false
          },
          "includeWineDetails": {
            "title": "Include wine details",
            "type": "boolean",
            "description": "Description, alcohol, residual sugar, acidity, closure, allergens, winemaker, grape shares, critic scores, awards, star distribution, global / country / region / winery rank, drinking window and the wine's own food pairings (one batched request per 50 wines).",
            "default": true
          },
          "includeMedianPrice": {
            "title": "Include median market price",
            "type": "boolean",
            "description": "Vivino's median price across the market's shops next to the featured price (one batched request per 50 wines).",
            "default": true
          },
          "includeAllOffers": {
            "title": "Include every shop offer",
            "type": "boolean",
            "description": "List every shop selling the wine in the market (shop, price, bottle size, stock, link) in offers. One request per wine. When the asked vintage is not on sale, Vivino lists the offers of the vintage it sells (sameVintage false).",
            "default": false
          },
          "includeHighlights": {
            "title": "Include highlights",
            "type": "boolean",
            "description": "Vivino's highlights per wine (\"96 by Wine Spectator\", \"Top 1% of wines in the world\", value for money) and the critic's name on matching critic scores. One request per wine.",
            "default": false
          },
          "includeAllVintages": {
            "title": "Include all vintages",
            "type": "boolean",
            "description": "For wine links, wine IDs and wineries: one row per vintage year that has ratings (price and rating by year) instead of the all-vintages row.",
            "default": false
          },
          "vintageStartYear": {
            "title": "All vintages from year",
            "minimum": 1800,
            "maximum": 2100,
            "type": "integer",
            "description": "With Include all vintages: only vintages from this year on."
          },
          "includeRatingsDistribution": {
            "title": "Include the star distribution",
            "type": "boolean",
            "description": "Ratings per star (1 to 5) for each vintage. One request per wine.",
            "default": false
          },
          "includeVintageList": {
            "title": "Include the vintage list column",
            "type": "boolean",
            "description": "Add a vintages column to each row: every vintage of the wine with its year, rating, ratings and reviews count.",
            "default": false
          },
          "includeReviews": {
            "title": "Include reviews",
            "type": "boolean",
            "description": "Also deliver community reviews of each wine as review rows (stars, text, language, date, likes, comments, the taster's name, profile and counts). Charged per review.",
            "default": false
          },
          "maxReviewsPerWine": {
            "title": "Max reviews per wine",
            "minimum": 0,
            "type": "integer",
            "description": "Up to this many reviews per wine (Vivino has thousands for popular wines). Default 10, or 50 in reviews mode. 0 in reviews mode = all."
          },
          "reviewsSort": {
            "title": "Review order",
            "enum": [
              "helpful",
              "recent"
            ],
            "type": "string",
            "description": "Most helpful first (Vivino's default) or newest first (best for collecting new reviews on a schedule).",
            "default": "helpful"
          },
          "reviewsLanguage": {
            "title": "Review language",
            "type": "string",
            "description": "Only reviews in this language (a 2-letter code: en, fr, de, it, es, pt...). Empty = Vivino's default (most-helpful reviews in English, newest reviews in every language)."
          },
          "reviewStars": {
            "title": "Review stars",
            "type": "array",
            "description": "Only reviews with these star ratings (2 = 2.0 to 2.9), e.g. 1 and 2 for the critical ones. Empty = every rating.",
            "items": {
              "type": "string"
            }
          },
          "reviewMinRating": {
            "title": "Minimum review rating",
            "minimum": 1,
            "maximum": 5,
            "type": "number",
            "description": "Only reviews rated at least this (1 to 5)."
          },
          "reviewsForVintageOnly": {
            "title": "Reviews of that vintage only",
            "type": "boolean",
            "description": "On: a vintage row gets the reviews of that year. Off: reviews across all vintages of the wine.",
            "default": true
          },
          "reviewsNewerThan": {
            "title": "Reviews newer than",
            "type": "string",
            "description": "Only reviews written on or after this date (YYYY-MM-DD)."
          },
          "reviewsOutput": {
            "title": "Review output",
            "enum": [
              "rows",
              "nested"
            ],
            "type": "string",
            "description": "rows = one row per review (default). nested = the reviews inside their wine row (reviews column); each review is still charged as a review.",
            "default": "rows"
          },
          "vintageHandling": {
            "title": "Vintage handling (search terms and look-ups)",
            "enum": [
              "auto",
              "name_and_vintage",
              "name_only"
            ],
            "type": "string",
            "description": "auto = a year in the term picks that vintage, no year returns every vintage. name_and_vintage = a year must match exactly (no fallback). name_only = the year is ignored and every vintage is returned.",
            "default": "auto"
          },
          "matchingMode": {
            "title": "Matching (wine look-ups)",
            "enum": [
              "basic",
              "advanced"
            ],
            "type": "string",
            "description": "basic = the best match per name. advanced = also the runner-up (isAlternative true) when it matches the name well.",
            "default": "basic"
          },
          "searchAllWines": {
            "title": "Search Vivino's full wine index too",
            "type": "boolean",
            "description": "When a name is not on sale in the market, find it in Vivino's full wine index (the site's own search box) and deliver it without a market price.",
            "default": true
          },
          "maxResults": {
            "title": "Max results",
            "minimum": 0,
            "type": "integer",
            "description": "Maximum wine rows across the whole run (reviews mode: maximum reviews). 0 = no limit. Explore serves about 2,000 wines per query; past that the actor splits the query into price bands automatically.",
            "default": 25
          },
          "maxResultsPerSearch": {
            "title": "Max results per search",
            "minimum": 0,
            "type": "integer",
            "description": "Cap per search term, Explore link or filter set. 0 = up to Max results."
          },
          "deduplicateWines": {
            "title": "Deduplicate wines",
            "type": "boolean",
            "description": "Deliver each vintage once per run (per market), even when several searches find it.",
            "default": true
          },
          "maxConcurrency": {
            "title": "Max concurrency",
            "minimum": 1,
            "maximum": 20,
            "type": "integer",
            "description": "Requests in flight at once.",
            "default": 8
          },
          "monitorMode": {
            "title": "Monitor mode (only new and changed)",
            "type": "boolean",
            "description": "Remember the wines across runs and deliver only wines that are new or whose price or rating changed, each with changeType (new, price_drop, price_rise, price_added, price_removed, rating_up, rating_down) and the previous value; with reviews on, only reviews newer than the last run. Run it on a schedule.",
            "default": false
          },
          "monitorKey": {
            "title": "Monitor name",
            "type": "string",
            "description": "Names the monitor's memory, so several monitors can run side by side. Empty = derived from the input."
          },
          "monitorStoreName": {
            "title": "Monitor store",
            "type": "string",
            "description": "Name of the monitor memory in your account: a named key-value store for wine monitors, a named dataset (this name + -r-...) for reviews-mode monitors.",
            "default": "vivino-monitor"
          },
          "monitorChanges": {
            "title": "Changes that count",
            "type": "array",
            "description": "Which changes make a known wine come back: price, rating. Empty = both.",
            "items": {
              "type": "string",
              "enum": [
                "price",
                "rating"
              ],
              "enumTitles": [
                "Price",
                "Rating"
              ]
            }
          },
          "emitUnchanged": {
            "title": "Also deliver unchanged wines",
            "type": "boolean",
            "description": "Monitor mode: also deliver (and pay for) known wines that did not change, marked unchanged.",
            "default": false
          },
          "resetMonitor": {
            "title": "Reset the monitor",
            "type": "boolean",
            "description": "Forget the monitor's memory and start over (every wine is new again).",
            "default": false
          },
          "proxyConfiguration": {
            "title": "Proxy",
            "type": "object",
            "description": "Optional. The actor picks its connection itself: the platform's own address for the US market and for market-free data, Apify residential in the market's country for every other market. A proxy set here is tried first."
          }
        }
      },
      "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
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}