# Whisky Hunter

> Track the secondary whisky market with Whisky Hunter. Compare what the online auction houses charge to buy and to sell, follow any distillery's prices month by month (the cheapest, mean and dearest bottle, the money its bottles fetched and how many sold), put distilleries or auction houses side by side over any period, and read the whole market's monthly volume back to 2005. No account or API key is required.

App · Food & Drink · 10 actions. Web page: https://docs.lodol.com/docs/integrations/whisky-hunter

## Actions

### Compare auction houses

Add each auction house up over a period and rank them side by side: what each took, how many lots it sold, its mean winning bid and its share of the houses being compared. Leave the houses empty to rank the whole market.

**Inputs**

- Auction houses (`auctions`, list): The auction houses to put side by side. Leave empty to rank every house in the market against the others.
- From (`from_date`, date): Only include months from this one onwards. Any day in the month works -- the results describe whole months, so a date in the middle of one keeps that whole month. Leave empty to start at the earliest results Whisky Hunter has, which reach back to November 2005.
- To (`to_date`, date): Only include months up to and including this one. Any day in the month works. Leave empty to run to the most recent month.
- Rank by (`sort_by`, text): Which figure to rank them on. One of: `trading_volume_gbp` (Trading volume), `lots_count` (Lots sold), `winning_bid_mean_gbp` (Mean winning bid), `name`. Default: `trading_volume_gbp`.
- Sort direction (`sort_direction`, text): Which way to rank them. Largest first by default. One of: `ascending` (Ascending (A-Z, smallest first)), `descending` (Descending (Z-A, largest first)). Default: `descending`.

**Outputs**

- `auctions` (list): The auction houses, ranked as asked
- `count` (number): How many auction houses were compared
- `first_month` (text): The earliest month covered, as 'YYYY-MM'
- `last_month` (text): The latest month covered, as 'YYYY-MM'
- `lots_count` (number): How many lots they sold between them
- `trading_volume_gbp` (number): What every house being compared took over the period, in GBP
- `winning_bid_mean_gbp` (number): Their combined mean winning bid, in GBP

**Example output**

```json
{
  "auctions": [
    {
      "first_month": "2024-01",
      "last_month": "2024-08",
      "lots_count": 59058,
      "lots_share_percent": 14.13,
      "months_count": 8,
      "name": "Whisky Auctioneer",
      "slug": "whiskyauctioneer",
      "trading_volume_gbp": 23324574.0,
      "volume_share_percent": 22.65,
      "winning_bid_mean_gbp": 394.94
    }
  ],
  "count": 1,
  "first_month": "2024-01",
  "last_month": "2024-08",
  "lots_count": 417939,
  "trading_volume_gbp": 102983546.05,
  "winning_bid_mean_gbp": 246.41
}
```

### Compare distilleries

Add several distilleries up over a period and rank them side by side: what each one's bottles fetched, how many sold, its mean, cheapest and dearest winning bid, and its share of the distilleries being compared.

**Inputs**

- Distilleries (`distilleries`, list, required): The distilleries to put side by side. Choose between 2 and 10 of them -- Whisky Hunter serves one distillery per request, so this step makes one call for each.
- From (`from_date`, date): Only include months from this one onwards. Any day in the month works -- the results describe whole months, so a date in the middle of one keeps that whole month. Leave empty to start at the earliest results Whisky Hunter has, which reach back to November 2005.
- To (`to_date`, date): Only include months up to and including this one. Any day in the month works. Leave empty to run to the most recent month.
- Rank by (`sort_by`, text): Which figure to rank them on. One of: `trading_volume_gbp` (Trading volume), `lots_count` (Lots sold), `winning_bid_mean_gbp` (Mean winning bid), `name`. Default: `trading_volume_gbp`.
- Sort direction (`sort_direction`, text): Which way to rank them. Largest first by default. One of: `ascending` (Ascending (A-Z, smallest first)), `descending` (Descending (Z-A, largest first)). Default: `descending`.

**Outputs**

- `count` (number): How many distilleries were compared
- `distilleries` (list): The distilleries, ranked as asked
- `first_month` (text): The earliest month covered, as 'YYYY-MM'
- `last_month` (text): The latest month covered, as 'YYYY-MM'
- `lots_count` (number): How many of their bottles sold between them
- `trading_volume_gbp` (number): What every distillery being compared fetched over the period, in GBP
- `winning_bid_mean_gbp` (number): Their combined mean winning bid, in GBP

**Example output**

