Whiskybase APIwhiskybase.com ↗
Access Whiskybase data via API: search whiskies, browse distilleries, check marketplace prices, get new releases, and fetch the Top 1000 ranked bottles.
What is the Whiskybase API?
The Whiskybase API exposes 6 endpoints covering the full Whiskybase catalogue — from keyword search and distillery browsing to live marketplace listings and the community-voted Top 1000. The get_top_1000_whiskies endpoint alone returns rank, age, strength, rating, and vote count for every bottle that has cleared the 15-vote threshold, giving you a clean, sortable benchmark of community consensus.
curl -X GET 'https://api.parse.bot/scraper/1fa3ba9e-3cd6-4ffe-b2d7-0da0f2ba5f66/search_whiskies?query=Ardbeg' \ -H 'X-API-Key: $PARSE_API_KEY'
Typed, relational, agent-ready
A generated client with real types, enums, and the links between objects — the structure a flat JSON response can't carry. Autocompletes in your editor and reads cleanly to coding agents.
- Fully typed · autocompletes
- Objects link to objects
- Typed errors & pagination
Typed Python client. Set up the SDK in your uv project, then pull this API’s typed client:
uv add parse-sdk uv run parse init uv run parse add --marketplace whiskybase-com-api
uv run parse add --marketplace pulls a pinned snapshot of this canonical API — it won’t change underneath you. To customize it, subscribe and swap to your own copy.
"""Walkthrough: Whiskybase SDK — search, browse, and rank whiskies."""
from parse_apis.whiskybase_api import Whiskybase, DistilleryNotFound
client = Whiskybase()
# Search for whiskies by keyword — limit caps total items fetched.
for whisky in client.whiskies.search(query="Laphroaig", limit=3):
print(whisky.name, whisky.strength, whisky.rating)
# Browse marketplace listings for a specific brand.
listing = client.listings.search(query="Macallan", limit=1).first()
if listing:
print(listing.whisky_name, listing.price, listing.seller)
# List distilleries and drill into the first one's whiskies.
distillery = client.distilleries.list(limit=1).first()
if distillery:
print(distillery.name, distillery.country, distillery.whiskies_count)
for dw in distillery.whiskies.list(limit=3):
print(dw.name, dw.strength, dw.rating)
# Typed error handling: catch not-found on an invalid distillery ID.
try:
bad = client.distillery(id="99999999")
bad.whiskies.list(limit=1).first()
except DistilleryNotFound as exc:
print(f"Distillery not found: {exc.distillery_id}")
# Top 1000 ranked whiskies globally.
for ranked in client.rankedwhiskies.list(limit=5):
print(ranked.rank, ranked.name, ranked.rating, ranked.votes)
print("exercised: whiskies.search / listings.search / distilleries.list / distillery.whiskies.list / rankedwhiskies.list")
Full-text search over the Whiskybase bottle database. Returns matching whiskies with name, brand, strength, rating, and photo URL. Sorted by relevance. Paginates server-side but this endpoint returns one page of up to 25 results.
| Param | Type | Description |
|---|---|---|
| queryrequired | string | Search keyword to match against whisky names and brands |
{
"type": "object",
"fields": {
"items": "array of whisky objects with id, name, brand, display_name, age, strength, bottle_size, vintage_year, bottle_year, rating, url, photo",
"total": "integer total number of matching results"
},
"sample": {
"data": {
"items": [
{
"id": 152827,
"age": 5,
"url": "https://www.whiskybase.com/whiskies/whisky/152827",
"name": "Wee Beastie",
"brand": "Ardbeg",
"photo": "https://static.whiskybase.com/storage/whiskies/1/5/2827/366361-normal.png",
"rating": "83.87",
"strength": "47.4 %vol",
"bottle_size": "700 ml",
"bottle_year": 2020,
"display_name": "Ardbeg Wee Beastie",
"vintage_year": null
}
],
"total": 1502
},
"status": "success"
}
}About the Whiskybase API
Search and Discovery
The search_whiskies endpoint accepts a keyword — a distillery name, brand, or bottler — and returns an array of matching bottles. Each item includes id, name, brand, display_name, age, strength, bottle_size, vintage_year, bottle_year, rating, and a direct url back to the Whiskybase listing. The total field tells you how many records matched so you can gauge coverage before paginating.
Distilleries and Their Catalogues
get_distilleries returns every distillery on Whiskybase with name, country, and whiskies_count — useful for building a directory or scoping a research project by region. Once you have a distillery ID from that response, pass it to get_distillery_whiskies to pull every bottle associated with that producer, each carrying id, name, age, strength, and rating.
New Releases and Marketplace
get_new_releases lists the latest bottlings across the database. Supply an optional year parameter (e.g. 2024) to narrow results to a specific bottling year; each release object includes bottled, age, strength, size, and rating. For pricing data, get_marketplace_listings returns active buy/sell listings with price, seller, and rating. Pass an optional query string to filter by bottler or distillery name, or omit it to retrieve the most recent listings across the whole market.
Top 1000 Rankings
get_top_1000_whiskies fetches Whiskybase's community ranking. Only bottles with 15 or more community votes are included, so low-sample outliers are filtered out automatically. Response fields are rank, id, name, age, strength, rating, and votes — enough to build leaderboards, track consensus shifts, or benchmark a specific bottle against the broader field.
The Whiskybase API is a managed, monitored endpoint for whiskybase.com — not a raw scraper you maintain. Every endpoint is automatically health-checked on a schedule, and when whiskybase.com changes and a check fails, the API is automatically queued for repair and re-verified. It is built to keep working as the site underneath it changes.
This isn't an official whiskybase.com API — it's an independent, maintained REST wrapper over public data. Where the source has no official API (or only a limited one), Parse gives you a stable contract over a source that never promised one, and keeps it current. Need a new endpoint or field? You can revise it yourself in plain English and the agent rebuilds it against the live site in minutes — contributing the change back to the shared API is free.
Will this API break when the source site changes?+
Is this an official API from the source site?+
Can I fix or extend this API myself if I need a new endpoint or field?+
What happens if I call an endpoint that has an issue?+
- Build a whisky price tracker by polling
get_marketplace_listingsfor a specific distillery name over time. - Populate a bottle database with distillery-level catalogues using
get_distilleriesandget_distillery_whiskiesin sequence. - Generate a 'top-rated this year' newsletter section by combining
get_new_releases(filtered by year) with ratings fromget_top_1000_whiskies. - Run competitive shelf analysis by searching multiple brand names via
search_whiskiesand comparing average ratings. - Build a country-filtered distillery directory using the
countryfield fromget_distilleries. - Flag newly listed high-rated bottles for auction or investment watchlists by crossing
get_marketplace_listingsresults againstget_top_1000_whiskiesIDs. - Aggregate vintage coverage per distillery by collecting
vintage_yearandbottle_yearfields fromsearch_whiskiesresults.
| Tier | Price | Credits/month | Rate limit |
|---|---|---|---|
| Free | $0/mo | 100 | 5 req/min |
| Hobby | $30/mo | 1,000 | 20 req/min |
| Developer | $100/mo | 5,000 | 100 req/min |
One credit = one API call regardless of which marketplace API you call. Exceeding the rate limit returns a 429 response. Authenticate with the X-API-Key header.
Does Whiskybase have an official developer API?+
What does `get_top_1000_whiskies` return and how is the ranking determined?+
rank, id, name, age, strength, rating, and votes. Only bottles with 15 or more votes are included, so bottles with very few ratings do not appear even if their average score is high.Can I filter marketplace listings by country, price range, or bottle size?+
get_marketplace_listings endpoint supports only a keyword query filter; there are no parameters for country, price range, or bottle size. The API covers listing-level fields including price, seller, rating, and whisky_name. You can fork it on Parse and revise it to add those filter parameters if your use case requires them.Does the API return tasting notes, flavour profiles, or individual user reviews?+
How fresh is the marketplace listing data?+
get_marketplace_listings endpoint reflects active listings on Whiskybase at the time of the request. Because listings are user-posted and can be added, updated, or removed at any time, the data represents a point-in-time snapshot. Polling at regular intervals is the practical way to detect price changes or new listings for a given bottle.