Vivino Scraper

Vivino Scraper collects wine and vintage data, market prices, ratings, merchant offers and optional customer reviews. Use it to enrich a wine catalog, research prices for an importer, or supply a wine discovery application with structured public data. Search by wine name, combine explore filters, or provide specific Vivino wine and vintage URLs. The results distinguish each vintage from its written reviews, so you can analyse the two separately and join them by vintage id.

Vivino Scraper input options

Choose a wine name with search, select explore filters, or supply urls. A search for tignanello uses Vivino's wine-name search. Explore filters include wine type, grape, origin region, origin country, minimum rating and price range. Sorting supports average rating, rating count, price and discount percentage, in ascending or descending order. The default minimum rating is 1, which enables a broad explore search when no narrower filter is selected.

The country option selects the market for prices and available merchants. It defaults to US. The currency option uses an ISO currency code and defaults to the currency of the selected country. The wine's origin is independent of this choice: an Italian wine can have a US price market. Use origin_countries for the countries where the wine was produced, and country for the country where the offer is available. US offers can also vary by state; the actual observed state is included when available.

The six wine types are red, white, sparkling, rose, dessert and fortified. Grape filters accept grape names or grape ids as strings. Region filters accept Vivino region ids. Unknown grape names, unsupported country or currency codes, and a minimum price above the maximum price produce an input error. Source names are requested in English for consistent country, region and wine metadata.

For specific wines, urls accepts HTTPS Vivino URLs ending in /w/<wine_id>, optionally with a year, or /wines/<vintage_id>. You can also provide a vintage id as a string. Bare numbers identify vintages, so do not put a wine id in that format. Specific URLs take precedence over explore filters. A dated wine URL selects the requested vintage when Vivino lists it; an unavailable year does not silently become a different vintage.

max_wines sets the maximum number of unique vintages and defaults to 50. include_offers adds merchant offers. include_details adds exact vintage grapes, winemaker and further vintage statistics. include_reviews adds separate written-review rows. max_reviews defaults to 20 and limits unique reviews per wine. Increase either volume option for a larger collection; continuation keeps the same limits across the whole request.

Output: wine rows and review rows

The dataset contains two row types. record_type and _type identify a wine as catalog_entry and a written review as review. Every row includes the source, platform, retrieval timestamp, a stable row id and the relevant vintage id in entry_id. Wine rows include title, wine id, wine name, winery, vintage year, region, origin country, image and a Vivino page URL. They also contain the vintage's average rating and rating count, plus the wine-wide rating statistics when the source provides them.

Wine prices are numeric amounts in currency. Price fields can be null when no matching offer is available for that market. Discount information and bottle volume are included where available. With offers enabled, each merchant has its name, id, country and a list of prices. Each price can include a bottle-quantity message, inventory, link and bottle volume. Availability and prices can change between runs, so retain the timestamp and market fields with your analysis.

Grapes require care. Without details, the grape names describe Vivino's wine style and grapes_source is style. With details, they come from the vintage and grapes_source is vintage. Exact grapes are useful for catalog enrichment; style grapes are useful for discovery but should not be treated as a confirmed blend. Further detail fields include review count, rating distribution, wine facts, awards and recommended drinking years where supplied.

Review rows include a string review_id, rating, text, language, publication time, reviewer alias, likes and comments. Public reviewer statistics include rating count, review count and follower count. A dated vintage requests reviews for that year. Every delivered review has the same entry_id as its associated delivered wine, including non-vintage wines. Reviews of other vintages are excluded from delivery, the review limit and billing. Reviews follow the associated wine in delivery order.

Example output

A search with country: US, wine_types: ["red"] and max_wines: 3 returns wine rows like this one (abridged from a real result):

{
  "record_type": "catalog_entry",
  "entry_id": 172082835,
  "title": "Fortunate Son The Dreamer 2022",
  "winery": "Fortunate Son",
  "region": "Napa Valley",
  "country_code": "US",
  "vintage_year": 2022,
  "grapes": ["Cabernet Sauvignon"],
  "grapes_source": "style",
  "rating_average": 4.7,
  "ratings_count": 79,
  "price": 199,
  "currency": "USD",
  "market_country": "US",
  "url": "https://www.vivino.com/w/10472042?year=2022"
}

