Search, match, and bottle detail endpoints.
Bottle Search
Searches whiskies based on a free-text query.
Returns a list of the most likely matching whiskies sorted by relevance.
Intended for scenarios where you only know a part of the whisky name (e.g. brand and release name), but not all whisky details. This is utilizing the Whiskystats Search, so you can test your queries on our website first.
query Parameters
querystring · requiredThe free-text search query. Conduct our best practive advice on searching whiskies to get the best results.
Default: Macallan Vibrant Oakpageinteger · requiredThe page number to return for paginated search results (starts at 1).
Default: 1
Headers
Authorizationstring · requiredThe
Authorizationheader is used to authenticate with the API using your API key. Value is of the formatBearer YOUR_KEY_HERE.
Responses
Search Results
totalintegerTotal number of matching whiskies in the database.
pageintegerCurrent page number in the paginated search results.
pagesintegerTotal number of pages available for the current search query.
resultsobject[]Paginated list of matching whiskies sorted by relevance.
Bottle Match
Searches whiskies based on a full text description.
Returns a list of the most likely matching whiskies sorted by the match score which ranges from 0 to 1 where 1 indicates a perfect match.
Intended for scenarios where you have the complete text description of a whisky bottle, not just a short name.
If you already hold structured whisky data on your side, you can provide those key-value pairs in the description text field. That helps our algorithms pick up the correct attributes.
For best performance, align field names with our conventions:
- brand: The distillery or brand name.
- bottler: The name of the independent bottler.
- bottle_for: For whom (company/occasion) the whisky was bottled for.
- name: The bottling series/product name/edition.
- name_addition: Additional name information.
- vintage_year (four-digit integer): The year of distillation.
- bottle_year (four-digit integer): The year of bottling.
- age (integer): The age of the whisky in years.
- strength (numeric): The alcohol strength.
- strength_unit (string): Either '%vol', 'gradi' or 'proof'.
- cask_number (string): Identifier or number of the cask(s).
- batch_number (string): Identifier or number of the batch.
- bottle_size (integer): The size of the bottle in millilitres.
- bottle_count (integer): The number of released bottles.
Headers
Authorizationstring · requiredThe
Authorizationheader is used to authenticate with the API using your API key. Value is of the formatBearer YOUR_KEY_HERE.
Request Body
descriptionstring · requiredComplete text description of a whisky bottle. Should contain all major details (brand, name, age, bottle size, alcohol strength, vintage year, bottling year, cask number, cask type, etc.). If you have structured data, you may embed key-value pairs using the field names documented above for best matching performance.
Responses
Match Results
totalintegerThe total number of top matching whiskies returned in the results.
resultsobject[]List of top matching whiskies sorted by match score.
Bottle Details
Returns bottling details and technical attributes of a whisky.
The response includes the Whisky ID, optional parent bottle group ID (when the bottling belongs to a bottle group), brand and bottling information, production characteristics, and image URLs.
If the Whisky ID is unknown, status code 404 is returned.
query Parameters
whisky_idstring · requiredThe Whisky ID.
Use "WB" as a prefix for Whiskybase IDs (e.g. "WB37719"). Use "BG" as a prefix for Whiskystats Bottle Group IDs (e.g. "BG124"). See our Documentation for more details.
Default: WB257657
Headers
Authorizationstring · requiredThe
Authorizationheader is used to authenticate with the API using your API key. Value is of the formatBearer YOUR_KEY_HERE.
Responses
Data Response
whisky_idstringThe Whisky ID for reference. In rare occassions, this might differ from the requested Whisky ID if that has become inactive. See our Documentation for more details.
parent_bottle_group_idstringIf the whisky is part of a bottle group, this is the respective Bottle Group ID. See our Documentation for more details.
brandstringThe brand or distillery name of the whisky.
bottlerstringThe bottler name, if available.
bottle_forstringThe entity or market this bottling was produced for, if available.
bottler_seriestringThe bottler's series or collection name.
namestringThe bottling name or release title.
ageintegerThe age statement in years, if available.
vintage_yearintegerThe distillation year, if available.
bottle_yearintegerThe bottling year, if available.
strengthnumberThe alcoholic strength value.
strength_unitstringThe unit of alcoholic strength (either "%vol" or "proof").
cask_numberstringThe cask number, if available.
cask_typestringThe cask type or maturation cask information, if available.
bottle_sizeintegerThe bottle volume in milliliters.
bottle_countintegerThe number of released bottles, if available.
bottle_codestringThe printed bottle code, if available.
barcodestringThe product barcode, if available.
caskstrengthbooleanWhether the whisky is bottled at cask strength.
singlecaskbooleanWhether the whisky is a single cask release.
coloredbooleanWhether the whisky is colored.
chillfilteredbooleanWhether the whisky is chillfiltered.
typestringThe whisky category (e.g. Single Malt).
whisky_image_urlstringURL of the full-size whisky image, if available.
whisky_thumbnail_urlstringURL of the thumbnail whisky image, if available.
whiskystats_urlstringThe Whiskystats URL for the requested Whisky ID.
whiskybase_urlstringThe Whiskybase URL for the requested Whisky ID (not available for Bottle Group IDs).
Auction Pricing
Returns the latest auction pricing summary of a whisky.
The response combines the latest market value, the most recent auction trade summary, the maximum auction price, and rolling 12-month auction statistics in the requested currency and price market. All price information are buyer prices (hammer price plus buyer fees).
If the Whisky ID is unknown, status code 404 is returned.
query Parameters
whisky_idstring · requiredThe Whisky ID.
Use "WB" as a prefix for Whiskybase IDs (e.g. "WB37719"). Use "BG" as a prefix for Whiskystats Bottle Group IDs (e.g. "BG124"). See our Documentation for more details.
Default: nullcurrency_codestring · requiredThree-character currency code (e.g. "EUR"). See our Documentation for more details.
Default: nullprice_market_codestringTwo-character price market code (e.g. "EU"). If provided, the response returns auction pricing data for the respective price market. If not provided, the response returns global auction pricing data. See our Documentation for more details.
Default: nullbottle_group_fallbackbooleanWhen
true, if the requested Whisky ID has no auction prices but its parent bottle group does, the response returns that parent group's auction pricing. Thewhisky_idin the response is then the parent bottle group's Whisky ID, not the requested Whisky ID. See our Documentation for more details.Default: false
Headers
Authorizationstring · requiredThe
Authorizationheader is used to authenticate with the API using your API key. Value is of the formatBearer YOUR_KEY_HERE.
Responses
Data Response
whisky_idstringThe Whisky ID for reference. In rare occassions, this might differ from the requested Whisky ID if that has become inactive or if
bottle_group_fallbackwastrueand auction data was taken from the parent bottle group. See our Documentation for more details.currency_codestringThe requested currency code for reference.
price_market_codestringIf provided in the request, the requested price market code for reference.
market_valuenumberThe latest market value (90-day moving average of auction buyer prices) of the whisky in the requested currency.
market_value_datestring · dateThe date of the latest auction trade used for the market value.
market_value_tradesnumberThe number of auction trades used to calculate the latest market value.
total_tradesnumberThe all-time total number of auction trades available for the whisky.
latest_auction_priceobjectSummary of the most recent auction trade date.
max_auction_priceobjectSummary of the all-time highest auction buyer price.
latest_12mobjectRolling 12-month auction pricing statistics.
Retail Pricing
Returns price summary statistics of current retail listings in the requested currency and price market.
If the Whisky ID is unknown, status code 404 is returned.
query Parameters
whisky_idstring · requiredThe Whisky ID.
Use "WB" as a prefix for Whiskybase IDs (e.g. "WB37719"). Use "BG" as a prefix for Whiskystats Bottle Group IDs (e.g. "BG124"). See our Documentation for more details.
Default: nullcurrency_codestring · requiredThree-character currency code (e.g. "EUR"). See our Documentation for more details.
Default: nullprice_market_codestringTwo-character price market code (e.g. "EU"). If provided, the response returns retail pricing data for the respective price market. If not provided, the response returns global retail pricing data. See our Documentation for more details.
Default: nullbottle_group_fallbackbooleanWhen
true, if the requested Whisky ID has no retail prices but its parent bottle group does, the response returns that parent group's retail pricing. Thewhisky_idin the response is then the parent bottle group's Whisky ID, not the requested Whisky ID. See our Documentation for more details.Default: false
Headers
Authorizationstring · requiredThe
Authorizationheader is used to authenticate with the API using your API key. Value is of the formatBearer YOUR_KEY_HERE.
Responses
Data Response
whisky_idstringThe Whisky ID for reference. In rare occassions, this might differ from the requested Whisky ID if that has become inactive or if
bottle_group_fallbackwastrueand retail data was taken from the parent bottle group. See our Documentation for more details.currency_codestringThe requested currency code for reference.
price_market_codestringIf provided in the request, the requested price market code for reference.
number_of_retail_listingsnumberThe number of current global retail listings.
retail_price_minnumberThe minimum price of all current retail listings of the whisky in the requested currency.
retail_price_qrt1numberThe first quartile (25th percentile) price of all current retail listings of the whisky in the requested currency.
retail_price_avgnumberThe average price of all current retail listings of the whisky in the requested currency.
retail_price_qrt2numberThe second quartile (50th percentile, median) price of all current retail listings of the whisky in the requested currency.
retail_price_qrt3numberThe third quartile (75th percentile) price of all current retail listings of the whisky in the requested currency.
retail_price_maxnumberThe maximum price of all current retail listings of the whisky in the requested currency.
Whiskybase Rating
Returns the average Whiskybase rating.
The highest and lowest ratings are removed when calculating the average but not for the rating count.
If the Whisky ID is unknown, status code 404 is returned.
query Parameters
whisky_idstring · requiredThe Whisky ID.
Use "WB" as a prefix for Whiskybase IDs (e.g. "WB37719"). Use "BG" as a prefix for Whiskystats Bottle Group IDs (e.g. "BG124"). See our Documentation for more details.
Default: WB37719bottle_group_fallbackbooleanWhen
true, if the requested Whisky ID has no Whiskybase ratings but its parent bottle group does, the response returns that parent group's rating. Thewhisky_idin the response is then the parent bottle group's Whisky ID, not the requested Whisky ID. See our Documentation for more details.Default: false
Headers
Authorizationstring · requiredThe
Authorizationheader is used to authenticate with the API using your API key. Value is of the formatBearer YOUR_KEY_HERE.
Responses
Data Response
whisky_idstringThe Whisky ID for reference. In rare occassions, this might differ from the requested Whisky ID if that has become inactive or if
bottle_group_fallbackwastrueand Whiskybase ratings were taken from the parent bottle group. See our Documentation for more details.whiskybase_ratingnumberThe Whiskybase rating of the whisky.
whiskybase_rating_countnumberThe number of Whiskybase ratings.