Pricing

Rating

Developer

Actor stats

Categories

Share

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

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

Run summary fields

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

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.

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.