Vivino

⭐ For bulk mode, parallel processing, a higher maximum and additional filters (grapes, regions, countries, etc.), please use canadesk/vivino-bulk!

🛑 Vivino USA is restricted to IPs from the United States (proxy settings)! For that reason, default is set to Canada. Other locations can be accessed from anywhere.

Parameters

[Input]

• Process (Select)

  • Get Wines Details

    Returns information about a specific wine:

    • Keyword (string)

      ⚡ Highly recommended to use URLs, especially when looking for a specific vintage (year).

      If you use a URL, it must be exact. You can include "?year=" with the year to specify the vintage (required to get reviews only for a specific year).

      Expected format: https://www.vivino.com/CA/en/w/2141966 (ID)

      If you use search terms, the process "Search Wines" will run first then return data for the first hit.

    • Reviews filter (array)

      Must be an array with one or more of the following values: [1, 2, 3, 4, 5].

      For example, [1, 3] will return reviews with a rating of 1 or 3.

      Leave empty or set them all to ignore the filter.

  • Get Wines Reviews

    Similar to "Get Wines Details", but only returns reviews.

  • Get Winery Details

    Returns general information and the wines produced by a specific winery:

    • Keyword (string)

      Must be a URL. By default, wines are sorted by best ratings. Add "?sort=most_rated" to change it.

      Expected format: https://www.vivino.com/wineries/luigi-bosca (name) or https://www.vivino.com/wineries/2485 (ID)

  • Search Wines

    Returns wines based on search terms:

    • Keyword (string)

      Returns the first search result found for the keyword(s).

    • Search filter (string)

      The search result must contain the exact value (case-sensitive) to be included. This is checked after the search!

      For example, "cork" is likely to exclude non-cork closures.

  • Explore Wines

    Returns wines based on filters:

    • Wine types (array)

      Must be an array with one or more of the following values: ["Red", "White", "Rose", "Sparkling", "Dessert", "Fortified"].

      Leave empty or set them all to ignore the filter.

    • Minimum rating (string)

      Must be a number (integer or float) between 1 and 5.

    • Minimum/Maximum price (integer)

      This will be applied in the country local currency!

    • Discounted (boolean)

    For more filters, please use canadesk/vivino-bulk.

  • Get Vivino Catalog

    Returns constants used by Vivino to map Countries, Foods, Grapes, Wine styles and Regions.

• Market (select)

  Choose from the available countries. This will set default domain, country, locale and currency.

  For the United States, your proxy IP must originate from the USA!

• Summarized results (boolean)

  🛑 Returns raw results, or a subset. See examples.

• Maximum (integer)

  Limits the number of results to be returned (up to 200).

  For a higher maximum and parallel processing, please use canadesk/vivino-bulk.

• Save on usage cost (boolean) 💸

  When enabled, all results will be wrapped in a single row to reduce "Dataset writes" cost.

• Retries (integer)

  Waiting time between requests.

[Output]

Get Wine Details/Reviews returns:

When the year is specified (either in keywords, or "?year=" in URLs), only the data relevant to the target vintage is available.

For process "Get Wine Reviews", taste and highlights are skipped and only some of the summary data is available.

1{
2	"url": string,
3  "summary": {
4    "name": string,
5    "type": string,
6    "rating": float,
7    "rating_count": integer,
8    "country": string,
9    "price": float,           // Median price from Vivino
10    "currency": string,
11    "taste_profile": object,  // E.g., "bold" can be true (rated over 3.15) or false
12    "flavors": array,         // Ordered by most mentions
13    "pairings": array,
14  },
15  "wine": object,
16  "region": object,
17  "country": object,
18	"vintages": array,          // Available vintages (years)
19  "prices": array,            // Available prices on Vivino, year 0 is generic pricing
20  "taste": array,             // Structure and flavor profile
21  "highlights": array,        // Special mentions, awards, etc.
22  "reviews": array
23}

When "Summary Results" is TRUE, only url and summary are returned.

