# Vivino Scraper - Wine Prices, Ratings, Reviews & Taste Profiles (`topapi/vivino-scraper`) Actor

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.

- **URL**: https://apify.com/topapi/vivino-scraper.md
- **Developed by:** [Top Api](https://apify.com/topapi) (community)
- **Categories:** E-commerce, Business, Other
- **Features:** Limited permissions
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $0.90 / 1,000 wines

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/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes.
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.

Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md.

## 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.

Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run.

For examples already wired to this Actor's own input schema, see the [API](#api) section below.

Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`).

# README

### What does Vivino Scraper do?

**Vivino Scraper** extracts wine data from [Vivino](https://www.vivino.com), the wine rating app and marketplace: one row per wine vintage with the **shop price in the market you choose**, the community rating and the number of ratings behind it, region, country, grapes, style, taste profile, flavour notes, food pairings, critic scores, rankings and drinking window. Wine retailers, importers, sommeliers, price-comparison sites and market researchers use it to price, compare and enrich wine catalogues.

- 🔎 **Every way in:** search terms, a list of wine names to match (one best match each), Vivino links (wine, vintage, winery, Explore, search, grape, region, style, country pages), wine IDs, vintage IDs, wineries, or Explore filters (type, country, region, grape, style, food, rating, number of ratings, price, year, discounts, natural wines).
- 💶 **Prices by market:** 28 shop markets (US, UK, France, Germany, Italy, Switzerland, Canada, Australia, Japan...), several markets in one run to compare, any currency.
- 🏪 **Every shop offer** of a wine in the market (shop, price, bottle size, stock), Vivino's median market price, discounts.
- 🍷 **Taste and details:** body, acidity, tannins, sweetness, fizziness, flavour groups, alcohol, residual sugar, closure, allergens, winemaker, grape shares, critic scores, awards, global / country / region / winery rank, drinking window.
- 💬 **Reviews:** community reviews per wine (helpful or newest, by language, by stars, by vintage) as rows or nested.
- 🔁 **Monitor mode:** scheduled runs return only new wines, price drops / rises and rating moves, and new reviews.
- ✅ No login, no cookies, no API key. Plain HTTP on Vivino's own JSON, fast and cheap.

### What data can you get from Vivino?

| | | |
|---|---|---|
| 🍷 Wine, winery, vintage (`fullName`, `winery`, `vintage`) | 💲 Shop price + currency (`price`, `currency`) | ⭐ Rating + ratings count (`averageRating`, `ratingsCount`) |
| 🗺️ Region, country (`region`, `country`) | 🏷️ Style, grapes (`style`, `grapes`) | 🧪 Body, acidity, tannins, sweetness |
| 👅 Flavour notes (`flavorNotes`) | 🍽️ Food pairings (`foodPairings`) | 📊 Median market price (`medianPrice`) |
| 🏪 Every shop offer (`offers`) | 🔻 Discounts (`discountedFrom`, `discountPercent`) | 🥇 Critic scores, awards (`criticScores`, `awards`) |
| 🏆 Global / country / region rank | 🗓️ Drinking window | 🍾 Alcohol, sugar, closure, allergens |
| 🧬 Grape shares (`grapeComposition`) | 📈 Top-list ranks (`topListRankings`) | 🔁 Monitor changes (`changeType`, `previousPrice`) |
| 💬 Review text + stars (`comment`, `rating`) | 👤 Taster name + counts (`username`, `userRatingsCount`) | 🔗 Wine, winery, review links |

### How to scrape Vivino with Vivino Scraper

1. [Create a free Apify account](https://console.apify.com/sign-up) (it comes with monthly free credit).
2. Open **Vivino Scraper** and choose what to scrape: search terms, wine names, links, IDs, wineries or Explore filters.
3. Pick the **market** whose shop prices you want (and a currency if you want another one).
4. Switch on what you need: details, every shop offer, highlights, reviews.
5. Click **Start**. A 20-wine run takes about 3 seconds.
6. Download the results as JSON, CSV, Excel or HTML, or read them through the API.

### Input

| Parameter | Type | What it does |
|---|---|---|
| `mode` | select | `wines` (default) = one row per vintage; `reviews` = only the reviews of every wine found |
| `searchQueries` | list | Search terms (wine, winery, grape, region). Every matching vintage on sale in the market |
| `wines` | list | Your own list: names (`Opus One 2018`), links or wine IDs. One best match per line, with `matchScore` |
| `startUrls` | links | Wine, vintage, winery, Explore, search, grape, region, style or country links (file upload too) |
| `wineIds` / `vintageIds` | list | Vivino wine IDs (`/w/1652`) / vintage IDs (`/wines/159365358`) |
| `wineries` | list | Winery names, IDs or links: the winery's whole catalogue |
| `urlsFromFile` | text | Links and IDs pasted, or one link to a .txt / .csv file or public Google Sheet |
| `wineTypes`, `countries`, `regions`, `grapes`, `wineStyles`, `foods` | lists | Explore filters (names or Vivino IDs). Also narrow search terms |
| `minRating`, `maxRating`, `minRatingsCount`, `priceMin`, `priceMax`, `vintageYears` | numbers | Explore filters, applied by Vivino before anything is charged |
| `discountedOnly`, `naturalOnly`, `sortBy` | | Discounted / natural wines only; Vivino's order (most rated, highest rated, price, discount, best picks) |
| `countryCode` (default `US`) / `markets` / `currencyCode` | | Shop market, up to 10 markets per run, currency |
| `includeTasteProfile` (on), `includeWineDetails` (on), `includeMedianPrice` (on) | switches | Taste, details, median price: no extra charge |
| `includeAllOffers`, `includeHighlights`, `includeRatingsDistribution`, `includeVintageList`, `includeStyleInfo`, `includeAllVintages` | switches | Shop offers, highlights + critic names, star split, vintage list column, style texts, one row per vintage year (`vintageStartYear`) |
| `includeReviews`, `maxReviewsPerWine`, `reviewsSort`, `reviewsLanguage`, `reviewStars`, `reviewMinRating`, `reviewsForVintageOnly`, `reviewsNewerThan`, `reviewsOutput` | | Reviews: how many, order, language, stars, year, date, rows or nested |
| `vintageHandling`, `matchingMode`, `searchAllWines` | | How a year in a name is used; best match or + runner-up; also search Vivino's full wine index |
| `maxResults` (default 25), `maxResultsPerSearch`, `deduplicateWines`, `maxConcurrency` | | Limits |
| `monitorMode`, `monitorKey`, `monitorStoreName`, `monitorChanges`, `emitUnchanged`, `resetMonitor` | | Monitor (scheduled runs) |
| `proxyConfiguration` | proxy | Optional; the actor picks its own connection per market |

#### Input JSON

```json
{
    "searchQueries": ["Barolo", "Tignanello 2019"],
    "wines": ["Opus One 2018", "Dom Perignon"],
    "countryCode": "GB",
    "currencyCode": "GBP",
    "minRating": 4,
    "maxResults": 100,
    "includeAllOffers": true,
    "includeReviews": true,
    "maxReviewsPerWine": 10
}
```

#### Search terms or wine names?

`searchQueries` returns every vintage Vivino's search finds on sale in the market (Barolo returns hundreds). `wines` returns one row per line: the best match for that name (the most-rated bottle on sale when no year is given, that vintage when a year is given). Use `wines` to match your own product list to Vivino, `searchQueries` to discover.

#### Pick the market before anything else

Vivino shows each visitor the shops, prices and availability of the country they browse from, so the same wine has a different price, or none, per market. The US market is read from the platform's own address (Vivino serves its Virginia shops); every other market is read through Apify's residential proxy in that country, included in the price. Explore and search list only wines on sale in the market; a name that is not on sale anywhere in the market is looked up in Vivino's full wine index and delivered without a price (`priceStatus: no_offer`).

#### More than 2,000 wines from one filter set

Vivino's Explore serves about 2,000 wines per query. Ask for more (`maxResults` 5,000) and the actor splits the query into price bands by itself and reads each band, without duplicates. Runs are capped at 256 MB of memory, so 5,000 wines take about 6 minutes (343-358 s measured).

### Output

One row per wine vintage (`recordType: "wine"`) or review (`recordType: "review"`). A wine row from a real run (Tignanello 2019 by link, US market; shown with its first critic score and first flavour group; the full row has 101 fields):

```json
{
    "recordType": "wine",
    "wineId": 1652,
    "vintageId": 159365358,
    "fullName": "Antinori Tignanello 2019",
    "url": "https://www.vivino.com/antinori-tuscany-tignanello/w/1652?year=2019",
    "winery": "Antinori",
    "vintage": "2019",
    "wineType": "Red",
    "region": "Toscana",
    "country": "Italy",
    "style": "Tuscan Red",
    "grapes": ["Sangiovese", "Cabernet Sauvignon", "Cabernet Franc"],
    "averageRating": 4.6,
    "ratingsCount": 8685,
    "ratingIsWineLevel": false,
    "price": 178.81,
    "currency": "USD",
    "medianPrice": null,
    "market": "US",
    "marketState": "Virginia",
    "body": 3.44,
    "acidity": 3.09,
    "tannins": 3,
    "sweetness": 1.72,
    "foodPairings": ["Beef", "Lamb", "Veal", "Poultry", "Cured Meat"],
    "alcoholContent": 14,
    "criticScores": [{"criticId": 13, "critic": null, "score": "95", "scoreNormalized": 95, "reviewedAt": "2022-06-15T00:00:00Z", "criticReviewId": 3532774}],
    "rankGlobal": 2722,
    "drinkingWindowFrom": 2024,
    "drinkingWindowTo": 2034,
    "offersCount": 10,
    "inputSource": "url",
    "scrapedAt": "2026-11-06T12:54:31.937Z",
    "flavorNotes": [{"group": "oak", "score": 736469, "count": 5374, "keywords": ["oak", "tobacco", "chocolate", "vanilla", "cedar", "coffee"]}]
}
```

A review row:

```json
{
    "recordType": "review",
    "reviewId": 359461132,
    "wineId": 1652,
    "vintage": "2019",
    "wineName": "Tignanello",
    "winery": "Antinori",
    "rating": 4.6,
    "comment": "Lovely nose with aromas of dark red fruits, licorice, spicy, coffee, tobacco leafs, pepper notes rich fruity palate, fine ripe tannins and good acid structure, dark chocolate, juicy aftertaste 96 DSP",
    "language": "en",
    "date": "2026-06-30T22:22:38.000Z",
    "likesCount": 56,
    "username": "dick.sc",
    "userRatingsCount": 8559,
    "reviewUrl": "https://www.vivino.com/users/dick.sc/activities/936791235",
    "reviewScope": "2019"
}
```

#### Fields

Fill from a real 1,000-row run (red wines, US market, defaults) and a 200-review run:

| Field | Meaning | Filled |
|---|---|---:|
| `wineId`, `vintageId`, `name`, `fullName`, `url`, `winery`, `vintage`, `wineType`, `region`, `country` | Identity of the vintage | 100% |
| `price`, `currency`, `merchantId`, `bottleVolumeMl` | Featured shop offer in the market | 100% (Explore and search list only wines on sale) |
| `averageRating`, `ratingsCount`, `ratingIsWineLevel` | Community score, its count, and whether it is the vintage's own score | 100% |
| `medianPrice` | Vivino's median price across the market's shops | 100% |
| `grapes` / `style` | Grape varieties / Vivino style | 98% / 99% |
| `body`, `acidity`, `tannins`, `sweetness`, `flavorNotes` | Taste profile (fizziness on sparkling wines) | 99-100% |
| `foodPairings` | Vivino's pairings | 99% |
| `alcoholContent` | ABV | 99% |
| `rankGlobal`, `rankCountry`, `rankRegion`, `rankWinery` | Vivino ranks with their totals | 96% |
| `drinkingWindowFrom` / `To` | Recommended drinking window | 95% |
| `description` | Wine / vintage description | 71% |
| `closure` | Cork, screw cap... | 45% |
| `grapeComposition` | Grape shares, % | 27% |
| `criticScores`, `criticScoreTop` | Critic scores (0-100), critic named with highlights | 13% |
| `winemaker` | Winemaker | 10% |
| `topListRankings` | Vivino top lists the vintage is on | 5% |
| `offers`, `offersCount` | Every shop offer (Include every shop offer) | 100% when on |
| `ratingsDistribution` | Ratings per star (Include the star distribution) | 100% when on |
| `comment`, `rating`, `language`, `date`, `likesCount`, `username`, `userRatingsCount`, `reviewUrl` | Review rows | 100% |

The full list of 140 fields, with types, is in the **Output** tab's dataset schema.

### How can I use Vivino data?

- 🛒 **Wine retailers:** price your range against the market's shops and median price, by country.
- 📦 **Importers and distributors:** find well-rated wines by region, grape and price band that sell in a market.
- 🍽️ **Restaurants and sommeliers:** build lists by rating, food pairing and taste profile.
- 📊 **Market research:** ratings and prices by region, grape, style or vintage; critic scores and ranks.
- 🔁 **Price monitoring:** scheduled runs flag price drops, rises and rating moves.
- 💬 **Sentiment analysis:** review text, stars and language for any wine or vintage.
- 🧩 **Catalogue enrichment:** match your product names to Vivino (`wines`) and add ratings, images and tasting data.

### How much does it cost to scrape Vivino?

Vivino Scraper is pay-per-result, no start fee, Apify platform usage included (residential proxy for non-US markets too).

| Row | Price | 100 rows | 1,000 rows | 10,000 rows |
|---|---:|---:|---:|---:|
| Wine (`wine`) | $0.0009 | $0.09 | $0.90 | $9.00 |
| Review (`review`) | $0.00009 | $0.009 | $0.09 | $0.90 |

Details, median price, every shop offer, highlights, star split, vintage list and taste profile are free inside the wine row. Duplicates, unchanged monitor wines and anything your filters remove are never charged. Set a **maximum cost per run** in the run options and the run stops cleanly at it.

### Integrations, API, scheduling & MCP

- **Schedules:** run it daily or hourly from the **Schedules** tab; with **Monitor mode** each run returns only new wines, price and rating changes and new reviews, and a run with nothing new charges nothing.
- **No-code:** Make, Zapier, n8n, Google Sheets, Airtable, Slack via [Apify integrations](https://docs.apify.com/integrations), and webhooks on run finish.
- **API:** `apify-client` for [Node.js](https://apify.com/topapi/vivino-scraper/api/javascript) or [Python](https://apify.com/topapi/vivino-scraper/api/python); the [Apify API reference](https://docs.apify.com/api/v2).
- **MCP / AI agents:** connect Claude, Cursor or any MCP client through the [MCP tab](https://apify.com/topapi/vivino-scraper/api/mcp) and ask for wines by food, budget or region.

### More TopApi scrapers

<table>
<tr>
<td>🛒 <a href="https://apify.com/topapi/walmart-scraper">Walmart Scraper</a>: products, prices, reviews and sellers</td>
<td>⭐ <a href="https://apify.com/topapi/trustpilot-reviews-scraper">Trustpilot Reviews Scraper</a>: company reviews</td>
<td>🍽️ <a href="https://apify.com/topapi/yelp-reviews-scraper">Yelp Reviews Scraper</a>: ratings, owner replies and photos</td>
</tr>
<tr>
<td>🧭 <a href="https://apify.com/topapi">All TopApi actors</a></td>
<td></td>
<td></td>
</tr>
</table>

### Limits & empty runs

- Explore and search list wines **on sale in the market** (measured: about 82,000 red wines in the US market); about 2,000 per query, more through automatic price bands.
- US prices are those Vivino shows to a Virginia visitor; Vivino picks the state from the visitor's address and no other state can be chosen.
- `price` is the featured offer of that exact vintage. When the asked vintage is not on sale, its row has no price; the all-vintages row of a wine quotes the vintage on sale (`priceVintageYear`), and the offers of a vintage not on sale are those of the vintage Vivino sells (`sameVintage: false`).
- Reviews of one vintage are only that year's reviews (Vivino pads thin years with other years; those are left out).
- A run with nothing to deliver ends with a status that says why (no match, filters too tight, name not found) and charges nothing.

### FAQ

#### How much does Vivino Scraper cost?

$0.90 per 1,000 wines and $0.09 per 1,000 reviews, no start fee. Details, offers, median price and taste profile ride on the wine row at no extra cost.

#### How many wines can Vivino Scraper collect in one run?

As many as the market lists for your filters: about 2,000 per query, and more through automatic price bands (5,000 measured in one run). 1,000 wines take 10-40 seconds.

#### Can Vivino Scraper compare prices between countries?

Yes. Put up to 10 market codes in `markets` (US, GB, FR, DE, CH...) and a `currencyCode` to see every market in one currency; each row carries its `market`.

#### Can I run Vivino Scraper on a schedule to get only price changes?

Yes. Turn on **Monitor mode** and schedule the run: each run returns new wines and wines whose price or rating moved, with `changeType`, `previousPrice` and `priceChangePercent`. Known, unchanged wines are not delivered and not charged. A known wine delivered before without an add-on the run now asks for (details, median price, offers, highlights, star split, vintage list, taste profile or style texts) comes back once with it, as `changeType` `details`, and is charged as a wine row.

#### Can Vivino Scraper match my own list of wine names?

Yes. Put the names in `wines`, one per line, with or without a year. Each line returns its best match with a `matchScore` (share of your words found); **Advanced matching** adds the runner-up.

#### Can Vivino Scraper get every vintage of a wine?

Yes. Give the wine link or ID and turn on **Include all vintages**: one row per vintage year with ratings (from `vintageStartYear` if set), each with its price in the market when on sale.

#### Can I get all the reviews of a wine with Vivino Scraper?

Yes: `mode: reviews`, `maxReviewsPerWine: 0`. Reviews come 50 a request, most helpful or newest first, filtered by language, stars, year or date.

#### Can I use Vivino Scraper with the Apify API or an MCP server?

Yes. Call it from the API with `apify-client`, from Make / Zapier / n8n, or as a tool from any MCP client through the MCP tab.

#### Do I need a Vivino account, cookies or an API key?

No. Vivino Scraper reads Vivino's public pages' own data; nothing to sign in to.

#### Why did my Vivino Scraper run return no results?

The wine is not on sale in the chosen market (try `searchAllWines`, another market, or the wine's link), the filters are too tight (rating, price, year), or the name did not match. The run's status message says which, and nothing is charged.

#### Your feedback

Found a bug or need a field? Open an issue on the **Issues** tab.

# Actor input Schema

## `mode` (type: `string`):

wines = one row per wine vintage found (default). reviews = only the community reviews of every wine found (no wine rows).

## `searchQueries` (type: `array`):

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).

## `wines` (type: `array`):

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.

## `startUrls` (type: `array`):

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.

## `wineIds` (type: `array`):

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.

## `vintageIds` (type: `array`):

Vivino vintage IDs (the number in a /wines/159365358 link or the vintageId of a row), one per line.

## `wineries` (type: `array`):

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.

## `urlsFromFile` (type: `string`):

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` (type: `array`):

Only these types. Leave empty for every type. Applies to Explore and to search terms.

## `countries` (type: `array`):

Where the wine is made: 2-letter codes (fr, it, us) or names (France, Italy). Not the market you buy in.

## `regions` (type: `array`):

Region names as Vivino names them (Napa Valley, Bordeaux, Barolo, Rioja, Toscana) or region IDs. Sub-regions are included by Vivino.

## `grapes` (type: `array`):

Grape names (Pinot Noir, Nebbiolo, Malbec) or Vivino grape IDs.

## `wineStyles` (type: `array`):

Vivino style names (Californian Pinot Noir, Italian Barolo, Spanish Rioja Red) or style IDs.

## `foods` (type: `array`):

Only wines Vivino pairs with these foods: Beef, Lamb, Pork, Poultry, Pasta, Shellfish, Spicy food, Mature and hard cheese... (names or food IDs).

## `minRating` (type: `number`):

Only wines with at least this Vivino average rating (1 to 5), e.g. 4 or 4.2.

## `maxRating` (type: `number`):

Only wines rated at most this (1 to 5).

## `minRatingsCount` (type: `integer`):

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` (type: `number`):

Per bottle, in the currency below (or the market's own currency).

## `priceMax` (type: `number`):

Per bottle, in the currency below (or the market's own currency).

## `vintageYears` (type: `array`):

Only these vintages, e.g. 2019, 2020.

## `discountedOnly` (type: `boolean`):

Only wines whose featured offer is discounted right now (each row then carries discountedFrom and discountPercent).

## `naturalOnly` (type: `boolean`):

Only wines Vivino lists as natural.

## `sortBy` (type: `string`):

Vivino's own order for Explore and search terms. Max results keeps the first ones in this order.

## `countryCode` (type: `string`):

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).

## `markets` (type: `array`):

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.

## `currencyCode` (type: `string`):

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` (type: `boolean`):

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.

## `includeStyleInfo` (type: `boolean`):

Add the wine style's description, blurb and facts (the same texts on every wine of a style).

## `includeWineDetails` (type: `boolean`):

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).