```json
{
  "count": 1,
  "distilleries": [
    {
      "first_month": "2024-01",
      "last_month": "2024-08",
      "lots_count": 30026,
      "lots_share_percent": 57.18,
      "months_count": 8,
      "name": "Macallan",
      "slug": "macallan",
      "trading_volume_gbp": 17791527.95,
      "volume_share_percent": 70.72,
      "winning_bid_max_gbp": 151657.5,
      "winning_bid_mean_gbp": 592.54,
      "winning_bid_min_gbp": 0.9
    }
  ],
  "first_month": "2024-01",
  "last_month": "2024-08",
  "lots_count": 52510,
  "trading_volume_gbp": 25159063.88,
  "winning_bid_mean_gbp": 479.13
}
```

### Get a distillery

Get one distillery's name, slug and country. Use it to turn a slug from any other step into a name, or to confirm a distillery is one Whisky Hunter tracks before asking for its results.

**Inputs**

- Distillery (`distillery`, text, required): The distillery to report on. The list fills with every distillery Whisky Hunter tracks once the app is connected.

**Outputs**

- `country` (text): Where it distils, e.g. 'Scotland'
- `name` (text): The distillery's name, e.g. 'Ardbeg'
- `slug` (text): The distillery's identifier, e.g. 'ardbeg'. Every action here that takes a distillery takes this.

**Example output**

```json
{
  "country": "Scotland",
  "name": "Ardbeg",
  "slug": "ardbeg"
}
```

### Get a distillery's monthly results

Get one distillery's auction results month by month: the cheapest, mean and dearest bottle sold, the money its bottles fetched and how many of them sold, all in GBP and across every auction house. Narrow it to a date range, and read the whole period's totals off the same result.

**Inputs**

- Distillery (`distillery`, text, required): The distillery to report on. The list fills with every distillery Whisky Hunter tracks once the app is connected.
- From (`from_date`, date): Only include months from this one onwards. Any day in the month works -- the results describe whole months, so a date in the middle of one keeps that whole month. Leave empty to start at the earliest results Whisky Hunter has, which reach back to November 2005.
- To (`to_date`, date): Only include months up to and including this one. Any day in the month works. Leave empty to run to the most recent month.
- Order (`order`, text): Which end of the series to return first. One of: `newest_first` (Newest month first), `oldest_first` (Oldest month first). Default: `newest_first`.
- How many months (`limit`, number): The most months to return. However many were cut, the totals still cover the whole period, and the full number that matched comes back as Total matched. From 1 to 1000. Default: `100`.

**Outputs**

- `count` (number): How many rows were returned
- `distillery_name` (text): The distillery these results are for
- `distillery_slug` (text): Its identifier, as it was asked for
- `months` (list): One row per month, in the order that was asked for
- `total_matched` (number): How many matched before the limit was applied
- `totals` (object): Every month the date filters matched, added up -- not just the rows the limit let through

**Example output**

```json
{
  "count": 1,
  "distillery_name": "Ardbeg",
  "distillery_slug": "ardbeg",
  "months": [
    {
      "date": "2024-08-01",
      "distillery_name": "Ardbeg",
      "distillery_slug": "ardbeg",
      "lots_count": 1142,
      "month": "2024-08",
      "trading_volume_gbp": 248748.06,
      "winning_bid_max_gbp": 2900.0,
      "winning_bid_mean_gbp": 217.82,
      "winning_bid_min_gbp": 3.4
    }
  ],
  "total_matched": 8,
  "totals": {
    "first_month": "2024-01",
    "last_month": "2024-08",
    "lots_count": 10333,
    "rows_count": 8,
    "trading_volume_gbp": 2860138.67,
    "winning_bid_max_gbp": 21000.0,
    "winning_bid_mean_gbp": 276.8,
    "winning_bid_min_gbp": 0.9
  }
}
```

### Get an auction house

Get one auction house's fees, website and base currency. Use it to price up a sale at a particular house, or to turn a slug from any other step into a name and a link.

**Inputs**

- Auction house (`auction`, text, required): The auction house to report on. The list fills with every house Whisky Hunter tracks once the app is connected.

**Outputs**

- `base_currency` (text): The currency the flat listing and reserve fees are charged in, e.g. 'GBP'. Empty when the house has no single base currency. Results are always reported in GBP regardless.
- `buyers_fee_percent` (number): What the buyer pays on top of the hammer price, as a percentage
- `listing_fee_amount` (number): The flat fee for listing one lot, in the house's base currency
- `name` (text): The auction house's name, e.g. 'Whisky Auctioneer'
- `reserve_fee_amount` (number): The flat fee for putting a reserve on one lot, in the house's base currency
- `sellers_fee_percent` (number): What is deducted from the seller's proceeds, as a percentage
- `slug` (text): The auction house's identifier, e.g. 'whiskyauctioneer'. Every action here that takes an auction house takes this.
- `total_commission_percent` (number): The buyer's and seller's fees added together: the round-trip commission on a hammer price at this house
- `url` (text): The auction house's own website

**Example output**

