# Commodities

Weekly retail prices from the Pakistan Bureau of Statistics' **Sensitive Price Indicator (SPI)**: 30 essential items, reported for 17 cities plus a national average. These are shortcuts over the `commodities.*` series, which carry a `city` dimension.

## `GET /v1/commodities/items` - public

Every item, with its id and unit:

```json
{ "success": true, "data": [
  { "id": "commodities.wheat_flour", "name": "Wheat Flour (20 Kg Bag)", "unit": "pkr_per_20kg" },
  { "id": "commodities.rice_basmati", "name": "Rice Basmati Broken", "unit": "pkr_per_kg" },
  { "id": "commodities.milk_fresh", "name": "Milk Fresh (Un-boiled)", "unit": "pkr_per_litre" }
] }
```

Items: `wheat_flour`, `rice_basmati`, `rice_irri`, `bread`, `beef`, `mutton`, `chicken`, `milk_fresh`, `eggs`, `sugar`, `gur`, `salt`, `tea_packet`, `cooking_oil`, `mustard_oil`, `vegetable_ghee_loose`, `vegetable_ghee_tin`, `pulse_masoor`, `pulse_moong`, `pulse_mash`, `pulse_gram`, `potatoes`, `onions`, `tomatoes`, `garlic`, `petrol`, `diesel`, `lpg`, `gas`, `electricity`.

**Check the unit.** Units vary by item. Most are per kg, but some aren't:

| Item | Unit |
|---|---|
| wheat flour | per 20 kg bag |
| eggs | per dozen |
| milk, petrol, diesel | per litre |
| cooking oil | per 5 litres |
| vegetable ghee (tin) | per 2.5 kg |
| tea | per 190 g pack |
| salt | per 800 g |
| LPG | per cylinder |
| gas | per MMBTU |
| electricity | per unit |
| bread | each |

## `GET /v1/commodities/cities` - public

```json
{ "success": true, "data": ["bahawalpur","bannu","faisalabad","gujranwala","hyderabad","islamabad","karachi","khuzdar","lahore","larkana","multan","national","peshawar","quetta","rawalpindi","sargodha","sialkot","sukkur"] }
```

`national` is the unweighted mean across the reporting cities.

## `GET /v1/commodities` (key required)

The national-average price series for one item.

| Param | Type | Default | Notes |
|---|---|---|---|
| `item` | string | required | `wheat_flour`, `commodities.wheat_flour` (either works) |
| `from`, `to` | date | - | Date window (weeks end on Thursday) |
| `limit` | int | 1000 | 1-10000 |
| `sort` | `asc`\|`desc` | `desc` | |

```bash
curl -H "X-API-Key: pk_live_xxx" \
  "https://api.pakdatahub.com/v1/commodities?item=wheat_flour&limit=2"
```

The response uses the standard series envelope, with `data[].dims = {"city": "national"}`.

## `GET /v1/commodities/by-city` (key required)

The same item in one city.

| Param | Type | Notes |
|---|---|---|
| `item` | string | required |
| `city` | string | required, one of `/cities` |
| `from`, `to`, `limit`, `sort` | | as above |

```bash
curl -H "X-API-Key: pk_live_xxx" \
  "https://api.pakdatahub.com/v1/commodities/by-city?item=petrol&city=lahore&from=2026-01-01&sort=asc"
```

## Equivalent generic call

The same data through [`/v1/series`](https://pakdatahub.com/docs/api-series.md). This form also accepts transforms:

```bash
curl -H "X-API-Key: pk_live_xxx" \
  "https://api.pakdatahub.com/v1/series/commodities.sugar?dims=city:karachi&transform=yoy"
```

## Related

- A per-city **cost-of-living index** built from these prices: series `cost_of_living.<city>` (weekly, rebased to 100), and the free [cost-of-living tool](https://pakdatahub.com/tools/cost-of-living).
- Coverage and history: [Commodities dataset](https://pakdatahub.com/docs/data-commodities.md).

---
Source: https://pakdatahub.com/docs/api-commodities - PakDataHub docs index: https://pakdatahub.com/docs/llms.txt