## `includeMedianPrice` (type: `boolean`):

Vivino's median price across the market's shops next to the featured price (one batched request per 50 wines).

## `includeAllOffers` (type: `boolean`):

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).

## `includeHighlights` (type: `boolean`):

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.

## `includeAllVintages` (type: `boolean`):

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.

## `vintageStartYear` (type: `integer`):

With Include all vintages: only vintages from this year on.

## `includeRatingsDistribution` (type: `boolean`):

Ratings per star (1 to 5) for each vintage. One request per wine.

## `includeVintageList` (type: `boolean`):

Add a vintages column to each row: every vintage of the wine with its year, rating, ratings and reviews count.

## `includeReviews` (type: `boolean`):

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.

## `maxReviewsPerWine` (type: `integer`):

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` (type: `string`):

Most helpful first (Vivino's default) or newest first (best for collecting new reviews on a schedule).

## `reviewsLanguage` (type: `string`):

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` (type: `array`):

Only reviews with these star ratings (2 = 2.0 to 2.9), e.g. 1 and 2 for the critical ones. Empty = every rating.

## `reviewMinRating` (type: `number`):

Only reviews rated at least this (1 to 5).

## `reviewsForVintageOnly` (type: `boolean`):

On: a vintage row gets the reviews of that year. Off: reviews across all vintages of the wine.

