# Revision vintages

Official statistics get revised: GDP, the balance of payments, remittances, reserves and more. Add `?vintage=YYYY-MM-DD` to [`/v1/series/{id}`](https://pakdatahub.com/docs/api-series.md) and every observation comes back **as we had recorded it by the end of that date**.

**Plan:** Pro and Business. Lower plans get `403`.

```bash
curl -H "X-API-Key: pk_live_xxx" \
  "https://api.pakdatahub.com/v1/series/inflation.cpi.national?vintage=2026-08-31&limit=3"
```

The response has the normal series envelope. The values are the ones in effect on the vintage date.

## How it works

- Whenever a stored value changes on a later ingest, we record the old value and when it was replaced. Re-ingesting an unchanged value costs nothing and isn't a revision.
- For each `(date, dims)`, a vintage request returns the value current at the vintage date. Points first recorded **after** the vintage date are left out.
- Our own revision tracking runs from **August 2026**. Before that, history comes from the **SBP's Monthly Statistical Bulletin archive** (see below).
- To see a point's whole history at once (first print, every revision and when it happened), use [`/revisions`](#the-revisions-endpoint).
- Points with no recorded history before a vintage date come back at the earliest value we hold.

## Revision history from the SBP Statistical Bulletin (2008 ->)

Every monthly issue of the State Bank's *Monthly Statistical Bulletin* opens with a table of headline indicators for the last 12-13 months, **as published that month**. We read every issue SBP still hosts, from 2005 to 2026 (258 issues), so for the series it covers you get each month's **first print** and **every revision, dated by the issue that printed it**: the point-in-time history that no longer exists on the SBP's live site, where a revision overwrites the original. We also read the bulletin's national-accounts tables (GDP by sector, at current and constant prices, marked provisional and revised), 2005-2023. Together that is about 8,800 first prints and 7,500 dated revisions on 70 series: 59 of ours matched by value, plus the 11 below that come straight from the bulletin. The 2005-2007 issues carried an older indicators table (call money rate, WPI, industrial output), so first prints of most of today's indicators start in 2008.

Covered series (and their twins under other dataset ids):

| What | Example id |
|---|---|
| USD/PKR, month average and month end | `fx.rate.avg.usd`, `fx.rate.monthend.usd` |
| Workers' remittances | `remittances.total`, `external.workers_remittances` |
| Exports and imports of goods (BOP) | `bop.goods_export_fob`, `bop.goods_import_fob` |
| GDP by sector and in total, constant prices (bases 2005-06 and 2015-16); nominal GDP | `gdp.gross_domestic_product_total_gross_value_add_2`, `gdp.agricultural_sector_2`, `fiscal.gross_domestic_product_2` |
| FX reserves: liquid, gold & FX, net with SBP | `reserves.total_liquid_fx_reserves`, `reserves.total_reserve_assets` |
| CPI inflation YoY: national, urban, rural, food, non-food, core | `inflation.cpi.national.yoy`, `inflation.cpi.urban.yoy` |
| Real and nominal effective exchange rates | `fx.effective.reer`, `fx.effective.neer` |
| Banks' weighted-average lending and deposit rates (fresh and outstanding) | `banking.lending_marginal_overall`, `banking.deposit_stocks_overall` |
| Net portfolio investment (BOP) | `bop.net_portfolio_investment` |
| National Savings Schemes outstanding | `debt.saving_schemes_total_outstanding_amount` |
| KSE-100 index, month end | `money.kse_100_index_last_working_day_month` |

### Series that come from the bulletin itself

Some bulletin rows have no equivalent elsewhere in the catalog, so we serve them as series in their own right. Each value is the bulletin's latest print, and every earlier print is kept as a dated revision:

| What | Id | From |
|---|---|---|
| Broad money (M2), month-end | `money.m2.monthly` | 2007 |
| 1-month KIBOR, month-end and monthly average | `rates.kibor.1m.month_end`, `rates.kibor.1m.month_avg` | 2007 |
| Scheduled banks' advances-to-deposits and investment-to-deposits ratios, monthly | `banking.advances_to_deposits_ratio.monthly`, `banking.investment_to_deposits_ratio.monthly` | 2004 |
| National CPI food, non-food and NFNE core inflation; 20% trimmed-mean core (historical) | `inflation.cpi.national.food.yoy`, `inflation.cpi.national.nonfood.yoy`, `inflation.core.nfne.national.yoy`, `inflation.core.trimmed_mean.national.yoy` | 2007-2019 |
| National CPI levels on the old bases (historical) | `inflation.cpi.national.index_2000_01`, `inflation.cpi.national.index_2007_08` | 2004-2019 |

How we keep it honest:

- A bulletin row is matched to one of our series **by its values**, not its label: its figures must agree with ours to the precision printed (or, for heavily revised series such as exports, sit within 15% across most months). Each series takes rows of one label family and one unit only, and a rebased index is never mixed with its old base.
- A series whose final printed figures often stay far from today's values is a different concept that only coincides in most months (the bulletin's total FDI and portfolio investment vs our narrower series, for example). Those are left out rather than recorded as revisions.
- A figure printed in a single issue and contradicted on both sides is treated as a reading slip and dropped. A misprint that SBP carried for several issues is kept, because it was the published number: the July 2010 lending rate printed as 36.36% for eight issues before it became 13.36%.
- Each figure is dated at the end of the month its issue came out, a conservative "public by" date. If a figure was revised after the bulletin stopped printing it, we can't date that change, so the bulletin's last value counts as current until our own tracking began (August 2026).

