Vivino APIvivino.com ↗
Search wines, wineries, and food pairings from Vivino via 6 endpoints. Returns ratings, vintages, regions, descriptions, and winery profiles.
What is the Vivino API?
The Vivino API provides access to wine and winery data across 6 endpoints, covering search, catalog browsing, detailed wine profiles, and food pairings. Using search_wines, you can query by name, grape variety, or region and receive structured results including ratings averages, vintage arrays, and winery metadata. Companion endpoints like get_wine_details and get_winery_details return deeper fields such as food pairings, grapes, winemaker names, and region statistics.
curl -X GET 'https://api.parse.bot/scraper/0573a298-2c9e-48ad-98ad-08cd6f65e3e4/search_wines?page=0&limit=5&query=malbec' \ -H 'X-API-Key: $PARSE_API_KEY'
Typed, relational, agent-ready
A generated client with real types, enums, and the links between objects — the structure a flat JSON response can't carry. Autocompletes in your editor and reads cleanly to coding agents.
- Fully typed · autocompletes
- Objects link to objects
- Typed errors & pagination
Typed Python client. Set up the SDK in your uv project, then pull this API’s typed client:
uv add parse-sdk uv run parse init uv run parse add --marketplace vivino-com-api
uv run parse add --marketplace pulls a pinned snapshot of this canonical API — it won’t change underneath you. To customize it, subscribe and swap to your own copy.
from parse_apis.vivino_wine_api import Vivino, Wine, Winery, WineNotFound
vivino = Vivino()
# Search for Malbec wines and browse results
for wine in vivino.wines.search(query="malbec"):
print(wine.name, wine.statistics.ratings_average, wine.region.name)
# Get detailed info about a specific wine
detail = vivino.wines.get(wine_id="1135067")
print(detail.name, detail.description, detail.winery.name)
# Explore popular wines from the catalog
for wine in vivino.wines.explore():
print(wine.name, wine.winery.name, wine.statistics.ratings_count)
# Find wines related to a food keyword
for wine in vivino.wines.food_pairing(food_name="steak"):
print(wine.name, wine.region.country)
# Search for wineries by name
for winery in vivino.wineries.search(query="penfolds"):
print(winery.name, winery.website, winery.statistics.wines_count)
# Get winery details by slug
winery_detail = vivino.wineries.get(winery_slug="penfolds")
print(winery_detail.name, winery_detail.winemaker, winery_detail.region.name)
Full-text search over Vivino's wine catalog. Matches wine name, grape variety, region, and winery name. Returns paginated results ordered by relevance with full wine details including name, region, winery, vintages, ratings, and description.
| Param | Type | Description |
|---|---|---|
| page | integer | Page number (0-indexed). |
| limit | integer | Max results per page. |
| queryrequired | string | Search keyword (wine name, grape variety, region, winery, etc.). |
{
"type": "object",
"fields": {
"hits": "array of wine objects with id, name, seo_name, region, winery, vintages, statistics, description",
"page": "current page number (0-indexed)",
"nbHits": "total number of matching wines",
"nbPages": "total number of pages",
"hitsPerPage": "number of results per page"
},
"sample": {
"data": {
"hits": [
{
"id": 1135980,
"name": "Reserve Malbec",
"region": {
"id": 454,
"name": "Mendoza",
"country": "ar"
},
"winery": {
"id": 4137,
"name": "Trivento",
"seo_name": "trivento"
},
"type_id": 1,
"seo_name": "reserve-malbec",
"vintages": [
{
"id": 1527219,
"name": "Trivento Reserve Malbec",
"year": "U.V.",
"statistics": {
"ratings_count": 105754,
"ratings_average": 3.7
}
}
],
"statistics": {
"ratings_count": 105754,
"ratings_average": 3.7
}
}
],
"page": 0,
"nbHits": 32633,
"nbPages": 42,
"hitsPerPage": 24
},
"status": "success"
}
}About the Vivino API
Wine Search and Catalog
The search_wines endpoint accepts a query string — wine name, grape variety, or region — and returns paginated results with fields including id, name, seo_name, region, winery, vintages, statistics, and description. Pagination is 0-indexed via the page parameter, and nbHits and nbPages give you the full result-set shape. The explore_wines endpoint browses the full catalog ordered by popularity without a query term, using a 1-indexed page input that maps internally to 0-indexed pagination.
Wine and Winery Detail
get_wine_details takes either a wine_id (e.g. '1135067') or a wine_slug (e.g. 'cabernet-sauvignon-reserva-central-valley'). The response includes the image object with URL variations, a vintages array with per-year names and statistics, a winery object with website and description, and a statistics object covering ratings_count, ratings_average, and labels_count. get_winery_details requires a winery_slug (e.g. 'penfolds' or 'opus-one') and returns winery-level fields including winemaker, region, website, and aggregate statistics across all their wines.
Winery Search and Food Pairings
search_wineries accepts a winery name query and returns an items array of unique winery objects — each with id, name, seo_name, statistics, region, description, and website. The get_food_pairings endpoint takes a food_name string such as 'steak' or 'pasta' and returns wine objects whose names or associated metadata match that term, giving the same paginated hit structure as the search endpoints.
Coverage Notes
All endpoints return data as structured objects rather than free-form text, making the responses straightforward to parse into typed models. The statistics object appears at multiple levels — wine, vintage, winery, and region — so you can aggregate or filter at whichever granularity your application needs. Wine type_id is returned as an integer identifier; a mapping to human-readable type names (e.g. red, white, sparkling) is not included in the response schema directly.
The Vivino API is a managed, monitored endpoint for vivino.com — not a raw scraper you maintain. Every endpoint is automatically health-checked on a schedule, and when vivino.com changes and a check fails, the API is automatically queued for repair and re-verified. It is built to keep working as the site underneath it changes.
This isn't an official vivino.com API — it's an independent, maintained REST wrapper over public data. Where the source has no official API (or only a limited one), Parse gives you a stable contract over a source that never promised one, and keeps it current. Need a new endpoint or field? You can revise it yourself in plain English and the agent rebuilds it against the live site in minutes — contributing the change back to the shared API is free.
Will this API break when the source site changes?+
Is this an official API from the source site?+
Can I fix or extend this API myself if I need a new endpoint or field?+
What happens if I call an endpoint that has an issue?+
- Build a wine recommendation engine using
search_winesfiltered by region and sorted byratings_average. - Populate a wine cellar tracker by fetching full vintage arrays via
get_wine_details. - Create a food-and-wine pairing tool using
get_food_pairingswith ingredients from a recipe. - Display winery profiles in a travel app using
get_winery_detailsfields likewinemaker,website, andregion. - Index a wine catalog for autocomplete search by paginating through
explore_winessorted by popularity. - Compare winery statistics across producers using
search_wineriesto retrieveratings_countandwines_count. - Generate SEO content pages for wine varieties by pulling
description,grapes, andstatisticsfromget_wine_details.
| Tier | Price | Credits/month | Rate limit |
|---|---|---|---|
| Free | $0/mo | 100 | 5 req/min |
| Hobby | $30/mo | 1,000 | 20 req/min |
| Developer | $100/mo | 5,000 | 100 req/min |
One credit = one API call regardless of which marketplace API you call. Exceeding the rate limit returns a 429 response. Authenticate with the X-API-Key header.
Does Vivino have an official public developer API?+
What does `get_wine_details` return beyond basic wine info?+
vintages array with per-year statistics, an image object with multiple URL variations, a winery object that includes the winery's website and description, and a statistics block with ratings_count, ratings_average, and labels_count. Food pairings and grape data are also included in the response.How does pagination work across the search and explore endpoints?+
search_wines, search_wineries, and get_food_pairings use 0-indexed pagination via the page parameter. explore_wines accepts a 1-indexed page input. All paginated responses include nbHits, nbPages, and hitsPerPage so you can iterate through the full result set.Does the API return individual user reviews or tasting notes?+
ratings_count, ratings_average) and structured descriptions at the wine and winery level, but individual user reviews and tasting notes are not exposed. You can fork this API on Parse and revise it to add an endpoint targeting per-wine review data.