Whisky Identification
Uniquely identifying a whisky can be a time-consuming task. But everything that follows, from valuation to product presentation, depends on that first crucial step. Our Whisky Bottle Identification endpoints are built to make whisky identification faster and more reliable.
The endpoints start from the information you already have: a few words, a full description, or a photo. Each one returns a short list of the most likely whisky releases, so near-duplicates stay visible and you can confirm the one you mean. Every possible match carries a Whisky ID. That ID is what you store, and what you send to the Whisky Bottle endpoints for ratings, auction results, and retail prices.
| Endpoint | Your starting point | What you get back |
|---|---|---|
| Bottle Search | A short query: brand, release name, or part of a title | A paginated list, best matches first |
| Bottle Match | A full listing: text descriptions, or the attributes you already store | The closest releases, each with a similarity score from 0 to 1 |
| Bottle Scan | A photo of the bottle | The closest releases, each with a similarity score from 0 to 1 |
Bottle Search
Bottle Search fits a lookup, not a finished catalogue record. Use it for the search boxes in your tools, for a colleague answering "do we have the Vibrant Oak?", or for a product title that is only a brand and a release name.
It uses the same engine as the Whiskystats Search, so you can try a query on the website before you send it to the API. Our best-practice advice on searching whiskies covers the queries that behave well.
Send a free-text query and receive a list of matching releases.
The list is ordered by relevance, ready to show on a search results page.
total tells you whether the query was specific or still broad.
page and pages tell you where you are in that list.
results is the current page.
Code
In this example the 700ml and the 750ml are both matches.
The name on each possible match includes the size.
Show whisky_name and whisky_image_url to the person choosing, then store the whisky_id they confirm.
Bottle Match
Bottle Match fits when the bottle is already described in words like for an auction lot or a shop listing, e.g. "Balvenie 1937 50 Year Old, distilled 1937, bottled 1987, 42% ABV, 75cl". The endpoint compares that description with our whisky catalogue and returns the closest matches, with a similarity score you can use to decide what needs a human look.
Put the full text in description.
Include the details that actually distinguish the whisky: brand, name, age, bottle size, strength, vintage year, bottling year, and cask/batch information.
If you already store those as separate fields, write them into the same text as key-value pairs.
Field names from the Bottle Match reference (brand, age, bottle_size, and the others listed there) are the ones our algorithms read most reliably.
results holds the top matches, highest score first.
A similarity score of 1 means the description and the matched release fully line up.
total is the number of matches returned.
Code
A high top score and a big distance to the second-best match signal that you can attach the Whisky ID with little review.
When the top scores sit close together, compare whisky_name and the image before you advance.
Bottle Scan
Use Bottle Scan when you have an image of the whisky bottle itself.
Send either a base64-encoded image or a publicly accessible image_url.
The response has the same shape as Bottle Match.
score is the visual similarity scaling from 0 to 1, and results is sorted from the closest image to the next.
Note that different bottle sizes of the same release can both score highly, because the bottles look alike.
whisky_name includes the size, so you can separate them before you attach the Whisky ID.
The Whisky ID you keep
A Whisky ID is the permanent connector for a whisky in our database.
The identification endpoints return it as whisky_id.
There are two forms, Whiskybase IDs (prefix WB) and Bottle Group IDs (prefix BG). See our Whisky IDs documentation for more details.
With that ID, you can call the Whisky Bottle endpoints to retrieve all sorts of release-level information, such as bottling details, auction valuation, retail prices or whisky ratings.
You can paste a Whisky ID into the Whiskystats Search to look up that whisky directly on our website.