# Catalog

The catalog describes every series: its id, name, unit, frequency, source, date range and dimensions. It is **public**, so no key is needed. Use it to build pickers, find ids, or list everything.

## `GET /v1/catalog`

List and filter series metadata.

| Param | Type | Default | Notes |
|---|---|---|---|
| `module` | string | - | `forex`, `fixed-income`, `economic`, `prices`, `commodities`, `external`, `monetary`, `real`, `public-finance`, `debt`, `social`, `alternate` |
| `source` | string | - | `SBP`, `PBS`, `PTA`, `MUFAP` |
| `q` | string | - | Full-text filter over id, name and description |
| `limit` | int | 500 | 1-5000 |
| `offset` | int | 0 | For paging through large modules |
| `canonical_only` | bool | false | Drop near-duplicate series that point at a canonical one |

```bash
curl "https://api.pakdatahub.com/v1/catalog?module=forex&q=usd&limit=2"
```

```json
{
  "success": true,
  "data": [
    { "id": "fx.rate.avg.usd", "module": "forex",
      "name": "Average Exchange rate of Pak Rupees per U.S. Dollar",
      "description": "Average Exchange rate of Pak Rupees per U.S. Dollar",
      "unit": "pkr", "frequency": "monthly", "source": "SBP",
      "source_url": "https://easydata.sbp.org.pk/api/v1/series/TS_GP_ER_FAERPKR_M.E00220/data",
      "dimensions": {}, "first_date": "1947-08-31", "last_date": "2026-08-31",
      "tier": "basic", "canonical_id": null },
    { "id": "fx.rate.monthend.usd", "module": "forex", "...": "..." }
  ],
  "pagination": { "next_cursor": null, "count": 100 }
}
```

`pagination.count` is the **total** number of matches, so page with `offset` until you've read `count` rows. For example, the `external` module holds 9,176 series:

```python
import httpx
rows, offset = [], 0
while True:
    page = httpx.get("https://api.pakdatahub.com/v1/catalog",
                     params={"module": "external", "limit": 5000, "offset": offset}).json()
    rows += page["data"]
    offset += 5000
    if offset >= page["pagination"]["count"]:
        break
print(len(rows))
```

## `GET /v1/catalog/{series_id}`

The full record for one series. It is **not** wrapped in an envelope:

```bash
curl "https://api.pakdatahub.com/v1/catalog/rates.kibor.3m"
```

```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 }
```

An unknown id returns `404 not_found`. The fields are explained in [Series & the catalog](https://pakdatahub.com/docs/series-and-catalog.md#the-catalog-record).

## Tips

- For a ranked "best match" rather than a filter, use [`/v1/search`](https://pakdatahub.com/docs/api-search.md).
- `last_date` tells you how fresh a series is without spending a keyed request.
- Every series also has a web page at `https://pakdatahub.com/series/{id}`.

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