With include_reviews enabled, review rows follow their wine (reviewer name omitted here):

{
  "record_type": "review",
  "review_id": "187251426",
  "entry_id": 6401709,
  "rating": 4.5,
  "text": "Notes of vanilla, cherry and oak. A slight whiff of coffee on the nose. We had with steak and then cheese, and it was a perfect partner.",
  "language": "en",
  "published_at": "2020-12-19T18:58:07.000Z",
  "likes": 4,
  "author_ratings_count": 419
}

Vivino Scraper use cases

• Wine retail and importers: compare shelf prices with Vivino ratings per market, and spot well-rated wines that are priced below their peers.
• Price research: sort by price or discount percentage and track how merchant offers move between runs.
• Drinks apps and catalogs: enrich your own wine list with vintage ids, regions, grapes and rating statistics.
• Sentiment and taste analysis: collect written reviews with language, date and flavour words to study how a wine is described.

Vivino Scraper compared with other Vivino actors on the Store

Other Vivino actors on the Store mostly take a list of wine names and return one row per match, or run a filtered search with a single dataset item type. This actor combines both: name search, explore filters and direct vintage URLs in one input. It keeps wine rows and review rows separate, linked by entry_id, so you pay for reviews only when you ask for them. It also lets you choose the market country and currency independently of the wine's origin, and empty results are free.

Pricing and free usage

Wine rows and review rows are billed as separate events. Only delivered wine rows count toward the wine event, and only delivered review rows count toward the review event. Enabling offers or details does not create another wine row. Empty search results and unavailable inputs deliver no billable rows. Check this actor's Pricing tab for the current event prices before starting a run; price terms are managed by Apify.

Free usage is limited to ten delivered rows in total, including both wines and reviews. A wine with nine reviews fills that allowance. The requested wine and review volumes are capped before collection, and rows beyond the delivery allowance are not billed. Paid runs use the requested wine and review limits, subject to source availability and the run's configured timeout.

Continuation and source availability

Large requests continue in bounded pages. Apify automatically follows the continuation cursor while time and delivery allowance remain. If a cursor is exposed in a result, keep every other input option unchanged when resuming. Already delivered wine rows are not repeated when the next page continues collecting reviews. Stable row identities also prevent duplicate rows from being counted twice during collection.

A source interruption can leave useful partial results. Read the warnings and partial flag before assuming that every requested detail or review was available. A wine with no written reviews remains a valid wine result. Optional offers are null when not requested or unavailable, and an empty list when the request succeeded but no merchants were listed. Missing source fields remain null rather than being guessed.

Invalid individual wine or review records are skipped with a warning while collection continues. Invalid merchant offers leave the wine result available with a warning. Review collection scans at most 1,000 source pages per wine; reaching that limit before completion also produces a warning.

FAQ

Can I collect a particular vintage?

Yes. Provide a vintage URL or vintage id, or use a wine URL with its year. For example, a wine URL with ?year=2021 selects that year when Vivino lists it. Each wine result has its own vintage id and year.

Why do prices differ between countries?

Prices and merchants depend on the chosen market and available delivery area. The wine's origin country describes production, while market_country describes offers. Currency controls the amount's denomination. Keep those fields together when comparing results.

Does the review limit apply to the entire dataset?

max_reviews applies separately to each wine. max_wines counts unique wine vintages and excludes review rows. The free allowance applies to all delivered rows together, so it can stop a run before either requested volume is reached.

What happens when no wines match?

The run records a clear no-results error and does not deliver billable wine or review rows. Try a broader price range, a lower minimum rating or another market. Some wine types have limited availability in particular countries.

Can I use these results for a catalog join?

Use entry_id for a vintage and wine_id for the broader wine. Reviews carry their own vintage id. This source does not supply a dependable GTIN or EAN in the supported responses, so barcode joins require another source.