```json
{
  "base_currency": "GBP",
  "buyers_fee_percent": 12.5,
  "listing_fee_amount": 6.0,
  "name": "Whisky Auctioneer",
  "reserve_fee_amount": 10.0,
  "sellers_fee_percent": 5.0,
  "slug": "whiskyauctioneer",
  "total_commission_percent": 17.5,
  "url": "https://www.whiskyauctioneer.com/"
}
```

### Get an auction house's monthly results

Get one auction house's results month by month: the mean winning bid, the money that changed hands and the lots that sold, all in GBP, plus its share of every lot sold across the market that month. Narrow it to a date range, and read the whole period's totals off the same result.

**Inputs**

- Auction house (`auction`, text, required): The auction house to report on. The list fills with every house Whisky Hunter tracks once the app is connected.
- From (`from_date`, date): Only include months from this one onwards. Any day in the month works -- the results describe whole months, so a date in the middle of one keeps that whole month. Leave empty to start at the earliest results Whisky Hunter has, which reach back to November 2005.
- To (`to_date`, date): Only include months up to and including this one. Any day in the month works. Leave empty to run to the most recent month.
- Order (`order`, text): Which end of the series to return first. One of: `newest_first` (Newest month first), `oldest_first` (Oldest month first). Default: `newest_first`.
- How many months (`limit`, number): The most months to return. However many were cut, the totals still cover the whole period, and the full number that matched comes back as Total matched. From 1 to 1000. Default: `100`.

**Outputs**

- `auction_name` (text): The auction house these results are for
- `auction_slug` (text): Its identifier, as it was asked for
- `count` (number): How many rows were returned
- `months` (list): One row per month, in the order that was asked for
- `total_matched` (number): How many matched before the limit was applied
- `totals` (object): Every month the date filters matched, added up -- not just the rows the limit let through

**Example output**

```json
{
  "auction_name": "Whisky Auctioneer",
  "auction_slug": "whiskyauctioneer",
  "count": 1,
  "months": [
    {
      "auction_name": "Whisky Auctioneer",
      "auction_slug": "whiskyauctioneer",
      "date": "2024-08-01",
      "lots_count": 5925,
      "market_lots_count": 34399,
      "month": "2024-08",
      "trading_volume_gbp": 2215125.0,
      "winning_bid_mean_gbp": 373.86
    }
  ],
  "total_matched": 8,
  "totals": {
    "first_month": "2024-01",
    "last_month": "2024-08",
    "lots_count": 59058,
    "rows_count": 8,
    "trading_volume_gbp": 23324574.0,
    "winning_bid_mean_gbp": 394.94
  }
}
```

### List auction houses

List the online whisky auction houses Whisky Hunter tracks, with what each one charges: the buyer's and seller's fees as percentages of the hammer price, the flat listing and reserve fees in the house's own currency, and the two percentages added together as the round-trip commission. Filter by currency or name, and sort by any of the fees to find the cheapest place to buy or sell.

**Inputs**

- Base currencies (`currencies`, list): Only include auction houses that charge their flat fees in these currencies. Leave empty for all of them.
- Name contains (`search`, text): Only include auction houses whose name contains this text. Case is ignored.
- Sort by (`sort_by`, text): Which column to order the houses on. One of: `name`, `buyers_fee_percent` (Buyer's fee), `sellers_fee_percent` (Seller's fee), `total_commission_percent` (Buyer's and seller's fees combined), `listing_fee_amount` (Listing fee), `reserve_fee_amount` (Reserve fee). Default: `name`.
- Sort direction (`sort_direction`, text): Which way to order the list. One of: `ascending` (Ascending (A-Z, smallest first)), `descending` (Descending (Z-A, largest first)). Default: `ascending`.
- How many auction houses (`limit`, number): The most auction houses to return. Whisky Hunter tracks about 30, so the default returns all of them. From 1 to 500. Default: `100`.

**Outputs**

- `auctions` (list): The auction houses that matched
- `count` (number): How many rows were returned
- `total_matched` (number): How many matched before the limit was applied

**Example output**

```json
{
  "auctions": [
    {
      "base_currency": "GBP",
      "buyers_fee_percent": 12.5,
      "listing_fee_amount": 6.0,
      "name": "Whisky Auctioneer",
      "reserve_fee_amount": 10.0,
      "sellers_fee_percent": 5.0,
      "slug": "whiskyauctioneer",
      "total_commission_percent": 17.5,
      "url": "https://www.whiskyauctioneer.com/"
    }
  ],
  "count": 1,
  "total_matched": 31
}
```

### List distilleries

List the distilleries Whisky Hunter tracks auction results for, with the country each one distils in. Filter by country or by name. Each one's slug is what the distillery results actions take.

**Inputs**

