# DecaData Odyssey Lite API

> US retail point-of-sale sales and units for about 380 consumer companies (weekly for all, daily for the largest), by ISIN or ticker, from 2018-01-01. Company totals from eight US retailers, mapped to the company that owned each brand at the time (history is never restated). Pay per request in USDC over HTTP 402 (x402): no account, no API key.

Data is available 7 days after the transaction date (T+7); currently through 2026-10-29. All responses are JSON.

## What this data is, and isn't

It's what sold: units and dollars rung up at the till in eight US retail groups, summed to the company that owned each product. It isn't scraped shelf prices or listings, web traffic, card-spend estimates, government aggregates or company filings. Use it to see how a consumer company is actually selling, between and ahead of its quarterly reports.

## Which endpoint answers which question

| Question | Call | Cost |
|---|---|---|
| Which companies are covered, from when, at what tier? | `GET /v1/coverage` | free |
| What does the data look like? | `GET /v1/companies/{id}/sample` | free |
| What would a window cost? | `GET /v1/quote?company={id}&from=&to=&freq=` | free |
| How did this company's last reported quarter do, against last year and the market? | `GET /v1/companies/{id}/yoy` | $0.01 |
| Day-by-day (or week-by-week) sales and units | `GET /v1/companies/{id}/sales?from=&to=&freq=` | from $1.00 |
| What will BLS say food-at-home inflation was, before it publishes? | `GET /v1/cpi/food-at-home/nowcast?month=YYYY-MM` | $25.00 to $250.00 before BLS's release, $0.01 after |

`{id}` is an ISIN (`US7134481081`), `isin:US7134481081` or `ticker:PEP`. Start with the year-on-year figure to find the companies worth a closer look, then buy the series for those.

## Free endpoints

