# Series & the catalog

Almost everything in PakDataHub is a **time series**: rows of `(date, value, dims)` under one stable id. The **catalog** describes every series, and **`GET /v1/series/{id}`** returns its data.

The exceptions are the richer, entity-shaped datasets, which have their own endpoints:
- mutual funds
- debt securities
- auctions
- external trade by commodity

## Series ids

Ids are lowercase, dot-separated and human-readable, in the form `topic.group.item`:

| Id | What it is |
|---|---|
| `fx.rate.avg.usd` | PKR per US dollar, monthly average, from 1947 |
| `rates.kibor.3m` | KIBOR 3-month, daily, with `side` = bid/offer |
| `inflation.cpi.national.yoy` | Headline CPI inflation, year-on-year % |
| `payments.raast.p2p.value` | Raast person-to-person transfer value, quarterly |
| `commodities.wheat_flour` | Wheat flour (20 kg bag), weekly, with `city` |

Ids are **case-sensitive and stable**. Use them verbatim; don't re-slug them or swap the dots for hyphens.

Series auto-discovered from the SBP open-data portal sometimes carry a numeric suffix (`_2`, `_3`) that tells apart series whose names collide.

## Modules

Every series belongs to one module. You can filter the catalog and search by module:

| Module | Covers |
|---|---|
| `forex` | PKR exchange rates, REER/NEER |
| `fixed-income` | KIBOR, policy rate, PKRV/PKISRV curves, auction cut-offs |
| `economic` | Curated flagships: CPI and groups, WPI, LSM, remittances, telecom |
| `prices` | Inflation measures, cost-of-living index by city |
| `commodities` | Weekly SPI retail prices |
| `external` | Balance of payments, trade by country, FDI, reserves, remittances by country |
| `monetary` | Money supply, banking aggregates, deep KIBOR/KIBID history, NPLs, branchless banking |
| `real` | GDP, auto, power, fuel, fertilizer, cement, corporate sector |
| `public-finance` | Federal and provincial revenue and expenditure, FBR taxes |
| `debt` | External debt, government securities holdings, national savings |
| `social` | Population, labour, literacy, education, health, confidence surveys |
| `alternate` | Digital payments (Raast, cards, POS, PRISM), SME finance |

See the [data dictionary](https://pakdatahub.com/docs/data-dictionary.md) for every module, with real ids.

## The catalog record

`GET /v1/catalog/{id}` (public) describes one series:

```json
{
  "id": "rates.kibor.3m",
  "module": "fixed-income",
  "name": "KIBOR 3-Month",
  "description": "Karachi Interbank Offered Rate, 3-month tenor (bid/offer)",
  "unit": "percent",
  "frequency": "daily",
  "source": "SBP",
  "source_url": "https://www.sbp.org.pk/ecodata/kibor/kibor.asp",
  "dimensions": { "side": ["bid", "offer"] },
  "first_date": "2005-06-09",
  "last_date": "2026-10-02",
  "tier": "basic",
  "canonical_id": null
}
```

| Field | Meaning |
|---|---|
| `unit` | e.g. `percent`, `pkr`, `index`, `count`, `usd_mn` (US$ millions), `usd_th` (thousands), `pkr_mn`, `pkr_bn`, `pkr_per_kg` |
| `frequency` | `daily`, `weekly`, `monthly`, `quarterly`, `half_yearly`, `annual` or `irregular` (e.g. auctions) |
| `dimensions` | the dimension keys and values the series carries (see below) |
| `tier` | Informational: every plan reaches every series. Plans differ by history depth, revision vintages and webhooks (see [plans](https://pakdatahub.com/docs/plans-credits.md)). |
| `canonical_id` | set when this series is a near-duplicate of another; prefer the canonical one |

## Dimensions

Some series carry more than one value per date, labelled by **dimensions**:

- **KIBOR**: `side` = `bid` or `offer`.
- **SPI commodity prices**: `city` = `karachi`, `lahore`, ... or `national`.

Filter with `dims=key:value`, and comma-separate several filters:

```bash
curl -H "X-API-Key: pk_live_xxx" \
  "https://api.pakdatahub.com/v1/series/rates.kibor.3m?dims=side:offer&from=2026-01-01"
```

Without `dims` you get every dimension's rows, each tagged in `data[].dims`.

## Discovering series

- **Search:** `GET /v1/search?q=remittances` gives ranked matches ([Search](https://pakdatahub.com/docs/api-search.md)).
- **Browse a module:** `GET /v1/catalog?module=forex` ([Catalog](https://pakdatahub.com/docs/api-catalog.md)).
- **Web:** the [coverage page](https://pakdatahub.com/coverage) and a page per series at `https://pakdatahub.com/series/{id}`.

## Getting data

Once you have an id:

```bash
curl -H "X-API-Key: pk_live_xxx" \
  "https://api.pakdatahub.com/v1/series/inflation.cpi.national.yoy?from=2020-01-01&sort=asc&format=csv"
```

See [Series endpoint](https://pakdatahub.com/docs/api-series.md) for every parameter, and [Transforms](https://pakdatahub.com/docs/api-transforms.md) for server-side YoY, MoM, % change, moving average and rebasing.

---
Source: https://pakdatahub.com/docs/series-and-catalog - PakDataHub docs index: https://pakdatahub.com/docs/llms.txt