> ## Documentation Index
> Fetch the complete documentation index at: https://www.worldmonitor.app/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Consumer Prices

> Retail grocery and essentials price tracking by market — overview, categories, movers, retailer spreads, and freshness across 7/30/90-day windows.

The **Consumer Prices** panel is the retail-inflation and basket-pricing surface for the dashboard. It tracks actual shelf prices at the market (country) level, broken down by category and retailer, and exposes source freshness so a reader can see when the underlying scrapes last ran.

## What the panel shows

Five tabs under a market + basket selector and a time-range control:

| Tab            | What it answers                                                                                                              |
| -------------- | ---------------------------------------------------------------------------------------------------------------------------- |
| **Overview**   | Current basket level, period-over-period change, and a sparkline across the selected range.                                  |
| **Categories** | Category-level snapshot (food, beverages, household, essentials, etc.) with period deltas.                                   |
| **Movers**     | Top risers and top fallers across the basket for the selected window — the items driving the overall change.                 |
| **Spread**     | Retailer-level price spread on a fixed essentials basket — which retailer is cheapest, which is most expensive, and the gap. |
| **Health**     | Data-source freshness — when each upstream scrape last completed, with a clear indicator if data is stale.                   |

Panel-level controls:

* **Market bar** — a button per supported market (default `AE`; the full list comes from `MARKETS` in `src/services/consumer-prices`). Selecting a market implicitly sets the basket to that market's `essentials-<code>` variant (or the default basket when the `all` aggregate view is active) — there is no separate basket picker.
* **Range bar** — `7d`, `30d`, or `90d`.
* **Category filter** — click a category row on the **Categories** tab to scope the **Movers** tab to that category. A clear-filter affordance resets it.

Settings persist across sessions in `localStorage` under `wm-consumer-prices-v1`.

Panel id is `consumer-prices`; canonical component is `src/components/ConsumerPricesPanel.ts`.

## How you reach it

* **Cmd+K**: type *prices* or *consumer*.
* **Availability by variant**: enabled by default in the **finance** and **commodity** variants. Registered but disabled (opt-in) in the **full/geopolitical** variant. Not registered in the tech or happy variants. Source: `FINANCE_PANELS`, `COMMODITY_PANELS`, `FULL_PANELS` in `src/config/panels.ts`.

## Data sources

Five tab RPCs plus one sparkline RPC back the panel:

| Surface            | RPC                                                            |
| ------------------ | -------------------------------------------------------------- |
| Overview           | `GET /api/consumer-prices/v1/get-consumer-price-overview`      |
| Overview sparkline | `GET /api/consumer-prices/v1/get-consumer-price-basket-series` |
| Categories         | `GET /api/consumer-prices/v1/list-consumer-price-categories`   |
| Movers             | `GET /api/consumer-prices/v1/list-consumer-price-movers`       |
| Spread             | `GET /api/consumer-prices/v1/list-retailer-price-spreads`      |
| Health             | `GET /api/consumer-prices/v1/get-consumer-price-freshness`     |

Upstream data is scraped from retailer price feeds by the companion
`consumer-prices-core` service and published as Redis snapshots per market and
basket.

## Refresh cadence

The underlying seeders run roughly once per day per market+basket combination. The Consumer Prices keys in `api/health.js` allow up to **25 hours** (`maxStaleMin: 1500`) before the health surface escalates a warning, which gives the seeder a 1-hour grace window on top of the daily cadence.

The Health tab inside the panel shows the per-source fetched-at timestamps so you can see staleness directly rather than relying on global health flags.

## Tier & gating

Consumer Prices is **free**. The panel is registered without a `premium` flag in `src/config/panels.ts`, so anyone — including unauthenticated readers — can see it on variants where it is enabled.

## API reference

* [Consumer Prices service](/api/ConsumerPricesService.openapi.yaml) — full OpenAPI for all 5+1 RPCs.