# Super Tracker API

> Free, keyless, read-only JSON over every New Zealand supermarket price, daily. Base URL `https://api.supertracker.nz`. No keys; money in integer NZD cents; days are NZ dates. Per IP: 300 requests/minute, 10,000/day. Bulk data is a nightly Parquet/CSV export, not something to crawl out of the API.

## Docs

- [Full API reference (Markdown)](https://api.supertracker.nz/llms-full.txt): every endpoint, parameter, response and schema, generated from the OpenAPI document
- [OpenAPI 3.1](https://api.supertracker.nz/openapi.json): the machine-readable contract (also [YAML](https://api.supertracker.nz/openapi.yaml))
- [Interactive reference](https://api.supertracker.nz/): browse and try every endpoint in a browser
- [MCP endpoint](https://api.supertracker.nz/mcp): stateless Streamable HTTP MCP server (revision 2026-07-28 plus legacy initialize); one read-only tool per endpoint, named after the operationIds below

## Bulk data

- [Export manifest](https://api.supertracker.nz/data/latest/manifest.json): nightly Parquet and CSV of every listing, store, price span, index point and basket item, CC BY 4.0; download `https://api.supertracker.nz/data/latest/<name>`

## Endpoints


### Search

- [GET /api/v1/search](https://api.supertracker.nz/api/v1/search): Search products across every chain (`search_products`)
- [GET /api/v1/listings](https://api.supertracker.nz/api/v1/listings): Search listings (one row per chain product) (`search_listings`)
- [GET /api/v1/suggestions](https://api.supertracker.nz/api/v1/suggestions): Autocomplete suggestions for a partial query (`suggest`)
- [GET /api/v1/gtin/{gtin}](https://api.supertracker.nz/openapi.json#/paths/~1api~1v1~1gtin~1{gtin}/get): Look up a barcode (`lookup_gtin`)

### Products

- [GET /api/v1/products/{id}](https://api.supertracker.nz/openapi.json#/paths/~1api~1v1~1products~1{id}/get): A product with every chain's offer and its alternatives (`get_product`)
- [GET /api/v1/products/{id}/history](https://api.supertracker.nz/openapi.json#/paths/~1api~1v1~1products~1{id}~1history/get): National price history of a product, per chain (`get_product_history`)
- [GET /api/v1/products/{id}/stores](https://api.supertracker.nz/openapi.json#/paths/~1api~1v1~1products~1{id}~1stores/get): The price of a product at every store in the country (`get_product_stores`)
- [GET /api/v1/products/{id}/spread](https://api.supertracker.nz/openapi.json#/paths/~1api~1v1~1products~1{id}~1spread/get): Daily price spread across each chain's stores (`get_product_spread`)

### Listings

- [GET /api/v1/listings/{id}](https://api.supertracker.nz/openapi.json#/paths/~1api~1v1~1listings~1{id}/get): One chain's listing with today's price at every store (`get_listing`)
- [GET /api/v1/listings/{id}/history](https://api.supertracker.nz/openapi.json#/paths/~1api~1v1~1listings~1{id}~1history/get): Price history of a listing, national or at one store (`get_listing_history`)

### Retailers

- [GET /api/v1/retailers](https://api.supertracker.nz/api/v1/retailers): The supermarket chains (`list_retailers`)

### Shelves

- [GET /api/v1/shelves](https://api.supertracker.nz/api/v1/shelves): The shelf directory, or the shelf a query names (`list_shelves`)
- [GET /api/v1/shelves/{slug}](https://api.supertracker.nz/openapi.json#/paths/~1api~1v1~1shelves~1{slug}/get): One page of a shelf, sorted and filtered as a whole set (`browse_shelf`)

### Retailers

- [GET /api/v1/retailers/{slug}/browse](https://api.supertracker.nz/openapi.json#/paths/~1api~1v1~1retailers~1{slug}~1browse/get): Walk a chain's own category tree (`browse_retailer`)
- [GET /api/v1/retailers/compare](https://api.supertracker.nz/api/v1/retailers/compare): The Stats NZ basket priced at every chain (`compare_retailers`)
- [GET /api/v1/retailers/levels](https://api.supertracker.nz/api/v1/retailers/levels): Each chain's basket price level against the others, by day (`get_retailer_levels`)

### Stores

- [GET /api/v1/stores](https://api.supertracker.nz/api/v1/stores): Every store with its price level and place (`list_stores`)
- [GET /api/v1/stores/{id}](https://api.supertracker.nz/openapi.json#/paths/~1api~1v1~1stores~1{id}/get): How one store prices against its chain (`get_store`)
- [GET /api/v1/stores/{id}/listings](https://api.supertracker.nz/openapi.json#/paths/~1api~1v1~1stores~1{id}~1listings/get): What one store charges, searchable (`get_store_listings`)
- [GET /api/v1/stores/{id}/levels](https://api.supertracker.nz/openapi.json#/paths/~1api~1v1~1stores~1{id}~1levels/get): One store's basket price level against its chain, by day (`get_store_levels`)
- [GET /api/v1/areas](https://api.supertracker.nz/api/v1/areas): Price levels by region, town size and town (`list_areas`)

### Deals

- [GET /api/v1/deals](https://api.supertracker.nz/api/v1/deals): What is cheaper than shelf right now (`list_deals`)

### Food price index

- [GET /api/v1/index/latest](https://api.supertracker.nz/api/v1/index/latest): Today's food-price index headline (`get_index_latest`)
- [GET /api/v1/index/daily](https://api.supertracker.nz/api/v1/index/daily): Daily index series for one group (`get_index_daily`)
- [GET /api/v1/index/groups](https://api.supertracker.nz/api/v1/index/groups): Index series for the headline and every group, columnar (`get_index_groups`)
- [GET /api/v1/index/items](https://api.supertracker.nz/api/v1/index/items): Every basket item's relative price by day, columnar (`get_index_items`)

### Basket

- [GET /api/v1/basket/{id}](https://api.supertracker.nz/openapi.json#/paths/~1api~1v1~1basket~1{id}/get): One basket item and the products it is priced from (`get_basket_item`)
- [GET /api/v1/basket](https://api.supertracker.nz/api/v1/basket): The Stats NZ basket items and their weights (`get_basket`)

### Bulk data

- [GET /data/latest/manifest.json](https://api.supertracker.nz/data/latest/manifest.json): The nightly exports and their checksums (`get_export_manifest`)

### Meta

- [GET /healthz](https://api.supertracker.nz/healthz): Liveness (`healthz`)

## Guides on the website

- [MCP for agents](https://supertracker.nz/agents): the endpoint, how to connect Claude Code, Claude, Cursor, VS Code or any client, example questions, every tool
- [The API](https://supertracker.nz/developers): where things are, a four-call quick start, conventions, fair use, every endpoint
- [Open data](https://supertracker.nz/open-data): the exports, explained
- [Site pages](https://supertracker.nz/llms.txt): the human-facing pages, which render from this API
- [Contact](https://supertracker.nz/contact): hello@supertracker.nz