## `reviewsNewerThan` (type: `string`):

Only reviews written on or after this date (YYYY-MM-DD).

## `reviewsOutput` (type: `string`):

rows = one row per review (default). nested = the reviews inside their wine row (reviews column); each review is still charged as a review.

## `vintageHandling` (type: `string`):

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.

## `matchingMode` (type: `string`):

basic = the best match per name. advanced = also the runner-up (isAlternative true) when it matches the name well.

## `searchAllWines` (type: `boolean`):

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.

## `maxResults` (type: `integer`):

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.

## `maxResultsPerSearch` (type: `integer`):

Cap per search term, Explore link or filter set. 0 = up to Max results.

## `deduplicateWines` (type: `boolean`):

Deliver each vintage once per run (per market), even when several searches find it.

## `maxConcurrency` (type: `integer`):

Requests in flight at once.

## `monitorMode` (type: `boolean`):

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.

## `monitorKey` (type: `string`):

Names the monitor's memory, so several monitors can run side by side. Empty = derived from the input.

## `monitorStoreName` (type: `string`):

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.

## `monitorChanges` (type: `array`):

Which changes make a known wine come back: price, rating. Empty = both.

## `emitUnchanged` (type: `boolean`):

Monitor mode: also deliver (and pay for) known wines that did not change, marked unchanged.