1{
2	"url": "https://www.vivino.com/CA/en/w/779452",
3	"summary": {
4		"name": "Clos de l'Oratoire des Papes Châteauneuf-du-Pape",
5		"type": "Red",
6		"rating": 4.2,
7		"rating_count": 40926,
8		"country": "France",
9		"price": "CAD",
10		"currency": null,
11		"taste_profile": {
12			"light": false,
13			"bold": true,
14			"smooth": false,
15			"tannic": false,
16			"dry": true,
17			"sweet": false,
18			"soft": false,
19			"acidic": false,
20			"fizzy": false
21		},
22		"flavors": [
23			"Oak",
24			"Red fruit",
25			"Black fruit",
26			"Earth",
27			"Spices"
28		],
29		"pairings": [
30			"Lamb",
31			"Pork",
32			"Poultry"
33		]
34	}
35}

Get Winery Details returns raw data:

Each entry is a wine with multiple vintages.

Vintage prices are also fetched when "has_valid_ratings" is true for the wine.

1{
2	"id": integer,
3	"name": string,
4	"seo_name": string,
5	"type_id": integer,
6	"vintage_type": integer,
7	"is_natural": boolean,
8	"region": object,
9  "review_status": integer,
10	"winery": object,
11  "image": object,
12  "statistics": object,
13  "rank": integer,
14	"hidden": boolean,
15	"vintages": object,
16  "style": object,
17	"has_valid_ratings": true
18}

Search Wines returns:

When "Summary results" is TRUE.

1{
2  "url": "https://www.vivino.com/CA/en/w/7753397?ref=nav-search",
3  "name": "fleur-de-france-moelleux-white",
4  "type": "Dessert",
5  "rating": 3.9,
6  "country": "France",
7  "winery": "Tresch Clerget",
8  "alcoholLevel": 10.5,
9  "image": "https://images.vivino.com/labels/qTrXHjpmTbq__eXk-lTQtQ.jpg"
10}

Explore Wines returns:

Each entry is a wine with multiple vintages.

When "Summary results" is TRUE.

1{
2	"url": "http://www.vivino.com/wines/172762328",
3	"name": "Luigi Bosca Paraiso 2020",
4	"country": "Argentina",
5	"price": 129.99,
6	"discount": 27.78,
7	"score": "Amazing Value!",
8	"rating": 4.9,
9	"image": "https//images.vivino.com/thumbs/_Bf6JTwYRpSX6eKUiLIvNA_pl_480x640.png",
10	"taste": {
11		"acidity": 3.07,
12		"fizziness": null,
13		"intensity": 4.22,
14		"sweetness": 1.86,
15		"tannin": 3.32,
16		"user_structure_count": 40,
17		"calculated_structure_count": 5  // Total votes = 40 + 5 = 45
18	}
19}

When "Summary results" is FALSE.

1{
2  "summary": object,                // Same as previous example
3  "vintage": {                      // Qualitative data
4    "id": integer,
5    "seo_name": string,
6    "name": string,
7    "statistics": object,
8    "image": object,
9    "wine": object,                 // Region, winery, flavor, rankings...
10    "year": integer,
11    "grapes": array,
12    "has_valid_ratings": boolean
13  },
14  "price": {                        // Main price
15    "id": integer,
16    "merchant_id": integer,
17    "amount": float,
18    "discounted_from": integer,
19    "discount_percent": float,
20    "type": string,
21    "sku": string,
22    "url": string,
23    "visibility": integer,
24    "bottle_type_id": integer,
25    "currency": object,
26    "xms": float,
27    "xmphs": boolean,
28    "price_group_id": array,
29    "vfm_score": float,
30    "vfm_category": object,
31    "bottle_type": object
32  },
33  "prices": [                       // All prices
34    {
35      "id": integer,
36      "merchant_id": integer,
37      "amount": float,
38      "discounted_from": integer,
39      "discount_percent": float,
40      "type": string,
41      "sku": string,
42      "url": string,
43      "visibility": integer,
44      "bottle_type_id": integer,
45      "currency": object,
46      "xms": float,
47      "xmphs": boolean,
48      "price_group_id": [string],
49      "vfm_score": float,
50      "vfm_category": object,
51      "bottle_type": object
52    },
53    ...
54  ]
55}

Support

Always use a strong proxy, and make sure to wait long enough between requests!

Open a new issue for bugs and feature requests. Please share your Run URL and Input.

Cheers!