> For the complete documentation index, see [llms.txt](https://whalecoupons.gitbook.io/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://whalecoupons.gitbook.io/docs/public-data.md).

# Public data

You can use Whale Coupons data without MCP. There are two public sources.

## codes.json

```
https://whalecoupons.co/codes.json
```

A single JSON file listing every store in the directory and its current code.

* No sign-in or API key.
* Served with `Access-Control-Allow-Origin: *`, so a browser app on any domain can fetch it.
* `Content-Type: application/json`.

```bash
curl -s https://whalecoupons.co/codes.json | jq '.updated, .count, .codes[0]'
```

```js
const res = await fetch("https://whalecoupons.co/codes.json");
const data = await res.json();
const pets = data.codes.filter(c => c.category === "Pets");
```

### Structure

```json
{
  "site": "Whale Coupons",
  "updated": "2026-10-19",
  "count": <number of stores>,
  "codes": [
    {
      "store": "1001 Knots",
      "category": "Home & kitchen",
      "code": "WHALECOUPONS",
      "discount": "10% off",
      "url": "<store link>",
      "page": "https://whalecoupons.co/stores/1001-knots/",
      "listed": "2026-10-18",
      "apply": "auto",
      "min_order": null,
      "kw": "rug room animal art century chinoiserie classic contemporary deco floral ..."
    }
  ]
}
```

### Top-level fields

| Field     | Type                | Description                  |
| --------- | ------------------- | ---------------------------- |
| `site`    | string              | Always `"Whale Coupons"`     |
| `updated` | string (YYYY-MM-DD) | Date the file was generated  |
| `count`   | integer             | Number of entries in `codes` |
| `codes`   | array               | One object per store         |

### Fields in each `codes` entry

| Field       | Type                | Description                                                                                                        |
| ----------- | ------------------- | ------------------------------------------------------------------------------------------------------------------ |
| `store`     | string              | Store name                                                                                                         |
| `category`  | string              | One of the 14 categories (see [Tool reference](https://whalecoupons.gitbook.io/docs/tool-reference.md#categories)) |
| `code`      | string              | The coupon code. Most stores use `WHALECOUPONS`, and a few issue their own                                         |
| `discount`  | string              | The discount as text, such as `"10% off"` or `"$100 off"`                                                          |
| `url`       | string              | Link that opens the store with the discount. This is an affiliate link                                             |
| `page`      | string              | The store's page on whalecoupons.co                                                                                |
| `listed`    | string (YYYY-MM-DD) | Date of the entry                                                                                                  |
| `apply`     | string              | `"auto"`: opening `url` applies the discount at checkout. `"code"`: enter the code at checkout                     |
| `min_order` | string or null      | Minimum order with currency, such as `"69 USD"`, or `null` if there is none                                        |
| `kw`        | string              | Space-separated keywords from the store's own product catalog. Useful for search                                   |

Field meanings are inferred from the file's contents and from the matching fields in the MCP tools.

### Good practice

* Fetch the file once and cache it. Check `updated` to decide when to fetch again.
* Show the `page` link so people can see the store's conditions.
* If you show `url` links, say that they are affiliate links.
* The same code across many stores is intended. It is the customer discount each store gave Whale Coupons.

## Open dataset

Aggregate statistics are published as an open dataset:

* **Title:** Independent Store Coupon Categories and Black Friday Discount Study (Whale Coupons, October 2026)
* **DOI:** [10.5281/zenodo.23464382](https://doi.org/10.5281/zenodo.23464382)
* **License:** [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/). Credit "Whale Coupons".
* **Files:** `independent-store-coupon-categories.csv`, `black-friday-study.csv`, `datapackage.json`, `README.md`, `CITATION.cff`, `LICENSE`

It covers 2,500+ independent online stores in 13 product categories, with store counts, types of codes, median, mean and maximum percentage discounts, and the share of stores offering 20% or more. It also includes the figures from the Whale Coupons [Black Friday independent-store discount study](https://whalecoupons.co/deals-research/black-friday-indie-discounts/). The dataset contains no individual codes and no affiliate links. Methodology and column definitions are in its `README.md`.

**Cite as:**

> Whale Coupons (2026). *Independent Store Coupon Categories and Black Friday Discount Study (Whale Coupons, October 2026)* (Version 2026.10.19) \[Data set]. Zenodo. <https://doi.org/10.5281/zenodo.23464382>

## llms.txt

<https://whalecoupons.co/llms.txt> is a plain-text overview of the site for AI tools. It links the categories, roundups and store pages, and names the MCP endpoint and `codes.json`.