## `resetMonitor` (type: `boolean`):

Forget the monitor's memory and start over (every wine is new again).

## `proxyConfiguration` (type: `object`):

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.

## Actor input object example

```json
{
  "mode": "wines",
  "wineTypes": [
    "red"
  ],
  "minRating": 4,
  "discountedOnly": false,
  "naturalOnly": false,
  "sortBy": "mostPopular",
  "countryCode": "US",
  "includeTasteProfile": true,
  "includeStyleInfo": false,
  "includeWineDetails": true,
  "includeMedianPrice": true,
  "includeAllOffers": false,
  "includeHighlights": false,
  "includeAllVintages": false,
  "includeRatingsDistribution": false,
  "includeVintageList": false,
  "includeReviews": false,
  "reviewsSort": "helpful",
  "reviewsForVintageOnly": true,
  "reviewsOutput": "rows",
  "vintageHandling": "auto",
  "matchingMode": "basic",
  "searchAllWines": true,
  "maxResults": 20,
  "deduplicateWines": true,
  "maxConcurrency": 8,
  "monitorMode": false,
  "monitorStoreName": "vivino-monitor",
  "emitUnchanged": false,
  "resetMonitor": false
}
```

# Actor output Schema

## `results` (type: `string`):

One item per wine vintage or review (recordType).

## `summary` (type: `string`):

Per-input counts, the market and egress used, inputs that matched nothing, monitor counts. Written for Console runs, runs over 500 rows and runs with a refused request (other runs log it).

# 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 '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "wineTypes": [
        "red"
    ],
    "minRating": 4,
    "maxResults": 20
};

// Run the Actor and wait for it to finish
const run = await client.actor("topapi/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 '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = {
    "wineTypes": ["red"],
    "minRating": 4,
    "maxResults": 20,
}

# Run the Actor and wait for it to finish
run = client.actor("topapi/vivino-scraper").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).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"
  ],
  "minRating": 4,
  "maxResults": 20
}' |
apify call topapi/vivino-scraper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,topapi/vivino-scraper"
        }
    }
}
```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/Rf9KE9hGbwj4yqFSx/builds/SvzdaSZduGqOQQJBh/openapi.json
