Vivino Wine Search API Wrapper

Find Vivino-style wine ratings and product details from a list of wine names. This Actor works as a batch-friendly Vivino API wrapper for wine catalog enrichment, wine ratings API workflows, wine price enrichment, and wine product matching. It accepts one or more wine search queries, looks them up through a managed wine search API, and saves one structured result per successful match to the default Apify dataset.

Use it when you need wine ratings, review counts, winery names, vintages, average prices, and source URLs in a batch-friendly format for enrichment, research, catalog cleanup, lead qualification, or marketplace data workflows.

What does this Actor do?

• Searches wine names, product titles, or free-text wine queries.
• Returns normalized wine information when a match is found.
• Writes one billable dataset row per successful wine match.
• Keeps failed or unmatched searches visible in the run log and RUN_SUMMARY key-value-store record.
• Runs as a batch Actor, so results can be exported as JSON, CSV, Excel, XML, or consumed through the Apify API.

Why use this Actor?

• Success-only result billing: pay for matched wine results, not every attempted query.
• No Vivino key needed: run wine search and enrichment jobs without bringing your own Vivino API credentials.
• Built for catalog enrichment: submit merchant titles, SKUs, wine list entries, or internal product names in bulk.
• Clean one-row-per-wine output: each successful match becomes a normalized dataset row that is easy to export or join back to your catalog.
• Failed matches reported separately: unmatched and failed queries stay out of the billable result dataset and are listed in RUN_SUMMARY.

Input

Provide an array of wine search queries.

{
  "queries": [
    "Vin rosu sec Tenuta Luce Brunello di Montalcino 2018, 0.75L",
    "Morillon Blanc 2024 - Jeff Carrel",
    "White Wine Tenuta Ulisse Pecorino Terre D' Abruzzo 13%, 6 x 0.75L",
    "Purcari Malbec"
  ]
}

Input fields

Field	Type	Required	Description
queries	array of strings	Yes	Wine names, product titles, vintages, or search phrases. Each query creates one backend search request. Successful matches create one billable dataset item. Maximum: 500 unique queries per run.

Pricing and billing behavior

This Actor uses Apify's pay-per-event pricing.

• Actor Start is charged once when a run starts, according to the Actor's configured Apify pricing.
• Wine result is charged through Apify's apify-default-dataset-item event.
• Each successful wine match written to the default dataset counts as one Wine result event.
• Unmatched queries and backend errors are not written to the default dataset, so they are not charged as Wine result events.

For example, if you submit 100 queries and 83 wines are matched, the run produces 83 billable dataset items.

Output

The Actor stores successful wine matches in the default dataset. Each item contains the original query, a status, timing metadata, and wine fields when available.

{
  "query": "Purcari Malbec",
  "normalized_query": "Purcari Malbec 2020",
  "status": "found",
  "elapsed_ms": 842,
  "match_confidence": 0.94,
  "matched_at": "2026-06-28T09:20:31Z",
  "name": "Malbec",
  "winery": "Purcari",
  "year": 2020,
  "type": 1,
  "color": 1,
  "grapes": "Malbec",
  "alcohol": "13.5",
  "details": "Purcari Malbec 2020",
  "score": 4.1,
  "reviews": 1200,
  "url": "https://www.vivino.com/...",
  "avg_price": "18.50",
  "currency": "EUR"
}

Unmatched queries and backend errors are reported in the run log and in the RUN_SUMMARY record in the default key-value store.

Dataset fields

Field	Description
query	The original search query submitted to the Actor.
normalized_query	Cleaned query text used for product matching and catalog enrichment.
status	found for billable default-dataset records.
elapsed_ms	Backend request duration in milliseconds.
match_confidence	Approximate match confidence from 0 to 1, when available.
matched_at	UTC timestamp when the Actor prepared the successful match row.
name	Matched wine name, when available.
winery	Matched producer or winery, when available.
year	Vintage year, when available.
type	Internal wine type identifier, when available.
color	Internal color identifier, when available.
grapes	Matched grape variety or blend, when available.
alcohol	Alcohol percentage or ABV value, when available.
details	Full stored wine detail text, when available.
score	Wine score/rating, when available.
reviews	Number of reviews, when available.
url	Source wine page URL, when available.
avg_price	Average price, when available.
currency	Price currency, when available.

Run summary fields