- [Coverage](https://api.decadata.io/v1/coverage): every company on sale, with isin, ticker, name, tier, first_date, last_date
- [Company](https://api.decadata.io/v1/companies/ticker:PEP): look up one company by ISIN, `isin:...` or `ticker:...`
- [Sample](https://api.decadata.io/v1/companies/ticker:PEP/sample): Q1 2019 rows for a company, free, to judge the data
- [Quote](https://api.decadata.io/v1/quote?company=ticker:PEP&from=2025-01-01&to=2025-12-31&freq=daily): the exact price of a request before buying
- [CPI food-at-home](https://api.decadata.io/v1/cpi/food-at-home): the months the nowcast is on offer for, BLS's release dates, today's price, and the track record

## Paid: year-on-year growth, $0.01

`GET https://api.decadata.io/v1/companies/{id}/yoy`

The company's latest **reported** quarter: the 91 days to the end of its last quarter with published results, against the same 91 days a year earlier (364 days before, so each day is compared with the same weekday). Never the quarter it hasn't reported yet: that's for subscribers. Reported quarters come from the company's earnings announcements, and the window ends at the quarter's real fiscal end, from the company's SEC filings (10-Qs and 10-Ks: some fiscal quarters end weeks before the calendar quarter they're listed under). When the filings don't say, it ends at the earlier of the listed quarter end and 35 days before the announcement, or 28 days before the listed end when the announcement date isn't known; a company without any we know of (foreign listings, private or retired companies) gets the last calendar quarter that ended at least 60 days before the latest day on sale. `quarter_end` and `basis` (`reported` or `lagged`) say which. **Same store, like for like** (`method`): from the retailers' own transaction logs, each day against the same weekday a year before, **in the stores trading on both days only**, so stores opening or closing don't count as growth; and last year's sales are credited to **this year's owners**, so an acquisition or a spin-off doesn't either (`as_owned_*` credits last year to last year's owners, for comparison). The days and the retailers are added up, which weights each retailer by the company's sales there a year before. Where the logs don't cover a window (before 2025), the panel is used instead (`method` `retailer groups`: sales per panel store within each retailer group). It moves on when the company reports its next quarter.

Returns `sales_per_store_growth_pct` and `units_per_store_growth_pct` (percent, to 0.1: same-store growth); the same for the market, **every sale in the same stores**, branded or not (`market_sales_per_store_growth_pct`, `market_units_per_store_growth_pct`); and the company against that market (`vs_market_sales_growth_pct`, `vs_market_units_growth_pct`), with the two windows (`from`, `to`, `prior_from`, `prior_to`) and `compared` (days or weeks with data on both sides).

**Read `vs_market` first.** It takes out what moved every product in those stores alike (a retailer's own trend, its shoppers, the calendar). The market includes fresh food and store brands, so a branded company below the market may partly be branded goods losing share to them. Sales growing faster than units means a higher average price paid (price rises or a richer mix); units growing faster means the opposite. A company without a year of history answers `422`, before any payment is asked for.

## Paid: the CPI food-at-home nowcast

`GET https://api.decadata.io/v1/cpi/food-at-home/nowcast?month=YYYY-MM` (without `month`: the next BLS release on offer)

Our estimate of BLS's **food-at-home inflation** for a month (CPI-U, US city average, not seasonally adjusted, year on year, `CUUR0000SAF11`), before BLS publishes it, from what shoppers paid at the tills of the high-low grocery chains in our panel. Priced by how long before BLS's release (8:30 a.m. Eastern on its release day) you buy it: **$250.00** 15 days or more before, **$100.00** 7 to 14 days, **$25.00** in the last 6 days, and **$0.01** from the release on (the month, scored against BLS's figure). The free list (`GET /v1/cpi/food-at-home`) gives each month's release date, today's price, and the track record.

Returns `nowcast.food_at_home_yoy_pct`; `bls_latest` (BLS's latest published month); `our_index`, our own index for the month so far, for food at home and BLS's six groups (cereals and bakery, meats, poultry, fish and eggs, dairy, fruits and vegetables, nonalcoholic beverages, other food at home); `data_through` (the last day of data in it; it's updated daily while the month is open); `days_to_release`; and, once BLS has published, `actual` and the nowcast's miss.

How it's made: every product sold in the same store in both periods, at the price paid, weighted by spending, grouped into BLS's own items and combined with BLS's weights; fresh meat and produce per pound; promotion-heavy aisles at each product's most common price. The nowcast starts from BLS's latest figure and adds, item by item, a share of the change our data shows since, each share fitted on earlier months only. Our own index runs above BLS (about 1.3 points a year since 2025): high-low chains, against a national sample that includes everyday-low-price retailers.

## Paid: sales and units

`GET https://api.decadata.io/v1/companies/{id}/sales?from=YYYY-MM-DD&to=YYYY-MM-DD&freq=daily|weekly`

Without `to`, the window ends at the latest day on sale; without `from`, it's just that day (weekly: that whole week). `freq` defaults to daily (weekly for tier 3, which has no daily series).

Rows: `date` (or `week_start`, a Monday), `units`, `sales` (USD), `panel_stores`, and `unique_stores` and `unique_customers` (may be null).

## Reading the numbers

- **Don't compare raw totals across years.** The panel's stores change (a retailer closing stores lowers every company's totals), so for growth use `/yoy`: same store, like for like. `panel_stores` (rows of `/sales`) helps for short comparisons; across years, stores closing make sales per store misleading too.
- **Compare like with like.** Sales follow the week (weekends are bigger) and the calendar: compare a day with the same weekday, and a holiday with the same holiday. Thanksgiving is far below a normal day; Christmas Day has no data.
- **Units and sales together** give the average price paid (sales / units), so price and volume can be told apart.
- **Ownership is as it was.** A product counts towards the company that owned it on the day; an acquisition doesn't move past sales, and published days are never restated.
- **Coverage is eight US retail groups,** not all of a company's sales: read it as a consistent sample of US retail, best for direction and change.

## Examples

- How did PepsiCo's last reported quarter look at the till? `GET /v1/companies/ticker:PEP/yoy` ($0.01).
- Screen 20 companies for growth: 20 `/yoy` calls ($0.20), then the daily series for the two or three that stand out.
- PepsiCo's latest day: `GET /v1/companies/ticker:PEP/sales` ($5.00, tier 1).
- A year of daily history, all of it over 90 days old: `/sales?from=2024-01-01&to=2024-12-31` ($183.00 for tier 1). Check any window first with `/v1/quote`.

## MCP

The free endpoints and `/yoy` are also an MCP server, for assistants and agents that speak the Model Context Protocol: `https://api.decadata.io/mcp` (Streamable HTTP, no sign-in).

- Claude: Settings, Connectors, Add custom connector, with that URL. Claude Code: `claude mcp add --transport http decadata https://api.decadata.io/mcp`
- Cursor and others: `{"mcpServers": {"decadata": {"url": "https://api.decadata.io/mcp"}}}`

Tools: `find_companies`, `get_sample` and `quote_sales` (free), and `get_yoy_growth` ($0.01, paid with x402's MCP transport: the payment in `_meta["x402/payment"]`). A client without a wallet gets the price and the HTTP URL to buy from. The daily series is HTTP only.

## How to pay (x402 version 2, https://x402.org)

1. Request without payment: the response is `402 Payment Required`, with the `PaymentRequired` object in the `PAYMENT-REQUIRED` header (base64) and as the body: `accepts` gives the price (`amount`, USDC with 6 decimals), `payTo`, `asset` and `network` (`eip155:8453`, Base), and `resource` the exact request being bought.
2. Sign the payment with your wallet and repeat the request with the `PAYMENT-SIGNATURE` header. x402 client libraries for JavaScript and Python do this for you. No ETH is needed: the facilitator pays the gas.
3. The payment is verified, the response made, and only then the payment settled. The response carries the data, a receipt and the licence; the `PAYMENT-RESPONSE` header has the settlement.

One payment buys one response. A request for days not yet on sale is cut back to the latest day on sale, and only those days are charged.

## Funded trials

If DecaData has given you a trial code (`ddt_...`), it pays for `/yoy` and `/sales` up to its budget, until its end date, with no wallet: send it in the `X-DecaData-Trial` header or as `?trial=`. In an assistant, add the MCP server as `https://api.decadata.io/mcp?trial=<code>`. Each response says what's left (`trial.left_usd`); when it runs out, the usual 402 comes back.

## Errors

- `400`: a window that can't be sold (bad dates, more than 1098 days, or daily for a weekly-only company)
- `402`: payment required, or the payment wasn't accepted (`error` says why)
- `404`: unknown company (see /v1/coverage)
- `422`: `/yoy` for a company without a year of history; nothing is charged
- `429`: this wallet has bought 50 different companies in 30 days

## Prices (USD)

`/yoy`: $0.01 a request, any company.

`/v1/cpi/food-at-home/nowcast`: $250.00 15+ days before BLS's release, $100.00 7-14 days, $25.00 the last 6 days, $0.01 from the release on.

`/sales`: the latest 90 days on sale are "live"; older days are "history". Each company's tier is in /v1/coverage.

| Tier | Live, per company-day | History, per company-month | Frequency |
|---|---|---|---|
| 1 | $5.00 | $15.00 | daily or weekly |
| 2 | $1.50 | $4.00 | daily or weekly |
| 3 | $10.00 per company-month | $1.00 | weekly only |

History is charged by the day at the monthly rate / 30. Minimum $1.00 per request; at most 1098 days per request. Weekly windows are whole Monday-to-Sunday weeks. One payer can buy up to 50 different companies in 30 days, across both paid endpoints.

## Licence

Licensed to the purchaser for its own research. No redistribution or resale. https://decadata.io/terms

Every row sold by /sales carries a mark that identifies the purchase it was sold in.

## More

- [Odyssey Lite subscription](https://decadata.io/#contact): every company and brand, from T+3, with full history in bulk; API spend counts towards it
- [MCP server](https://api.decadata.io/mcp), [OpenAPI](https://api.decadata.io/openapi.json), [x402 discovery](https://api.decadata.io/.well-known/x402), [agents.json](https://api.decadata.io/agents.json)
- [DecaData](https://decadata.io), and [@Deca_Data on X](https://x.com/Deca_Data)