Vivino API & Scraper
The Vivino API turns the world's largest wine database and its marketplace into clean JSON, in thirteen actions.
🤖 Using an AI assistant? Copy this link into ChatGPT / Claude / Cursor — it reads every endpoint and parameter instantly and tells you if this API fits your use case.
Search by free text, grape, region, country of origin, wine type, vintage year, price band and rating band — Vivino ranks 12,373,334 wines globally, and a single grape filter alone returns tens of thousands. Pull one vintage in full: its own rating, rating count and written-review count, a 1-to-5 ratings histogram, its global, country, region and winery rank, grape composition in percent, food pairings, the crowd-built taste structure (acidity, tannin, sweetness, intensity, fizziness) with the flavour keywords behind it, the drinking window, the closure and the critic scores. Read every year of the same wine with that year's own rating — 45 vintages came back for one Catena Zapata Malbec. Then read the marketplace: every merchant Vivino lists for that bottle, with its price, bottle size, discount and link, plus the median, cheapest and dearest offer. Reviews come back with the star rating, the note and the reviewer Vivino shows on the page. Up to 50 vintages in one batch call. One ReefAPI key, the standard { ok, data, meta, error } envelope, no Vivino account needed.
The rating on a Vivino search card is often not that vintage's rating — we return both
When Vivino has too few ratings for a specific year, its search card quietly shows the rating pooled across every vintage of that wine instead. The card does not say so — the status field on a search row read "Normal" on 18 of 18 rows we checked, including every one of these. So a naive scraper reports a 2025 bottling as having forty thousand ratings when four people have rated it. We return the card figure and the all-vintages pool as separate fields, and the vintage's own numbers come from the detail call with a status flag that tells you which you are looking at. Checked on 24 wines across four categories: the two agreed on all 19 rated vintages and differed on all 5 unrated ones.
| Wine | Ratings the search card shows | Ratings that vintage actually has | What our detail call reports |
|---|---|---|---|
| Catena Catena Alta Malbec 2023 | 40,035 | 17 | vintage_ratings_count 17, status BelowThreshold |
| Tilia Malbec 2025 | 18,234 | 4 | vintage_ratings_count 4, status BelowThreshold |
| Kaiken Malbec Reserva 2020 | 14,766 | 4 | vintage_ratings_count 4, status BelowThreshold |
| Flechas de los Andes Gran Malbec 2024 | 14,202 | 12 | vintage_ratings_count 12, status BelowThreshold |
| Marqués de Riscal Reserva 1957 | 262,702 | 6 | vintage_ratings_count 6, status BelowThreshold |
| Catena Zapata Malbec Argentino 2017 | 23,579 | 23,579 | vintage_ratings_count 23,579, status Normal ✅ |
An unrated vintage returns rating null, never 0.0 — Vivino writes a zero average for "nobody has rated this", and passing that through would sort a brand-new release as the worst wine on your list. The wine-level rating is still returned beside it, so you always have a number to fall back on and you always know which one it is.
Real request and response JSON
Captured from the indexed primary action, search, on .
{
"method": "POST",
"url": "https://api.reefapi.com/vivino/v1/search",
"headers": {
"x-api-key": "$REEF_KEY",
"content-type": "application/json"
},
"body": {
"query": "barolo",
"per_page": 10
}
}{
"ok": true,
"meta": {
"api": "vivino",
"endpoint": "search",
"mode": "live",
"latency_ms": 985.9,
"record_count": 10,
"bytes": 352378,
"cache_hit": false,
"stop_reason": "complete",
"upstream_requests": 1,
"charged_credits": 3,
"version": "1.0.0"
},
"data": {
"records_matched": 2112,
"page": 1,
"per_page": 10,
"market": {
"country": "us",
"state": "Virginia",
"currency": "USD"
},
"filters_applied": [
"query"
],
"wines": [
{
"vintage_id": 2459253,
"wine_id": 82199,
"name": "Giacomo Conterno Barolo Riserva Monfortino 2013",
"wine_name": "Barolo Riserva Monfortino",
"year": 2013,
"is_non_vintage": false,
"url": "https://www.vivino.com/w/82199?year=2013",
"seo_name": "giacomo-conterno-barolo-riserva-monfortino-2013",
"wine_type": "red",
"is_natural": false,
"rating": 4.7,
"ratings_count": 540,
"wine_rating": 4.7,
"wine_ratings_count": 6265,
"region": {
"id": 504,
"name": "Barolo",
"seo_name": "barolo",
"country": {
"code": "[trimmed-depth]",
"name": "[trimmed-depth]",
"wines_count": "[trimmed-depth]",
"wineries_count": "[trimmed-depth]"
}
},
"country": {
"code": "it",
"name": "Italy",
"wines_count": 303877,
"wineries_count": 44135
},
"winery": {
"id": 11472,
"name": "Giacomo Conterno",
"seo_name": "giacomo-conterno",
"ratings_count": null,
"ratings_average": null,
"wines_count": null
},
"style": {
"id": 7,
"name": "Italian Barolo",
"regional_name": "Italian",
"varietal_name": "Barolo",
"body": 5,
"body_description": "Very full-bodied",
"acidity": 3,
"acidity_description": "High"
},
"taste": {
"structure": {
"acidity": "[trimmed-depth]",
"fizziness": "[trimmed-depth]",
"intensity": "[trimmed-depth]",
"sweetness": "[trimmed-depth]",
"tannin": "[trimmed-depth]",
"user_structure_count": "[trimmed-depth]"
},
"flavors": [
"[trimmed-depth]",
"[trimmed-depth]",
"[trimmed-depth]"
]
},
"image_url": "https://images.vivino.com/thumbs/ElcyI1YpRSes_LvNodMeSQ_pb_x600.png",
"best_price": {
"price_id": 32675977,
"merchant_id": 34781,
"amount": 2307,
"currency": "USD",
"discounted_from": null,
"discount_percent_source": null,
"discount_percent_computed": null,
"bottle_volume_ml": 750,
"bottle_type": "Bottle (0.75l)",
"bottle_quantity": 1,
"sku": "57315633",
"url": "https://www.drinkdivino.com/giacomo-conterno-barolo-riserva-monfortino-2013.html",
"offer_type": "vc"
},
"prices": [
{
"price_id": "[trimmed-depth]",
"merchant_id": "[trimmed-depth]",
"amount": "[trimmed-depth]",
"currency": "[trimmed-depth]",
"discounted_from": "[trimmed-depth]",
"discount_percent_source": "[trimmed-depth]",
"discount_percent_computed": "[trimmed-depth]",
"bottle_volume_ml": "[trimmed-depth]",
"bottle_type": "[trimmed-depth]",
"bottle_quantity": "[trimmed-depth]",
"sku": "[trimmed-depth]",
"url": "[trimmed-depth]",
"offer_type": "[trimmed-depth]"
}
],
"prices_count": 1
},
{
"vintage_id": 1243783,
"wine_id": 82199,
"name": "Giacomo Conterno Barolo Riserva Monfortino 2008",
"wine_name": "Barolo Riserva Monfortino",
"year": 2008,
"is_non_vintage": false,
"url": "https://www.vivino.com/w/82199?year=2008",
"seo_name": "giacomo-conterno-barolo-riserva-monfortino-2008",
"wine_type": "red",
"is_natural": false,
"rating": 4.7,
"ratings_count": 490,
"wine_rating": 4.7,
"wine_ratings_count": 6265,
"region": {
"id": 504,
"name": "Barolo",
"seo_name": "barolo",
"country": {
"code": "[trimmed-depth]",
"name": "[trimmed-depth]",
"wines_count": "[trimmed-depth]",
"wineries_count": "[trimmed-depth]"
}
},
"country": {
"code": "it",
"name": "Italy",
"wines_count": 303877,
"wineries_count": 44135
},
"winery": {
"id": 11472,
"name": "Giacomo Conterno",
"seo_name": "giacomo-conterno",
"ratings_count": null,
"ratings_average": null,
"wines_count": null
},
"style": {
"id": 7,
"name": "Italian Barolo",
"regional_name": "Italian",
"varietal_name": "Barolo",
"body": 5,
"body_description": "Very full-bodied",
"acidity": 3,
"acidity_description": "High"
},
"taste": {
"structure": {
"acidity": "[trimmed-depth]",
"fizziness": "[trimmed-depth]",
"intensity": "[trimmed-depth]",
"sweetness": "[trimmed-depth]",
"tannin": "[trimmed-depth]",
"user_structure_count": "[trimmed-depth]"
},
"flavors": [
"[trimmed-depth]",
"[trimmed-depth]",
"[trimmed-depth]"
]
},
"image_url": "https://images.vivino.com/thumbs/ElcyI1YpRSes_LvNodMeSQ_pb_x600.png",
"best_price": {
"price_id": 35957409,
"merchant_id": 34781,
"amount": 2112,
"currency": "USD",
"discounted_from": null,
"discount_percent_source": null,
"discount_percent_computed": null,
"bottle_volume_ml": 750,
"bottle_type": "Bottle (0.75l)",
"bottle_quantity": 1,
"sku": "58242072",
"url": "https://www.drinkdivino.com/giacomo-conterno-barolo-riserva-monfortino-2008.html",
"offer_type": "vc"
},
"prices": [
{
"price_id": "[trimmed-depth]",
"merchant_id": "[trimmed-depth]",
"amount": "[trimmed-depth]",
"currency": "[trimmed-depth]",
"discounted_from": "[trimmed-depth]",
"discount_percent_source": "[trimmed-depth]",
"discount_percent_computed": "[trimmed-depth]",
"bottle_volume_ml": "[trimmed-depth]",
"bottle_type": "[trimmed-depth]",
"bottle_quantity": "[trimmed-depth]",
"sku": "[trimmed-depth]",
"url": "[trimmed-depth]",
"offer_type": "[trimmed-depth]"
}
],
"prices_count": 1
},
{
"vintage_id": 1199466,
"wine_id": 82199,
"name": "Giacomo Conterno Barolo Riserva Monfortino 1999",
"wine_name": "Barolo Riserva Monfortino",
"year": 1999,
"is_non_vintage": false,
"url": "https://www.vivino.com/w/82199?year=1999",
"seo_name": "giacomo-conterno-barolo-riserva-monfortino-1999",
"wine_type": "red",
"is_natural": false,
"rating": 4.7,
"ratings_count": 358,
"wine_rating": 4.7,
"wine_ratings_count": 6265,
"region": {
"id": 504,
"name": "Barolo",
"seo_name": "barolo",
"country": {
"code": "[trimmed-depth]",
"name": "[trimmed-depth]",
"wines_count": "[trimmed-depth]",
"wineries_count": "[trimmed-depth]"
}
},
"country": {
"code": "it",
"name": "Italy",
"wines_count": 303877,
"wineries_count": 44135
},
"winery": {
"id": 11472,
"name": "Giacomo Conterno",
"seo_name": "giacomo-conterno",
"ratings_count": null,
"ratings_average": null,
"wines_count": null
},
"style": {
"id": 7,
"name": "Italian Barolo",
"regional_name": "Italian",
"varietal_name": "Barolo",
"body": 5,
"body_description": "Very full-bodied",
"acidity": 3,
"acidity_description": "High"
},
"taste": {
"structure": {
"acidity": "[trimmed-depth]",
"fizziness": "[trimmed-depth]",
"intensity": "[trimmed-depth]",
"sweetness": "[trimmed-depth]",
"tannin": "[trimmed-depth]",
"user_structure_count": "[trimmed-depth]"
},
"flavors": [
"[trimmed-depth]",
"[trimmed-depth]",
"[trimmed-depth]"
]
},
"image_url": "https://images.vivino.com/thumbs/ElcyI1YpRSes_LvNodMeSQ_pb_x600.png",
"best_price": {
"price_id": 39924490,
"merchant_id": 34781,
"amount": 3599,
"currency": "USD",
"discounted_from": null,
"discount_percent_source": null,
"discount_percent_computed": null,
"bottle_volume_ml": 750,
"bottle_type": "Bottle (0.75l)",
"bottle_quantity": 1,
"sku": "68262792",
"url": "https://www.drinkdivino.com/giacomo-conterno-barolo-riserva-monfortino-1999.html",
"offer_type": "vc"
},
"prices": [
{
"price_id": "[trimmed-depth]",
"merchant_id": "[trimmed-depth]",
"amount": "[trimmed-depth]",
"currency": "[trimmed-depth]",
"discounted_from": "[trimmed-depth]",
"discount_percent_source": "[trimmed-depth]",
"discount_percent_computed": "[trimmed-depth]",
"bottle_volume_ml": "[trimmed-depth]",
"bottle_type": "[trimmed-depth]",
"bottle_quantity": "[trimmed-depth]",
"sku": "[trimmed-depth]",
"url": "[trimmed-depth]",
"offer_type": "[trimmed-depth]"
}
],
"prices_count": 1
}
]
}
}What the Vivino API does
| Action | Description | Concrete use case | Key params |
|---|---|---|---|
| search | Search Vivino's wine database. Filters by free text, grape, region, country of origin, wine type, vintage year, price band and rating band, and every filter here was measured to change the result count. Returns the vintage id and the wine id, the rating Vivino prints on the card AND the all-vintages pool beside it, the region/winery/style, and the cheapest live merchant offer. | Pricing teams call search to search Vivino's wine database. | query, market, currency, wine_type, country_codes, ... |
| wine/detail | One VINTAGE in full: the vintage's own rating, rating count and review count (and the flag saying whether Vivino rates this vintage on its own), the wine-level pool beside it, the ratings histogram, the global/country/region/winery ranks, the grape composition in percent, food pairings, the crowd taste structure, both published alcohol figures, the drinking window and the critic scores. | Marketplace operators call wine/detail to get one VINTAGE in full. | vintage_id, market, include_taste |
| wine/vintages | Every year of the same wine with that year's OWN rating, rating count and review count. This is the row a collector compares, and it is the honest answer to 'is the 2019 better than the 2018' — the search card cannot answer it. | Catalog enrichment teams call wine/vintages to get every year of the same wine with that year's OWN rating, rating count and review count. | vintage_id, market |
| wine/prices | The marketplace half: every merchant Vivino lists for one vintage, with its price, bottle size, discount and link. Also the median, cheapest and dearest offer. The merchant set is per storefront — the US and DE markets share none. | Retail analysts call wine/prices to get the marketplace half. | vintage_id, market, currency |
| wine/reviews | The published reviews for a wine, newest first, with the star rating, the note and the reviewer Vivino shows on the page. Pass `year` to read one vintage's reviews. | Pricing teams call wine/reviews to get the published reviews for a wine, newest first, with the star rating, the note and the review…. | wine_id, year, market, page, per_page |
| wine/highlights | The badges and ranks Vivino awards a vintage: global rank, rank within its country, its region and its winery, plus the critic scores behind them. | Marketplace operators call wine/highlights to get the badges and ranks Vivino awards a vintage. | vintage_id, market |
| wines/batch | Up to 50 vintages in ONE call — how a catalogue of thousands is refreshed without spending a call per wine. `full=false` returns the identity and rating block at about a fifth of the bytes. | Catalog enrichment teams call wines/batch to get up to 50 vintages in ONE call. | vintage_ids, market, full |
| winery/wines | A winery's catalogue: every wine it makes, with the wine-level rating and the best-rated vintage of each. | Retail analysts call winery/wines to get a winery's catalogue. | winery_id, market |
| region/detail | One wine region: its country, parent and sub-regions, its top grapes and how many wines and wineries Vivino holds for it. | Pricing teams call region/detail to get one wine region. | region_id, market |
| grapes | The grape enum behind `grape_ids` — 2229 grape varieties with the id, the name and how many wines Vivino holds for each. | Marketplace operators call grapes to get the grape enum behind `grape_ids`. | query, market, per_page |
| foods | The food-pairing enum behind `food_ids` — the 23 pairings Vivino uses. | Catalog enrichment teams call foods to get the food-pairing enum behind `food_ids`. | market |
| wine_styles | The style enum behind `wine_style_ids` — 747 regional styles such as 'Argentinian Mendoza Malbec'. | Retail analysts call wine_styles to get the style enum behind `wine_style_ids`. | query, market, per_page |
| countries | The country enum behind `country_codes` — 253 countries with how many wines and wineries Vivino holds for each, and their most used grapes. | Pricing teams call countries to get the country enum behind `country_codes`. | market |
Call search from your stack
curl -X POST https://api.reefapi.com/vivino/v1/search \
-H "x-api-key: $REEF_KEY" \
-H "content-type: application/json" \
-d '{"query":"barolo","per_page":10}'import requests
r = requests.post(
"https://api.reefapi.com/vivino/v1/search",
headers={"x-api-key": REEF_KEY},
json={
"query": "barolo",
"per_page": 10
},
)
print(r.json()["data"])const res = await fetch("https://api.reefapi.com/vivino/v1/search", {
method: "POST",
headers: {
"x-api-key": process.env.REEF_KEY,
"content-type": "application/json",
},
body: JSON.stringify({
"query": "barolo",
"per_page": 10
}),
});
const { ok, data, meta, error } = await res.json();Ask your MCP-connected assistant: call reefapi.vivino.search with {"query":"barolo","per_page":10}.Who uses this API and why
- Wine retail and e-commerce: enrich a catalogue with the rating, rating count, grape composition, region, food pairings and taste profile for the exact vintage you are selling, not a number pooled from other years.
- Price monitoring and competitor tracking: read which merchants list a bottle and what they charge, per storefront, and snapshot it on a schedule to build the price history Vivino does not publish.
- Restaurant and sommelier tools: build a wine list from food pairing, style, body and acidity, and show guests a rating that genuinely belongs to the vintage in the cellar.
- Collector and cellar apps: compare every year of a wine by its own rating and review count, with the drinking window and global, country, region and winery ranks.
- Market research on wine: measure how a grape, a region or a country performs across the catalogue using rating distributions, rating counts and price bands rather than anecdote.
Questions developers ask before integrating
Do I need a Vivino account?
No. Every action on this page works without one. Search, the vintage record, the vintage ladder, merchant prices, reviews, highlights, the winery catalogue, regions and all four id enums are returned anonymously.
Does it handle vintages properly, or does it collapse them?
Vintages are the point. Every id we return is a vintage id — one specific year of one wine — and wine/detail reports that year's own rating, rating count and written-review count with a status flag saying whether Vivino rates it on its own. wine/vintages returns every year of the same wine side by side with each year's rating; one Catena Zapata Malbec returned 45 vintages. Non-vintage bottlings come back as year null with is_non_vintage true rather than year 0.
Which prices do I get, and from whom?
The merchants Vivino itself lists for that vintage, each with its asking price and currency, its bottle size in millilitres, any previous price, and a link. You also get the median, cheapest and dearest offer across them. On 12 vintages we checked, our offers bracketed the price Vivino shows on its own card 12 out of 12 times.
Is there price history?
No, and we will not invent one. Vivino publishes no price history on its public pages, so what you get is the current merchant prices, clearly labelled as current. If you need a trend line, store our snapshots on a schedule — the prices action is one of the cheapest on this API precisely so that is affordable.
Prices differ by country — how do I pick the storefront?
With the market parameter. Vivino runs separate storefronts and they are genuinely different marketplaces: the same malbec search returned 1,740 matches on the US storefront and 740 on the German one, with 12 and 11 merchants respectively and not a single merchant in common. US and Germany are the two storefronts this API serves. The currency parameter is separate and works on either.
What does the taste structure actually contain?
Vivino's crowd-built profile: acidity, tannin, sweetness, intensity and fizziness as numeric scales, with the count of users behind them, plus the flavour groups (black fruit, oak, earth and so on) and the specific keywords under each with how many reviewers mentioned them — blackberry 415, plum 349, oak 461 on one wine. Fizziness is null on still wines, which is the source saying not-applicable rather than zero. Taste was present on 24 of 24 wines we sampled.
Do reviews include the reviewer?
Yes, exactly as the public review page prints it: the star rating, the written note, the language, the date, and the reviewer's display name and profile handle. Nothing account-gated is read. Pass a year to read one vintage's reviews; up to 50 reviews per page.
How do I filter by grape, region or food pairing?
By id, and the ids come from this API: grapes returns 2,229 varieties, wine_styles 747 regional styles, countries 253 and foods 23 pairings. Every filter on the search action was measured to change the result count in the same run — grape, region, style, country of origin, wine type, vintage year, price band, minimum rating, minimum rating count, bottle size, natural-only and discounted-only all bite.
What is the Vivino API?
Vivino API is a ReefAPI endpoint group for the world's largest wine database and its marketplace — ratings, grape composition, food pairings and taste structure per vintage, plus the merchants selling the bottle and what they charge. It returns live JSON through POST requests under /vivino/v1.
Is the Vivino API free to try?
Yes. ReefAPI starts with 1,000 free credits, no card required. Vivino calls use the same shared credit balance as every other ReefAPI engine.
Do I need a Vivino login or account?
No login to Vivino is needed for the API response. You call ReefAPI with your x-api-key header, and the playground can run live examples before you create a production key.
How fresh is the Vivino data?
The page example is captured from a live search call, and production requests fetch live data through ReefAPI rather than a static sample.
How many credits does the Vivino API use?
Vivino actions currently cost 1-3 credits per successful call. Failed or blocked calls are free. All APIs draw from one credit pool.
Can I call Vivino from an AI assistant or MCP client?
Yes. Connect ReefAPI once through MCP and your assistant can call vivino actions with the same key, credit pool and JSON envelope used by normal REST requests.