GET /wine

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

Query string parameters

ParamterTypeOptionalInfo
idIntegerYesWine Lister unique wine id (Note, a single Wine Lister wine id can have multiple vinages)
titleStringYesSee below on title matching
colourStringYes
countryStringYes
vintageStringYes'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

ParamterTypeValuesNull allowedInfo
idIntegerno
vintageString'wine','NV',[vintage e.g. '2013']noIf no vintage is specified wine level data will be returned and this value will be 'wine'
titleString
colourString'red','white','rosé'no
countryStringno
region_appellationStringnoIncludes classification e.g. 'Margaux AOP'
urlStringno
indicatorsArray'investment_staple', 'value_pick', 'hidden_gem', 'buzz_brand'Yes
drinking_window_openIntegerYesFrom average of our partner critics' suggested drinking windows
drinking_window_closeIntegerYesFrom average of our partner critics' suggested drinking windows
drinking_adviceString'Lay down', 'Ready but will improve', 'Drink now'Yes
wine_lister_scoreIntegerYesWhere we have insufficient data to compute a wine lister score, this will be null
quality_scoreIntegerYesWhere we have insufficient data to compute a quality score, this will be null
brand_scoreIntegerYesWhere we have insufficient data to compute a brand score, this will be null
economics_scoreIntegerYesWhere we have insufficient data to compute an economics score, this will be null

Example request

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 --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": "Marguax 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
404Not found{"error":"No unique wine found for the specified parameters"}

Try it - You must be enrolled and logged in to try here



Result