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 means the comparison did not clear thresholds — it does not mean zero.

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.

Number of individual price observations behind the cell.

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.