- Countries (`countries`, list): Only include distilleries in these countries. Leave empty for all of them.
- Name contains (`search`, text): Only include distilleries whose name contains this text. Case is ignored.
- Sort by (`sort_by`, text): Which column to order the distilleries on. One of: `name`, `country` (Country, then name). Default: `name`.
- Sort direction (`sort_direction`, text): Which way to order the list. One of: `ascending` (Ascending (A-Z, smallest first)), `descending` (Descending (Z-A, largest first)). Default: `ascending`.
- How many distilleries (`limit`, number): The most distilleries to return. Whisky Hunter tracks about 160, so the default returns all of them. From 1 to 1000. Default: `200`.

**Outputs**

- `count` (number): How many rows were returned
- `distilleries` (list): The distilleries that matched
- `total_matched` (number): How many matched before the limit was applied

**Example output**

```json
{
  "count": 1,
  "distilleries": [
    {
      "country": "Scotland",
      "name": "Ardbeg",
      "slug": "ardbeg"
    }
  ],
  "total_matched": 160
}
```

### List monthly results for every auction house

List monthly results for every auction house at once: one row per house per month, each with its mean winning bid, trading volume, lots sold and share of the market. Narrow it to particular houses, to a date range, or both.

**Inputs**

- Auction houses (`auctions`, list): Only include these auction houses. Leave empty for all of them.
- From (`from_date`, date): Only include months from this one onwards. Any day in the month works -- the results describe whole months, so a date in the middle of one keeps that whole month. Leave empty to start at the earliest results Whisky Hunter has, which reach back to November 2005.
- To (`to_date`, date): Only include months up to and including this one. Any day in the month works. Leave empty to run to the most recent month.
- Order (`order`, text): Which end of the series to return first. One of: `newest_first` (Newest month first), `oldest_first` (Oldest month first). Default: `newest_first`.
- How many rows (`limit`, number): The most rows to return, where a row is one auction house in one month. However many were cut, the totals still cover the whole period, and the full number that matched comes back as Total matched. From 1 to 5000. Default: `100`.

**Outputs**

- `count` (number): How many rows were returned
- `months` (list): One row per auction house per month, in the order that was asked for
- `total_matched` (number): How many matched before the limit was applied
- `totals` (object): Every month the date filters matched, added up -- not just the rows the limit let through

**Example output**

```json
{
  "count": 1,
  "months": [
    {
      "auction_name": "Whisky Auctioneer",
      "auction_slug": "whiskyauctioneer",
      "date": "2024-08-01",
      "lots_count": 5925,
      "market_lots_count": 34399,
      "month": "2024-08",
      "trading_volume_gbp": 2215125.0,
      "winning_bid_mean_gbp": 373.86
    }
  ],
  "total_matched": 24,
  "totals": {
    "first_month": "2024-08",
    "last_month": "2024-08",
    "lots_count": 40107,
    "rows_count": 24,
    "trading_volume_gbp": 9025670.24,
    "winning_bid_mean_gbp": 225.04
  }
}
```

### Summarise the market month by month

Add the whole secondary whisky market up month by month: the money that changed hands, the lots that sold, the mean winning bid those two imply, how many auction houses reported and which of them traded the most. The series a chart of the market's health is drawn from.

**Inputs**

- From (`from_date`, date): Only include months from this one onwards. Any day in the month works -- the results describe whole months, so a date in the middle of one keeps that whole month. Leave empty to start at the earliest results Whisky Hunter has, which reach back to November 2005.
- To (`to_date`, date): Only include months up to and including this one. Any day in the month works. Leave empty to run to the most recent month.
- Order (`order`, text): Which end of the series to return first. One of: `newest_first` (Newest month first), `oldest_first` (Oldest month first). Default: `newest_first`.
- How many months (`limit`, number): The most months to return. However many were cut, the totals still cover the whole period, and the full number that matched comes back as Total matched. From 1 to 1000. Default: `100`.

**Outputs**

- `count` (number): How many rows were returned
- `months` (list): One row per month, in the order that was asked for
- `total_matched` (number): How many matched before the limit was applied
- `totals` (object): Every month the date filters matched, added up -- not just the rows the limit let through

**Example output**

```json
{
  "count": 1,
  "months": [
    {
      "auctions_reporting": 24,
      "date": "2024-08-01",
      "lots_count": 40107,
      "month": "2024-08",
      "top_auction_name": "Whisky Auctioneer",
      "top_auction_share_percent": 24.54,
      "top_auction_slug": "whiskyauctioneer",
      "trading_volume_gbp": 9025670.24,
      "winning_bid_mean_gbp": 225.04
    }
  ],
  "total_matched": 3,
  "totals": {
    "first_month": "2024-06",
    "last_month": "2024-08",
    "lots_count": 145910,
    "rows_count": 3,
    "trading_volume_gbp": 36298825.7,
    "winning_bid_mean_gbp": 248.78
  }
}
```