# Vivino Scraper (`solidcode/vivino-scraper`) Actor

\[💰 $1.80 / 1K] Extract structured wine data from Vivino: name, winery, vintage, region, grapes, community ratings with counts, price, taste profile, food pairings, and optional reviews. Search by keyword or paste wine URLs. 23 countries, 15 currencies.

- **URL**: https://apify.com/solidcode/vivino-scraper.md
- **Developed by:** [SolidCode](https://apify.com/solidcode) (community)
- **Categories:** E-commerce, Other
- **Stats:** 11 total users, 0 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $1.80 / 1,000 results

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.
Since this Actor supports Apify Store discounts, the price gets lower the higher subscription plan you have.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

Actors are web data automations that power AI and operations. They run on the Apify platform to scrape websites, process data, connect APIs, and automate workflows.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.
Actors are written with capital "A".

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.
The best way to integrate Actors is as follows.

- **AI agents and MCP clients** — the [Apify MCP server](https://docs.apify.com/integrations/mcp.md) at `https://mcp.apify.com` (remote, streamable HTTP, OAuth on first use).
- **Agentic workflows and local Actor development** — [Agent Skills](https://apify.com/.well-known/agent-skills/index.json) with the [Apify CLI](https://docs.apify.com/cli/docs.md): `npm install -g apify-cli`, then `apify login`.
- **JavaScript/TypeScript projects** — the official [JS/TS client](https://docs.apify.com/api/client/js/docs.md): `npm install apify-client`.
- **Python projects** — the official [Python client](https://docs.apify.com/api/client/python/docs.md): `pip install apify-client`.
- **Any other language** — the [REST API](https://docs.apify.com/api/v2.md).

For usage examples, see the [API](#api) section below.

For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt).

# README

## Vivino Scraper

Pull structured wine data from Vivino at scale — winery, vintage, region, grape varieties, community ratings with the rating counts behind them, market prices, taste-profile scores, food pairings, and opt-in reviews. Search by wine name or paste Vivino URLs directly, and localize prices across 23 countries and 15 currencies. Built for wine retailers, sommeliers, market researchers, and catalog teams who need clean, comparable wine data without copying it bottle by bottle from Vivino.

### Why This Scraper?

- **Know whether a rating is really that vintage's own** — the `ratingIsWineLevel` field separates three cases no other Vivino extractor exposes: the vintage's own score, the wine's overall score standing in, and a bottle rated too few times for Vivino to publish any score. About two rows in five carry the flag, so filtering on it changes your sample materially.
- **Invented vintages are filtered out** — Vivino's index lists release years a producer never actually bottled, each wearing a copied rating. Removing them cut phantom rows on an all-vintages sweep from 82% to 0% and lifted price coverage on that same sweep from 18% to 70%.
- **Alcohol content on nearly nine bottles in ten** — ABV lands on 88.9% of wines measured across 1,527 rows, alongside region and country on 100% and grape varieties on 95%.
- **Non-vintage wines are labelled, not left blank** — a Champagne, Cava, or NV blend returns the literal `"N.V."` in `vintage` (58% of rows on a Champagne run), so "no year exists" is never confused with "the year failed to read".
- **Paste back any URL the scraper produced and get a full record** — Vivino serves a wine page in three different shapes and all three resolve to a complete detail parse, taking the output-to-input round trip from 15% to 100% of URLs.
- **Up to 100 community reviews per wine** — reviewer username, their own rating, the full comment text, and the review date, each emitted as its own row for easy analysis.
- **Localized pricing across 23 countries and 15 currencies** — quote in USD, GBP, EUR, CHF, AUD, JPY, and more to match the market you actually sell into.
- **Sweep every vintage of a wine, or pin to one exact year** — "Ignore vintage" returns all release years for price-over-time work; "Match exact vintage" locks to the year you typed and holds it on 100% of returned rows.
- **Taste-profile scores plus the community's dominant flavor notes** — body, acidity, tannins, sweetness, and fizziness on the axes Vivino measures for that wine type, with flavor-note groups ranked by how strongly tasters called them.

### Use Cases

**Wine Retail & Pricing**

- Monitor competitor and market pricing on the same wine across countries
- Track a vintage's price as it moves from current release to back-vintage
- Spot under-rated, well-priced bottles by comparing rating to price
- Validate landed costs against local market currency before importing

**Restaurants & Sommeliers**

- Build a by-the-glass and bottle list ranked by community rating
- Match wines to menu courses using the food-pairing fields
- Surface crowd-pleasers with high ratings *and* high rating counts
- Find structurally similar alternatives using body, acidity, and tannin scores

**Market Research & Trends**

- Track how a region or grape variety is rated across thousands of wines
- Benchmark a producer's portfolio against its peers
- Analyze taste-profile trends by region, country, or vintage year
- Quantify community sentiment from review text and ratings

**App & Catalog Building**

- Enrich an e-commerce wine catalog with ratings, images, and tasting notes
- Power a wine-recommendation engine with taste-profile vectors
- Populate a wine app with structured pairings, grapes, and ABV
- Fill gaps in a product database using direct Vivino URL lookups

### Getting Started

#### Search by Wine Name

The simplest run — one query, full taste profile on by default:

```json
{
    "searchQueries": ["Barolo"],
    "maxResults": 50
}
```

#### Track Every Vintage of a Wine

Strip the vintage to gather all release years of a single wine, priced in euros:

```json
{
    "searchQueries": ["Tignanello"],
    "vintageHandling": "name_only",
    "countryCode": "FR",
    "currencyCode": "EUR",
    "maxResults": 100
}
```

#### Pull a Wine With Community Reviews

Look up specific bottles by URL and collect up to 25 reviews each:

```json
{
    "startUrls": [
        "https://www.vivino.com/en/tignanello/w/1652"
    ],
    "includeReviews": true,
    "maxReviewsPerWine": 25
}
```

#### Full-Featured Example

Mix queries and URLs, exact vintage matching, reviews on, localized to the UK:

```json
{
    "searchQueries": ["Penfolds Grange 2017", "Napa Cabernet Sauvignon"],
    "startUrls": [
        "https://www.vivino.com/en/grange/w/1136930"
    ],
    "vintageHandling": "name_and_vintage",
    "includeTasteProfile": true,
    "includeReviews": true,
    "maxReviewsPerWine": 50,
    "countryCode": "GB",
    "currencyCode": "GBP",
    "maxResults": 200
}
```

### Input Reference

#### What to Scrape

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `searchQueries` | string\[] | `["Tignanello 2019"]` | Wine names or keywords to search on Vivino (e.g. "Barolo", "Penfolds Grange"). Include the vintage year or leave it out. Each query runs independently. |
| `startUrls` | string\[] | `[]` | Paste Vivino wine URLs directly. Each URL is fetched as a single wine. |

#### Results

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `maxResults` | integer | `100` | Maximum number of **wines** to return across all queries and URLs. Set to `0` for unlimited. Start with 10–50 to test, then increase. This caps wines only — when reviews are on, each wine adds up to `maxReviewsPerWine` review rows on top of this number. |
| `vintageHandling` | select | `Smart (detect year automatically)` | How vintage years are matched: detect a year in your query automatically, match the exact year you typed, or ignore the year and return every vintage of the wine. |

#### Detail

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `includeTasteProfile` | boolean | `true` | Collect the taste profile — body, acidity, tannins, sweetness, fizziness, dominant flavor notes, and food pairings. |

#### Reviews

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `includeReviews` | boolean | `false` | Also collect user reviews. Each review is its own result row, added on top of the `maxResults` wine count, so total results grow with the number of reviews collected. |
| `maxReviewsPerWine` | integer | `10` | Maximum reviews to collect per wine (across all of its vintages) when reviews are on. Up to `100`. Ignored when reviews are off. |

#### Localization

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `countryCode` | select | `United States` | Country market used for pricing and availability. 23 countries supported. |
| `currencyCode` | select | `US Dollar` | Currency for wine prices (ISO 4217). 15 currencies supported. |

### Output

Every row carries a `recordType` field — `wine` or `review` — so you can filter cleanly downstream.

#### Wine (`recordType: "wine"`)

```json
{
    "recordType": "wine",
    "wineId": "1652",
    "vintageId": "159365358",
    "name": "Tignanello",
    "url": "https://www.vivino.com/en/tignanello/w/1652",
    "winery": "Antinori",
    "vintage": "2019",
    "wineType": "Red",
    "region": "Toscana",
    "country": "Italy",
    "grapes": ["Sangiovese", "Cabernet Sauvignon", "Cabernet Franc"],
    "averageRating": 4.6,
    "ratingsCount": 8567,
    "ratingIsWineLevel": false,
    "price": 159.99,
    "currency": "USD",
    "imageUrl": "https://images.vivino.com/thumbs/example.png",
    "foodPairings": ["Beef", "Lamb", "Game (deer, venison)"],
    "description": "A Tuscan icon blending Sangiovese with Bordeaux varieties.",
    "alcoholContent": 13.5,
    "body": 4.2,
    "acidity": 3.1,
    "tannins": 3.8,
    "sweetness": 1.4,
    "fizziness": null,
    "flavorNotes": [
        { "group": "oak", "score": 34699, "count": 240 },
        { "group": "red_fruit", "score": 29551, "count": 209 }
    ],
    "inputSource": "search",
    "searchQuery": "Tignanello 2019",
    "scrapedAt": "2026-08-25T14:30:00Z"
}
```

##### Core Fields

| Field | Type | Description |
|-------|------|-------------|
| `recordType` | string | Always `"wine"` |
| `wineId` | string | Vivino wine identifier |
| `vintageId` | string | Vivino vintage identifier — the rated, priced bottle |
| `name` | string | Wine name |
| `url` | string | Canonical Vivino wine URL. Paste it straight back into `startUrls` for a full re-fetch |
| `winery` | string | Winery / producer name |
| `vintage` | string | Vintage year, or the literal `"N.V."` for non-vintage wines. Always filled |
| `wineType` | string | Red, White, Rosé, Sparkling, Dessert, or Fortified |
| `region` | string | Wine region |
| `country` | string | Country of origin |
| `grapes` | string\[] | Grape varieties in the blend |
| `imageUrl` | string | Bottle / label image |
| `description` | string | Wine description and tasting note, when Vivino has one — roughly half of wines carry one |
| `alcoholContent` | number | Alcohol by volume (ABV %), filled on about nine wines in ten |
| `inputSource` | string | `search` or `url` — how this row was found |
| `searchQuery` | string | The query or URL that produced this row |
| `scrapedAt` | string | ISO timestamp of extraction |

##### Ratings & Pricing

| Field | Type | Description |
|-------|------|-------------|
| `averageRating` | number | Community average rating, 1–5. Empty when Vivino has too few ratings on the bottle to publish a score — never `0`, because `0` is not a rating anyone gave |
| `ratingsCount` | integer | Number of community ratings behind the average. Always filled, including when `averageRating` is empty — that is the "rated 20 times, no score published yet" case |
| `ratingIsWineLevel` | boolean | `false` when the score belongs to this exact vintage. `true` when it does not — either the wine's overall score is standing in, or Vivino has published no score at either level yet, in which case `averageRating` is empty while `ratingsCount` still shows how many people rated the bottle |
| `price` | number | Price in the selected currency, when Vivino lists a merchant offer. Back-vintages and rare bottles frequently have none |
| `currency` | string | Currency code (ISO 4217) |
| `foodPairings` | string\[] | Vivino's suggested food pairings |

##### Taste Profile

Populated when `includeTasteProfile` is on. Vivino measures different axes for different wine types — tannins on reds, fizziness on sparkling — so a still wine returns no fizziness score and a sparkling wine returns no tannin score.

| Field | Type | Description |
|-------|------|-------------|
| `body` | number | Light-to-full body score |
| `acidity` | number | Soft-to-acidic score |
| `tannins` | number | Smooth-to-tannic score (red wines) |
| `sweetness` | number | Dry-to-sweet score |
| `fizziness` | number | Still-to-fizzy score (sparkling wines) |
| `flavorNotes` | object\[] | Dominant flavor-note groups, each with a `group` name, a `score` (how strongly the community tasted it), and a `count` (mentions behind it) |

#### Review (`recordType: "review"`)

Emitted only when `includeReviews: true`. Capped at `maxReviewsPerWine` per wine.

```json
{
    "recordType": "review",
    "wineId": "1652",
    "vintageId": "159365358",
    "wineUrl": "https://www.vivino.com/en/tignanello/w/1652",
    "username": "winelover_42",
    "rating": 4.5,
    "comment": "Silky tannins, dark cherry, and a long finish. Worth the splurge.",
    "date": "2026-03-18T09:12:00Z"
}
```

| Field | Type | Description |
|-------|------|-------------|
| `recordType` | string | Always `"review"` |
| `wineId` | string | Parent wine identifier |
| `vintageId` | string | Parent vintage identifier |
| `wineUrl` | string | Parent wine URL |
| `username` | string | Reviewer's Vivino username |
| `rating` | number | Reviewer's own rating (0–5) |
| `comment` | string | Full review text |
| `date` | string | Review date |

### Tips for Best Results

- **Strip the vintage to track a wine across release years.** Set `vintageHandling` to "Ignore vintage" and you get every year of a wine — ideal for charting how a label's price moves from current release to back vintage. Release years the producer never actually bottled are removed for you, so the price curve you plot is built from bottles that exist.
- **"Match exact vintage" returns fewer wines by design.** Pinning a query to one year narrows the pool hard: "Sassicaia 2019" returns 44 wines on that year versus 396 across all years. If you set `maxResults` to 100 and get 44, that's the full set for that vintage, and the run tells you so when it finishes. Use "Ignore vintage" when you want volume rather than precision.
- **Weight ratings by their count, and treat an empty rating as "no score yet".** A 4.6 from 50,000 tasters is a far stronger signal than a 4.6 from 8, so sort on `ratingsCount` alongside `averageRating`. Vivino withholds an average entirely until a bottle clears its threshold, so newer and rarer releases arrive with `averageRating` empty and `ratingsCount` still filled — filter on `averageRating` being present before you rank, or you will bury bottles that simply have not been scored.
- **Filter on `ratingIsWineLevel` when the vintage year matters.** About **two rows in five** (39.7%, measured over 1,527 rows) carry `true`, meaning the score is not that exact vintage's own — far more than a spot check suggests, and it runs from 15% on a Champagne search to 64% on a single-winery catalog sweep. Roughly a third of those flagged rows have no published score at all rather than a substituted one. Keep `ratingIsWineLevel: false` for a strict vintage-by-vintage comparison; if you keep the flagged rows too, check `averageRating` is present before you rank on it.
- **Expect thinner detail on rare back-vintages.** Tasting notes, food pairings, taste scores, and prices all come from Vivino's community and merchant network, so a flagship current release is richly described while an obscure single-barrel bottling from decades ago may carry only name, winery, region, and vintage. Food pairings land on 96.5% of wines across broad varietal searches but nearer three in four on a deep single-winery sweep. Plan for it rather than treating an empty field as an error.
- **Reviews add on top of your `maxResults` cap.** `maxResults` limits the number of *wines*; it does not bound reviews. Each review is a separate billable row added on top, capped at `maxReviewsPerWine` per wine (across its vintages). So a 50-wine run with `maxReviewsPerWine: 100` can return up to 50 wines + 5,000 reviews. Reviews are off by default — turn them on deliberately and set `maxReviewsPerWine` to keep result counts predictable.
- **Set currency and country to your real market.** `currencyCode` controls the price currency and `countryCode` localizes availability — match both to the market you sell into so the prices you see are the prices your customers see.
- **Mix names and URLs in one run, and start small.** Combine a list of search terms with a list of specific Vivino URLs to cover broad discovery and exact lookups in a single pass. Run 10–50 results first to confirm the wines and fields match what you expect, then raise `maxResults` (or set it to `0` for unlimited).

### Pricing

**From $1.80 per 1,000 results** — and it gets cheaper as your Apify discount tier goes up.

| Results | No discount | Bronze | Silver | Gold |
|---------|-------------|--------|--------|------|
| 100 | $0.21 | $0.20 | $0.19 | $0.18 |
| 1,000 | $2.15 | $2.05 | $1.90 | $1.80 |
| 10,000 | $21.50 | $20.50 | $19.00 | $18.00 |
| 100,000 | $215.00 | $205.00 | $190.00 | $180.00 |

Tiered pricing takes effect on **9 September 2026**. Until that date every result is billed at a flat **$1.80 per 1,000**, the rate shown in the Gold column.

A "result" is any row in the output dataset — a wine or a single review. **No compute charges — you only pay per result returned.** Reviews are off by default; turning them on adds one billable row per review collected.

### Integrations

Export data in JSON, CSV, Excel, XML, or RSS. Connect to 1,500+ apps via:

- **Zapier** / **Make** / **n8n** — Workflow automation
- **Google Sheets** — Direct spreadsheet export
- **Slack** / **Email** — Notifications on new results
- **Webhooks** — Trigger custom APIs on run completion
- **Apify API** — Full programmatic access

### Legal & Ethical Use

This actor is designed for legitimate wine retail research, market analysis, catalog enrichment, and product discovery. Users are responsible for complying with applicable laws and Vivino's terms of service, including making reasonable-rate requests and respecting content usage rules. Review text and usernames are user-generated content — handle any personal data responsibly and in line with applicable privacy regulations. Do not use extracted data for spam, harassment, or any illegal purpose.

# Actor input Schema

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

Wine names or keywords to search on Vivino (e.g. 'Tignanello 2019', 'Barolo', or 'Penfolds Grange'). You can include the vintage year or leave it out. Each query runs independently. Leave empty if you only want to scrape specific URLs below.

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

Paste Vivino wine URLs directly (e.g. 'https://www.vivino.com/wineries/.../wines/...' or 'https://www.vivino.com/.../w/123456'). Each URL is fetched as a single wine.

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

Maximum number of WINES to return across all queries and URLs. Set to 0 for unlimited (up to the site's own limits). Note: this caps wines only — if Include User Reviews is on, each wine can add up to 'Maximum Reviews per Wine' review rows on top of this number. Tip: start with 10-50 to test, then increase.

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

How to handle the vintage year when searching by name. 'Smart' detects a year in your query automatically. 'Match exact vintage' only returns the exact year you typed. 'Ignore vintage' returns the wine regardless of year (uses the latest or most-rated vintage).

## `includeTasteProfile` (type: `boolean`):

Also collect the wine's taste profile: body, acidity, tannins, sweetness, fizziness, dominant flavor notes, and food pairings. On by default.

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

Also collect user reviews for each wine. Off by default. When on, each review is returned as its own result, so the total result count grows with the number of reviews. Use the cap below to keep this predictable.

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

When Include User Reviews is on, the maximum number of reviews to collect per wine (across all of its vintages). For example, 100 means at most 100 reviews for any single wine, no matter how many vintages it has. Each review is returned as its own result and counts toward your results. Ignored when reviews are off.

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

Country market used for pricing and availability. Use the country your prices should reflect. Currency (below) always applies; country-level localization depends on regional availability and may fall back to the nearest market for some wines.

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

Currency for wine prices (ISO 4217).

## `debugConnection` (type: `boolean`):

Internal diagnostics switch. Leave off.

## Actor input object example

```json
{
  "searchQueries": [
    "Tignanello 2019"
  ],
  "startUrls": [],
  "maxResults": 100,
  "vintageHandling": "auto",
  "includeTasteProfile": true,
  "includeReviews": false,
  "maxReviewsPerWine": 10,
  "countryCode": "US",
  "currencyCode": "USD"
}
```

# Actor output Schema

## `overview` (type: `string`):

Table of scraped wines with key fields.

# 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 = {
    "searchQueries": [
        "Tignanello 2019"
    ],
    "startUrls": [],
    "maxResults": 100,
    "vintageHandling": "auto",
    "includeTasteProfile": true,
    "includeReviews": false,
    "maxReviewsPerWine": 10,
    "countryCode": "US",
    "currencyCode": "USD"
};

// Run the Actor and wait for it to finish
const run = await client.actor("solidcode/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 = {
    "searchQueries": ["Tignanello 2019"],
    "startUrls": [],
    "maxResults": 100,
    "vintageHandling": "auto",
    "includeTasteProfile": True,
    "includeReviews": False,
    "maxReviewsPerWine": 10,
    "countryCode": "US",
    "currencyCode": "USD",
}

# Run the Actor and wait for it to finish
run = client.actor("solidcode/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 '{
  "searchQueries": [
    "Tignanello 2019"
  ],
  "startUrls": [],
  "maxResults": 100,
  "vintageHandling": "auto",
  "includeTasteProfile": true,
  "includeReviews": false,
  "maxReviewsPerWine": 10,
  "countryCode": "US",
  "currencyCode": "USD"
}' |
apify call solidcode/vivino-scraper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,solidcode/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/hgpqpO3ZZHviUWbtB/builds/T6g3PBO05VkzeFb52/openapi.json