GET /wine

Get information about a specific wine including Wine Lister scores, Wine Lister indicators, and drinking advice.

Query string parameters

Paramter	Type	Optional	Info
id	Integer	Yes	Wine Lister unique wine id (Note, a single Wine Lister wine id can have multiple vinages)
title	String	Yes	See below on title matching
colour	String	Yes
country	String	Yes
vintage	String	Yes	'NV' for non-vintage or vintage year, e.g. '2013'. If no vintage is specified we will return wine level data

For the best results we recommend storing and using our Wine Lister wine id to use as the parameter in your get request.

Wine title matching

Where the Wine Lister wine id is unknown, provide a wine title, country and colour and we will match it to one of our wines.

Your wine title should be as full as possible. The more of the following you include the higher the likelihood of a correct match: producer name, wine name, appellation, cru, sugar level e.g. auslese or SGN, and other designations such as reserva or vieilles vignes. For the best results set the title parameter as you would expect the wine to be displayed, i.e. including all punctuation.
The title parameter, as with all parameters should be UTF-8 url-encoded. It is not case sensitive.

If a unique Wine Lister wine matching the supplied wine cannot be found, an error is returned. See possible error responses below.

(Whilst we support wine title matching, we cannot guarantee that our wine title or your wine title will not change in the future, and therefore that the wine returned will always be the same.)

Response body parameters

Paramter	Type	Values	Null allowed	Info
id	Integer		no
vintage	String	'wine','NV',[vintage e.g. '2013']	no	If no vintage is specified wine level data will be returned and this value will be 'wine'
title	String
colour	String	'red','white','rosé'	no
country	String		no
region_appellation	String		no	Includes classification e.g. 'Margaux AOP'
url	String		no
indicators	Array	'investment_staple', 'value_pick', 'hidden_gem', 'buzz_brand'	Yes
drinking_window_open	Integer		Yes	From average of our partner critics' suggested drinking windows
drinking_window_close	Integer		Yes	From average of our partner critics' suggested drinking windows
drinking_advice	String	'Lay down', 'Ready but will improve', 'Drink now'	Yes
wine_lister_score	Integer		Yes	Where we have insufficient data to compute a wine lister score, this will be null
quality_score	Integer		Yes	Where we have insufficient data to compute a quality score, this will be null
brand_score	Integer		Yes	Where we have insufficient data to compute a brand score, this will be null
economics_score	Integer		Yes	Where we have insufficient data to compute an economics score, this will be null

Example request

curl | php

curl --request GET -G \
--url 'https://api.wine-lister.com/1.0/wine' \
--data-urlencode 'title=Château Margaux Premier Cru' \
--data-urlencode 'country=france' \
--data-urlencode 'colour=red' \
--data-urlencode 'vintage=2013' \
--user 'anystring:<your_api_secret_key>'

Example request 2 (produces the same response)

curl | php

curl --request GET \
--url 'https://api.wine-lister.com/1.0/wine?id=3720&vintage=2013' \
--user 'anystring:<your_api_secret_key>'

Example response

 
  {
  "id": 3720,
  "vintage": "2013",
  "title": "Château Margaux Premier Cru",
  "colour": "red",
  "country": "France",
  "region_appellation": "Margaux AOP",
  "url": "https://www.wine-lister.com/wine/3720/vintage/2013",
  "indicators":["buzz_brand"],
  "drinking_window_open": 2020,
  "drinking_window_close": 2029,
  "drinking_advice": "Lay down",
  "wine_lister_score": 939,
  "quality_score": 878,
  "brand_score": 999,
  "economics_score": 972
  }

Error response

In addition to the general error responses the following error responses can be returned

Status code
404	Not found	{"error":"No unique wine found for the specified parameters"}