```bash
# Remittances for Feb-Apr 2015 as published on 30 June 2015 (first prints)
curl -H "X-API-Key: pk_live_xxx" \
  "https://api.pakdatahub.com/v1/series/remittances.total?vintage=2015-06-30&from=2015-02-01&to=2015-04-30&sort=asc"
```

## The `/revisions` endpoint

`GET /v1/series/{id}/revisions` lists each point's history in one call: the first print, every figure it replaced with the date it stopped being current and where that print came from, and today's value. Same plan as vintages (Pro and Business; `403` otherwise). Parameters: `from`, `to`, `dims`, `limit`, `sort`, and `changed_only=true` to keep only points that were ever revised.

```bash
curl -H "X-API-Key: pk_live_xxx"   "https://api.pakdatahub.com/v1/series/bop.goods_export_fob/revisions?from=2020-01-01&to=2020-01-31"
```

January 2020 exports (US$ million): first printed as 2,051, revised to 2,052, then 2,053, and 2,056 today.

```json
{
  "success": true,
  "series": "bop.goods_export_fob",
  "data": [
    { "date": "2020-01-31", "dims": {}, "value": 2056.0, "first_print": 2051,
      "first_seen": "2020-03-31",
      "revisions": [
        { "value": 2051.0, "until": "2020-04-30", "source": "SBP Monthly Statistical Bulletin" },
        { "value": 2052.0, "until": "2020-08-31", "source": "SBP Monthly Statistical Bulletin" },
        { "value": 2053.0, "until": "2026-08-17", "source": "SBP Monthly Statistical Bulletin" }
      ] }
  ],
  "pagination": { "next_cursor": null, "count": 1, "revised_points": 1 }
}
```

`first_seen` is the date the figure was first public (the end of the month of the first issue that printed it, or when our own tracking first recorded it). `source` is `PakDataHub revision tracking` for revisions we recorded ourselves since August 2026. A last bulletin figure that differs from today's value, with no dated print of the change, is shown as superseded on 17 August 2026, when our own tracking began.

## Uses

- **Reproducibility:** rerun a model on the data exactly as it stood when the model was built.
- **Nowcasting and backtests:** train only on the numbers that were actually available at the time.
- **Revision studies:** first print vs latest print. Combine with a transform for a first-print YoY:

```bash
curl -H "X-API-Key: pk_live_xxx" \
  "https://api.pakdatahub.com/v1/series/inflation.cpi.national?vintage=2026-08-31&transform=yoy"
```

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