Vivino Wine Matcher API

Match messy retailer titles, supplier descriptions, or simple wine names to structured Vivino wine records in bulk. Each successful match returns normalized identity data, vintage, ratings, pricing, a confidence score, and alternative candidates—ready for catalog enrichment or export.

This Actor is built for wine product entity resolution, not broad Vivino crawling. Submit up to 500 unique queries and receive one best-match dataset row for each successful result.

From product title to structured wine

Input

Vin rosu sec Tenuta Luce Brunello di Montalcino 2018, 0.75L

Matched output from a successful Actor run

{
  "query": "Vin rosu sec Tenuta Luce Brunello di Montalcino 2018, 0.75L",
  "normalized_query": "Tenuta Luce Brunello di Montalcino 2018",
  "status": "found",
  "match_confidence": 1,
  "name": "Luce Brunello di Montalcino",
  "winery": "Tenuta Luce",
  "year": 2018,
  "grapes": "Sangiovese",
  "alcohol": "14.9",
  "score": 4.4,
  "reviews": 584,
  "url": "https://www.vivino.com/tenuta-luce-luce-brunello-di-montalcino/w/83595?year=2018",
  "avg_price": "649.99",
  "currency": "EUR"
}

Values such as ratings, review counts, prices, and availability may change at the source.

Why use this Actor?

• Handles messy catalog titles: removes packaging, pack-count, bottle-size, and other retail noise before matching.
• Selects one best candidate: ranks matches using winery, wine name, grape, and vintage evidence.
• Shows match confidence: use match_confidence to review uncertain matches before importing them.
• Returns alternatives: strong variant candidates are preserved in alternatives when available.
• Rejects obvious non-wine products: filters beer, cider, gift sets, and similar false positives.
• Success-only result billing: unmatched searches and backend errors do not create billable dataset rows.
• No separate Vivino API key: the Actor uses a managed backend connection.

Best-fit use cases

• Enrich retailer, distributor, marketplace, or restaurant wine catalogs.
• Normalize supplier feeds and inconsistent SKU descriptions.
• Add wine ratings, review counts, vintages, wineries, grapes, and source URLs.
• Flag uncertain matches for human review using confidence and alternatives.
• Schedule recurring enrichment jobs and export results as JSON, CSV, Excel, or XML.

Input

Provide one or more wine names or product titles in queries:

{
  "queries": [
    "Tenuta Luce Brunello di Montalcino 2018, 0.75L",
    "Morillon Blanc 2024 - Jeff Carrel",
    "Purcari Malbec"
  ]
}

Field	Type	Required	Limit
queries	Array of unique strings	Yes	500 per run

For stronger matches, include the producer, full label name, and vintage when available. Broad intent queries such as best merlot or cheap Italian wine are not a good fit.

Output fields

Successful matches are written to the default dataset.

Field	Meaning
query	Original submitted product title or wine name.
normalized_query	Cleaned query used by the matching engine.
status	found for billable dataset records.
match_confidence	Approximate matching confidence from 0 to 1; review lower-confidence matches.
matched_at	UTC time when the match row was prepared.
name, winery, year	Matched wine identity and vintage.
type, color	Source-provided numeric identifiers when available.
grapes, alcohol	Source-provided grape/blend and ABV values.
score, reviews	Community rating and associated review/rating volume when available.
url	Matched Vivino source page.
avg_price, currency	Source/store price and ISO currency when available; otherwise null.
alternatives	Strong alternative variants and their match evidence when available.

Source coverage varies by wine and market. Missing fields are returned as null or omitted; important matches should be reviewed before production pricing, inventory, or compliance decisions.

Run it through the Apify API

Replace YOUR_APIFY_TOKEN with your Apify API token:

curl -X POST \
  "https://api.apify.com/v2/acts/pulse_hub~vivino-wine-search-api/run-sync-get-dataset-items?token=YOUR_APIFY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"queries":["Purcari Malbec","Tenuta Luce Brunello 2018 0.75L"]}'

You can also run the Actor from the Apify Console, official JavaScript/Python clients, schedules, webhooks, and integrations.

Billing

This Actor uses Apify pay-per-event pricing:

• Actor Start is charged once per run at the price shown on the Pricing tab.
• Wine result is charged once for each successful match written to the default dataset.
• Unmatched queries and backend errors remain outside the default dataset and are not charged as Wine result events.

For example, 100 submitted queries with 83 successful matches produce 83 billable wine-result rows. The RUN_SUMMARY record reports totals, unmatched queries, and request errors.

Limits and reliability

• Maximum 500 unique queries per run.
• Designed for batch enrichment rather than latency-sensitive interactive search.
• Matching and field availability depend on the source data available for each query.
• match_confidence is a matching heuristic, not a guarantee of product identity.

Legal 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. Ensure that your use complies with applicable laws, marketplace requirements, and relevant source and downstream terms.

Support

When reporting an issue, include the Actor run ID, a small sample of affected queries, and the corresponding output rows. This makes matching problems easier to reproduce.