Every wine, every vintage, and what it actually costs today
The Vivino API turns the world's largest wine database and its marketplace into clean JSON, in thirteen actions.
13 active endpoints, on 0, 1, 2 and 3 credit tiers.
- POST/vivino/v1/search
- POST/vivino/v1/wine/detail
- POST/vivino/v1/wine/vintages
- POST/vivino/v1/wine/prices
- POST/vivino/v1/wine/reviews
- POST/vivino/v1/wine/highlights
- POST/vivino/v1/wines/batch
- +6 more
What Vivino endpoints does ReefAPI ship?
13 live read endpoints. Read-only data API: no writes, no account actions, no dashboard access on the target site.
Vivino API
6 of 13 endpoints, ready to run
Find wines by free text, grape, region, country of origin, type, vintage year, price band or rating band. Rows carry the vintage id and the wine id, the year, the rating Vivino prints on the card AND the all-vintages pool beside it, the region, country, winery and style, the taste profile, and the cheapest live merchant offer.
// Press "Try it" and this pane shows exactly what the // live site returned this second — including an empty // result, if that is the truth. No key, no account.
How the Vivino API works
Vivino is a normal ReefAPI surface — the same four rules that hold for every other engine on the key.
No OAuth app, no request signing, no per-site account. One key covers all 280 engines.
Every route is a POST with a JSON body. Parameters are validated against the published schema before anything is charged.
Credits, not seats. Failed and blocked calls are never charged, and cache hits cost nothing.
One envelope everywhere. meta carries latency_ms, record_count and the endpoint that answered.
Find the wine, check the vintage's real rating, then see who sells it
Search gets you the bottle; the detail call is where you find out whether the rating on the card belongs to that year at all; the prices call is the marketplace. The step people skip is the middle one, and it is the one that changes the answer.
{"query": "malbec", "market": "us", "min_rating": 4.2, "price_max": 100}On 2026-09-23 a plain malbec search returned 1,741 matches on the US storefront; adding red, a 4.2 rating floor and a 100 ceiling cut it to 189. Each row carries the vintage id and the wine id you need next, plus the cheapest live offer.
{"vintage_id": 173783705}The search card for this wine shows 40,035 ratings. The detail call reports vintage_ratings_count 17 and status BelowThreshold — the card was showing every vintage pooled. This is the call that stops you publishing a number that is wrong by three orders of magnitude.
{"vintage_id": 150304508}Every year of the wine with its own rating, so you can see which vintage is actually the good one. This wine returned 45 vintages, from a 2026 with 4 ratings to a 2017 with 23,579.
{"vintage_id": 150304508, "market": "us", "currency": "USD"}The merchants and what they charge, with the median, cheapest and dearest. Note the bottle size on each offer — the best price on this wine is a 1,500 ml magnum, which is not comparable with a 750 ml bottle.
{"vintage_ids": [150304508, 164942636, 153403476], "full": false}When you are refreshing a catalogue rather than researching one bottle, batch up to 50 vintages into a single call instead of one call each.
The right bottle, a rating that genuinely belongs to the vintage you are selling, and what the market is charging for it today — without mistaking a pooled average for this year's wine.
curl -X POST https://api.reefapi.com/vivino/v1/search \
-H "x-api-key: $REEF_KEY" \
-H "content-type: application/json" \
-d '{}'{
"ok": true,
"data": { … },
"meta": {
"api": "vivino",
"endpoint": "search",
"mode": "live",
"latency_ms": …,
"record_count": …
},
"error": null
}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.
Which rating belongs to the vintage, what a price actually means, and what Vivino does not publish
Thirteen actions, no Vivino account needed. Measured on 2026-09-23 with 65 timed live calls across every action, an 8-wine rating check against the wine pages' own published figures, a 12-vintage price check and a field-fill count across four categories. Several of these lines go against us.
When Vivino has too few ratings for one year, its search card shows the rating pooled across every vintage of the wine, and the row's own status field still reads "Normal" — on 18 of 18 rows we checked. Catena Catena Alta Malbec 2023 shows 40,035 ratings on the card; that vintage has 17. Marqués de Riscal Reserva 1957 shows 262,702; that vintage has 6. We return the card figure and the all-vintages pool as separate fields and never merge them, and the detail call reports the vintage's own count with a status flag. Across 24 wines the two agreed on all 19 rated vintages and differed on all 5 unrated ones.
We checked our rating against the figure each wine page publishes about itself, on 8 wines: matched 8 of 8, exactly. Note that Vivino counts two different things — star ratings and written reviews — and they are far apart: one wine had 23,579 ratings and 6,156 written reviews. Both are returned under separate names, because treating one as the other is the easiest way to publish a wrong number here.
Vivino publishes no price history on its public pages, so no product can read one out of it this way and we do not invent one. What you get is the current merchant prices, labelled as current. Our prices action is deliberately one of the cheapest on this API so that snapshotting on a schedule — building the history yourself — is affordable.
Every offer carries its bottle size in millilitres and the size's name. On one wine the best offer Vivino shows is a 1,500 ml magnum at 278.24 — compare that with a 750 ml price and you have invented a bargain. We also return the previous price and two discount figures: Vivino's own stated percentage and the one we compute from its own prices, because the two can disagree, and we would rather show you both than pick.
The same malbec search returned 1,740 matches on the US storefront and 740 on the German one, with 12 and 11 merchants — and not one merchant appears on both. Pick the storefront with the market parameter; US and Germany are the two this API serves. Currency is a separate parameter and works on either.
On 12 vintages spanning 29.95 to 6,760.00, the offers we return contained the price Vivino prints on its own card 12 times out of 12. Where a wine has a single merchant you get a single offer; median, cheapest and dearest are computed from whatever is genuinely listed rather than padded.
Up to 50 results per page, and the source refuses more. Search also needs at least one real filter — a bare unfiltered listing is not offered, and we say so with the list of filters that stand alone rather than failing vaguely. Two parameters Vivino accepts are silently ignored by it, so we do not expose them at all; the response tells you which filters were actually applied.
Across 25 search rows in each of four categories, the vintage id, wine id, name, rating, rating count, region, country, winery, style, taste profile and cheapest offer were present on 25 of 25 every time. Across 24 full vintage records: ratings, histogram, ranks, grapes, food pairings, taste, region, winery and style on 24 of 24. The gaps are real and uneven — closure is on 6 of 6 reds but 0 of 6 whites, grape composition 6 of 6 on whites but 0 of 6 on rosés, critic scores 5 of 6 on whites but 0 of 6 on rosés, and awards on just 1 of 24. We report a pooled average nowhere, because it would hide exactly that.
Vivino writes a zero average for a vintage nobody has rated yet. We return null instead, because a 0.0 sorts a brand-new release as the worst wine on your list. In our rosé sample, 3 of 6 vintages were too new to carry their own rating — the wine-level rating is still there beside them, clearly labelled.
What people build with Vivino
The jobs this data is most often used for.
endpoints
credits per call
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.
What Vivino data costs
The cheapest call here is 0 credits, so $15/mo (Pro) buys 10,000 of them — $1.50 per 1,000 credits. Credits roll over and never expire, and failed or blocked calls are not charged.
Full pricing →- 1,000 free credits on signup, no card
- One key, all 280 APIs, one credit pool
- Failed and blocked calls are never charged
- Credits roll over and never expire
Call it in two lines
Sign up, get 1,000 credits and one key that works on every engine. Then this is the whole protocol.
curl -X POST https://api.reefapi.com/vivino/v1/search \
-H "x-api-key: $REEF_KEY" \
-H "content-type: application/json" \
-d '{}'import requests
r = requests.post(
"https://api.reefapi.com/vivino/v1/search",
headers={"x-api-key": REEF_KEY},
json={},
)
print(r.json()["data"])Have a question? We got answers.
The questions people actually ask before wiring up Vivino.
Get a free key →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.
116 E-commerce & Marketplaces APIs on the same key
One key, one credit pool, one response envelope. If you are pulling Vivino, you are one call away from the rest of the category — no second contract, no second integration.
Need something this API does not do?
Name the endpoint, the field, or a source we do not carry yet. We ship new APIs every week and you would be first to get the key. Real people read every message and reply the same day.
Try it on your own data before you pay anything
The call above is the real endpoint, not a recording. A free key gives you 1,000 credits, the other 279 APIs, and the same envelope everywhere.
Endpoints, parameters and credit costs on this page are read from the live catalog and cannot drift from what the API accepts. Field notes were captured on 2026-09-23.