Data dictionary

First day of the calendar month the figure describes. Always the 1st; the index is monthly, not daily. A release for this period publishes mid-way through the following month.

Where the price was observed. "shelf" is an in-store price (the headline series). "marketplace" is a delivery-platform listing, which carries platform markup. Never combine the two: a marketplace basket_cost is not comparable to a shelf basket_cost. Month-over-month changes are comparable across bases, because a roughly constant markup cancels in a matched ratio.

Geographic granularity of the row.

Geography identifier. "US" for national rows; the CBSA code for metro rows.

Human-readable geography, e.g. "United States" or "Houston-The Woodlands-Sugar Land, TX". Metro names are full Census CBSA titles, which list several principal cities.

URL-safe geography key: "us" nationally, or "city-st" for a metro (e.g. houston-tx). Stable across releases — safe to join on. Maps to /price-index/metro/{geo_slug}.

Which category scheme category_code belongs to. "bls" mirrors the Bureau of Labor Statistics food-at-home groups and is what the site publishes; "gcpi" is our own finer grouping. Filter to one taxonomy before aggregating, or you will double-count.

Category key within the taxonomy. "all" is the aggregate across categories. BLS values: all, cereals_and_bakery_products, meats_poultry_fish_and_eggs, dairy_and_related_products, fruits_and_vegetables, nonalcoholic_beverages, other_food_at_home.

Display label for category_code.

Chained price index, April 2026 = 100. Built by chaining month-over-month changes, not by dividing basket costs. Null means the chain could not be continued — typically the month before was suppressed. A value of exactly 100.00 in a period after April 2026 marks a chain restart (a fresh base), not "unchanged since April".

Month-over-month percent change, from a matched sample: only (store, item) pairs observed in BOTH months, aggregated with a trimmed Jevons geometric mean. This is the field to use for "prices rose X%". Null NEVER means zero, and it has two distinct causes: either the comparison did not clear our thresholds, or the month follows a methodology change that makes it incomparable with the month before. August 2026 is such a month — mom_pct is null for all 133 of its rows and index_value restarts at 100, by design and not for want of data.

Year-over-year percent change. Null for every row until the series is 13 months old (first non-null: spring 2027). We do not publish annual comparisons before the data supports them.

Weighted average unit price of the basket, in dollars. A comparative measure of price level — NOT a weekly grocery bill. Treat it as indicative: the value depends on which items and stores cleared suppression for that geography and basis, so a difference between two basket_cost values mixes real price differences with coverage differences. Never derive a "delivery premium" by dividing a marketplace basket_cost by a shelf one — the two bases do not price the same item mix. Use mom_pct for any precise comparison.

Price spread for identical items: the p10-to-p90 range across store-level medians, weight-averaged over the basket. Roughly "how much you can save by shopping around". National dispersion includes genuine regional differences; metro dispersion is the within-market figure.

DISTINCT price observations behind the cell: the first reading for a given product at a given store in the period, plus every price change. Re-reading an unchanged price does not count again. The minimum-sample floors apply to this number. For periods published before September 2026 this column counts READINGS instead — see n_readings and the methodology.

How many times those prices were read. Empty for periods published before September 2026, which did not count the two separately — empty means not measured, not zero. The gap between the two is large and uneven: measured over the 30 days to 2026-09-20, readings exceeded distinct observations by 4.98x across our corpus, and by 21.3x for one chain.

Number of distinct stores contributing to the cell.

Number of distinct grocery banners (store brands) contributing. Published cells require at least three, so no single retailer can be reverse-engineered from a figure.

Version of the computation that produced the row. If the method changes materially, the whole series is recomputed under the new version rather than spliced — check this before combining downloads taken months apart.