The default key-value store includes a RUN_SUMMARY record with:

Field	Description
total_queries	Number of input queries accepted for the run.
billable_dataset_items	Number of successful matches written to the default dataset. This is the number of Wine result events.
found	Number of successful wine matches.
not_found	Number of unmatched queries.
errors	Number of backend or request errors.
not_found_queries	Input queries that did not produce a match.
error_items	Failed request details, including query, http_status when available, and error.

Typical use cases

• Enrich wine catalogs with ratings, review counts, vintages, and winery names.
• Clean up merchant product titles by resolving them to structured wine records.
• Compare wine lists across shops, marketplaces, or internal inventories.
• Build datasets for pricing analysis, product matching, or wine recommendation workflows.
• Run scheduled searches and export results automatically through Apify integrations.

Examples for e-commerce teams

• Merchant product title cleanup: turn messy storefront names like Purcari Malbec rosu 0.75L 2020 into structured wine, winery, vintage, rating, review, URL, and price fields.
• SKU enrichment: map internal SKU names or supplier feed rows to matched wine records for product detail pages, search filters, and marketplace listings.
• Wine list rating enrichment: add wine ratings and review counts to restaurant, retail, marketplace, or subscription-box wine lists.
• Price/rating research: compare average prices, ratings, and review volume across a basket of wines for merchandising, assortment, and competitor research.

Sample product-title input

These examples show realistic product titles and what the parser can infer before the backend picks the best available match.

Example query	Parsed intent
Vin rosu sec Tenuta Luce Brunello di Montalcino 2018, 0.75L	Romanian retail title for a dry red wine. Parses winery Tenuta Luce, wine Brunello di Montalcino, vintage 2018, and bottle size 0.750.
Morillon Blanc 2024 - Jeff Carrel	White wine title with producer text. Parses vintage 2024 and white type; producer text may stay in the normalized name if it is not recognized as a known winery.
White Wine Tenuta Ulisse Pecorino Terre D' Abruzzo 13%, 6 x 0.75L	Packaged white-wine title. Parses white type, package quantity 6, and bottle size 0.750; less-standard producer/appellation text may remain in the normalized name.
Purcari Malbec	Concise producer and grape/wine query. Parses winery Purcari and grape/wine Malbec; no vintage specified.

How to use it

1. Open the Actor on Apify.
2. Add one or more wine names to the queries input, up to 500 unique queries per run.
3. Start the run.
4. Open the default dataset to view, filter, export, or integrate the results.

You do not need to provide a separate Vivino key or backend API key. The Actor uses a managed backend connection.

Tips for better matches

• Include the winery or producer name when possible.
• Add the vintage year for wines where the year matters.
• Use the complete label name from the bottle or product page.
• Split different wines into separate query items instead of sending one long combined query.

Good queries:

Vin rosu sec Tenuta Luce Brunello di Montalcino 2018, 0.75L
Morillon Blanc 2024 - Jeff Carrel
White Wine Tenuta Ulisse Pecorino Terre D' Abruzzo 13%, 6 x 0.75L
Purcari Malbec

Less reliable queries that illustrate API limitations:

red wine
best merlot
cheap italian bottle

Limits and reliability

This Actor is designed for batch enrichment, not real-time interactive search. Runs are limited to 500 unique queries and paced against the backend API to keep performance predictable.

Search results depend on available source data and matching quality. Some wines may be missing, have incomplete fields, or return a nearby match rather than the exact product label. Always review important results before using them in production pricing, inventory, or compliance workflows.

Export and integrations

Because output is stored in an Apify dataset, you can:

• Export results as JSON, CSV, Excel, XML, RSS, or HTML.
• Pull results through the Apify API.
• Send finished runs to webhooks.
• Connect the dataset to automation tools and data pipelines.
• Schedule recurring runs for repeated catalog checks.

Legal and affiliation notice

This Actor is an independent data enrichment tool and is not affiliated with, endorsed by, or sponsored by Vivino. Wine names, brands, wineries, and trademarks belong to their respective owners.

Use the Actor responsibly and make sure your use case complies with applicable laws, marketplace requirements, and the terms that apply to your downstream use of the data.

Support

If you run into issues, include the Actor run ID, a small sample of input queries, and the affected dataset rows when contacting support. This makes it much easier to reproduce matching or backend errors.