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.

{
	"url": string,
  "summary": {
    "name": string,
    "type": string,
    "rating": float,
    "rating_count": integer,
    "country": string,
    "price": float,           // Median price from Vivino
    "currency": string,
    "taste_profile": object,  // E.g., "bold" can be true (rated over 3.15) or false
    "flavors": array,         // Ordered by most mentions
    "pairings": array,
  },
  "wine": object,
  "region": object,
  "country": object,
	"vintages": array,          // Available vintages (years)
  "prices": array,            // Available prices on Vivino, year 0 is generic pricing
  "taste": array,             // Structure and flavor profile
  "highlights": array,        // Special mentions, awards, etc.
  "reviews": array
}

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

{
	"url": "https://www.vivino.com/CA/en/w/779452",
	"summary": {
		"name": "Clos de l'Oratoire des Papes Châteauneuf-du-Pape",
		"type": "Red",
		"rating": 4.2,
		"rating_count": 40926,
		"country": "France",
		"price": "CAD",
		"currency": null,
		"taste_profile": {
			"light": false,
			"bold": true,
			"smooth": false,
			"tannic": false,
			"dry": true,
			"sweet": false,
			"soft": false,
			"acidic": false,
			"fizzy": false
		},
		"flavors": [
			"Oak",
			"Red fruit",
			"Black fruit",
			"Earth",
			"Spices"
		],
		"pairings": [
			"Lamb",
			"Pork",
			"Poultry"
		]
	}
}

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.

{
	"id": integer,
	"name": string,
	"seo_name": string,
	"type_id": integer,
	"vintage_type": integer,
	"is_natural": boolean,
	"region": object,
  "review_status": integer,
	"winery": object,
  "image": object,
  "statistics": object,
  "rank": integer,
	"hidden": boolean,
	"vintages": object,
  "style": object,
	"has_valid_ratings": true
}

Search Wines returns:

When "Summary results" is TRUE.

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

Explore Wines returns:

Each entry is a wine with multiple vintages.

When "Summary results" is TRUE.

{
	"url": "http://www.vivino.com/wines/172762328",
	"name": "Luigi Bosca Paraiso 2020",
	"country": "Argentina",
	"price": 129.99,
	"discount": 27.78,
	"score": "Amazing Value!",
	"rating": 4.9,
	"image": "https//images.vivino.com/thumbs/_Bf6JTwYRpSX6eKUiLIvNA_pl_480x640.png",
	"taste": {
		"acidity": 3.07,
		"fizziness": null,
		"intensity": 4.22,
		"sweetness": 1.86,
		"tannin": 3.32,
		"user_structure_count": 40,
		"calculated_structure_count": 5  // Total votes = 40 + 5 = 45
	}
}

When "Summary results" is FALSE.

{
  "summary": object,                // Same as previous example
  "vintage": {                      // Qualitative data
    "id": integer,
    "seo_name": string,
    "name": string,
    "statistics": object,
    "image": object,
    "wine": object,                 // Region, winery, flavor, rankings...
    "year": integer,
    "grapes": array,
    "has_valid_ratings": boolean
  },
  "price": {                        // Main price
    "id": integer,
    "merchant_id": integer,
    "amount": float,
    "discounted_from": integer,
    "discount_percent": float,
    "type": string,
    "sku": string,
    "url": string,
    "visibility": integer,
    "bottle_type_id": integer,
    "currency": object,
    "xms": float,
    "xmphs": boolean,
    "price_group_id": array,
    "vfm_score": float,
    "vfm_category": object,
    "bottle_type": object
  },
  "prices": [                       // All prices
    {
      "id": integer,
      "merchant_id": integer,
      "amount": float,
      "discounted_from": integer,
      "discount_percent": float,
      "type": string,
      "sku": string,
      "url": string,
      "visibility": integer,
      "bottle_type_id": integer,
      "currency": object,
      "xms": float,
      "xmphs": boolean,
      "price_group_id": [string],
      "vfm_score": float,
      "vfm_category": object,
      "bottle_type": object
    },
    ...
  ]
}

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!