---
title: "A weekly grocery budget for a named New Zealand household"
method: POST
path: "/v1/grocery-budget"
tags: ["Calculators"]
---

# A weekly grocery budget for a named New Zealand household

`POST /v1/grocery-budget`

## Request

- Base URL: `https://api.calculate.co.nz`
- URL: `https://api.calculate.co.nz/v1/grocery-budget`
- Auth: API key in header `X-API-Key`

What a household should expect to spend on groceries.

Build the household person by person: a teenager is not a child-sized cost,
and an average per head hides that. Then diet and region adjust the food
total, and a flat $25 a week covers cleaning products and toiletries unless
you turn it off.

All three spend levels come back every time, and that is the point. A
single figure invites "that seems high"; the gap between basic and liberal
for the SAME household, in dollars a year, is the number that changes
anything. On a family of four it is usually several thousand dollars, and
`annual_gap_basic_to_liberal` puts it in one place.

Be straight about what these figures are. They are indicative planning
figures used by the website calculator, not a measured survey result and
not a benchmark to hold anyone to. Someone who wants measured New Zealand
data wants the Household Economic Survey pages instead, so say so rather
than presenting these as official.

## Request body

- GroceryBudgetRequest
  - `members` string[], required: One entry per person in the household. A teenager is not a child-sized cost.
  - `spend_level` 'basic' | 'moderate' | 'liberal': How the household shops.
  - `diet` 'standard' | 'vegetarian' | 'vegan' | 'gluten_free' | 'organic' | 'halal': Diet, applied as a multiplier to the food cost.
  - `region` 'nz_average' | 'auckland' | 'wellington' | 'christchurch' | 'hamilton' | 'tauranga' | 'dunedin' | 'provincial' | 'rural_remote': Where they shop.
  - `include_non_food` boolean: Include $25 a week for cleaning products and toiletries. Most people counting a supermarket bill are including these.

## Response `200`

Weekly, monthly and annual budgets, with all three spend levels.

- GroceryBudgetResponse
  - `result` GroceryBudgetResult, required
    - `members` string[], required: Household as given.
    - `household_size` integer, required: Number of people.
    - `spend_level` string, required: Spend level used.
    - `diet` string, required: Diet used.
    - `diet_multiplier` number, required: Multiplier applied for the diet.
    - `region` string, required: Region used.
    - `region_multiplier` number, required: Multiplier applied for the region.
    - `include_non_food` boolean, required: Whether non-food is included.
    - `non_food_weekly` number, required: Weekly non-food allowance applied.
    - `base_weekly_food` number, required: Food cost before diet and region adjustment.
    - `weekly_total` number, required: Weekly budget after all adjustments.
    - `monthly_total` number, required: Weekly times 4.33.
    - `annual_total` number, required: Weekly times 52.
    - `weekly_by_level` object, required: All three spend levels weekly, for the same household.
    - `annual_by_level` object, required: All three spend levels annually.
    - `annual_gap_basic_to_liberal` number, required: What the household's shopping habits are worth over a year. Usually the most useful number here.
    - `per_person_weekly` number, required: Weekly total divided by household size.
    - `notes` string[], required: What applied, and what these figures are.
    - `excludes` string[], required: What is not in the budget.
  - `disclaimer` string, required: Scope and limits of this calculation.

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/calculate/apis/calculate-co-nz-api.md) · [All operations](https://skmtc.dev/calculate/apis/calculate-co-nz-api/llms.txt) · [OpenAPI document](https://skmtc.dev/calculate/apis/calculate-co-nz-api/revisions/aa59a8e76614?raw)