# Vivino Wines Scraper — Ratings & Bottle Data (`noahadler/vivino-wines`) Actor

Scrape Vivino wines by name or URL: ratings (0–5), winery, vintage, grapes, region and country. Price and currency when Vivino lists a marketplace price. Optional reviews. HTTP JSON for importers researching ES/EU bottles.

- **URL**: https://apify.com/noahadler/vivino-wines.md
- **Developed by:** [Noah Adler](https://apify.com/noahadler) (community)
- **Categories:** E-commerce
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $2.00 / 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

## Vivino Wines — Ratings, Prices & Reviews

**Vivino scraper** / **Vivino API** stand-in for **wine ratings, prices and reviews**. Search by bottle name (Rioja, Marqués de Riscal Reserva) or paste a `vivino.com` wine URL. Each Dataset row is one wine: `wineId`, name, winery, vintage, rating (0–5), ratings count, price, currency, grapes, region, country, URL, and optional nested `reviews[]`.

Vivino **has no official public API**. This Actor talks to the same HTTP JSON the website uses (`search/wines` + `/api/vintages/{id}` + `/api/wines/{id}/reviews`). No Playwright on the happy path.

Ideal for **importers, wine shops, and price/rating research** on ES/EU bottles — a clean schema challenger, not a clone title of the bloated Store incumbents.

**Why this Actor:** Vivino ratings + prices · Rioja / ES examples · HTTP-only · PPE per **Wine**

***

### What you get

| Field | Description |
|-------|-------------|
| `wineId` / `vintageId` | Vivino identifiers |
| `name` / `winery` / `vintage` | Label + year (`N.V.` when non-vintage) |
| `rating` / `ratingsCount` | Community score **0–5** and vote count |
| `price` / `currency` | Marketplace amount when Vivino shows one |
| `grapes` / `region` / `country` | Style geography |
| `url` | Canonical `vivino.com` wine page |
| `reviews` | Optional sample (`includeReviews`) |

### Input example

```json
{
  "queries": ["Marques de Riscal Reserva"],
  "maxItems": 8,
  "includeReviews": false,
  "proxyConfiguration": { "useApifyProxy": false }
}
```

### Output example

```json
{
  "wineId": "1163903",
  "name": "Marqués de Riscal Reserva",
  "winery": "Marqués de Riscal",
  "vintage": "2019",
  "rating": 4.2,
  "ratingsCount": 85000,
  "price": 14.95,
  "currency": "EUR",
  "grapes": ["Tempranillo"],
  "region": "Rioja",
  "country": "Spain",
  "url": "https://www.vivino.com/en/marques-de-riscal-reserva/w/1163903"
}
```

Numbers above are illustrative — live runs return current Vivino catalog values.

### Proxy

Leave proxy **off** first. If you see HTTP 403 / AWS WAF, enable **RESIDENTIAL** (Spain `ES` if you care about EUR shelf prices). If residential still fails after 2–3 honest runs, treat it as a drop — do not rewrite the Actor as a browser farm.

### Limitations

- Unofficial endpoints can change without notice (same constraint as every Vivino scraper in the Store).
- Search HTML embeds the first results page; `maxItems` caps how many of those wines you keep.
- Some wines have a rating but **no marketplace price** in your country — `price` stays null (honest), we do not invent a number from the vintage year.
- `includeReviews` adds extra calls; reviews stay **nested** so PPE is still one **Wine** row.

### Racimo

1. **Hero (this Actor):** wines — ratings, prices, optional reviews
2. Later only if this one has runs: vintage history / merchant prices
3. Winelist monitor

PPE is **per Wine** (volume, cheap vs lead scrapers).

# Actor input Schema

## `queries` (type: `array`):

Search terms as on Vivino (bottle, winery, or appellation). Example: Marques de Riscal Reserva, Rioja.

## `wineUrls` (type: `array`):

Optional vivino.com wine pages (…/w/{id} or /wines/{id}).

## `maxItems` (type: `integer`):

Maximum wine rows (1–100). Reviews stay nested on the same row.

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

Attach a short reviews\[] sample (rating + text) on each wine. Extra Vivino calls.

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

Vivino JSON usually works without proxy. If you hit WAF/403, enable RESIDENTIAL (ES or your shopper country).

## Actor input object example

```json
{
  "queries": [
    "Marques de Riscal Reserva",
    "Rioja"
  ],
  "maxItems": 20,
  "includeReviews": false,
  "proxyConfiguration": {
    "useApifyProxy": false
  }
}
```

# Actor output Schema

## `wines` (type: `string`):

Dataset items: Vivino wines with ratings and prices.

# 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 = {
    "queries": [
        "Marques de Riscal Reserva",
        "Rioja"
    ]
};

// Run the Actor and wait for it to finish
const run = await client.actor("noahadler/vivino-wines").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 = { "queries": [
        "Marques de Riscal Reserva",
        "Rioja",
    ] }

# Run the Actor and wait for it to finish
run = client.actor("noahadler/vivino-wines").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 '{
  "queries": [
    "Marques de Riscal Reserva",
    "Rioja"
  ]
}' |
apify call noahadler/vivino-wines --silent --output-dataset

```

## MCP server setup

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

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/PHTqDakKrQzHD8FZt/builds/ruLc5auTHSHbhCwFn/openapi.json