austrian-cpi/README.md

Query and merge Austrian CPI time series data for economic modeling

# austrian-cpi v1.0.9
## Lightweight utilities for querying, merging & **using** Austrian Consumer-Price-Index (CPI) time-series in JavaScript / Node.js
**Last Update: 19.7.2025 (Next Update: 21.08.2025)**

A lightweight, zero-dependency helper for working with Austrian CPI tables from Statistik Austria—perfect for dashboards, data-science notebooks, web applications, Node.js backend services, or quick forward- and backward-inflation adjustments and pricing algorithms based on the main/primary Austrian CPI Basket.

---

## 📦 Installation

```bash
npm install austrian-cpi
```

### NPM Link

View on NPM: https://www.npmjs.com/package/austrian-cpi

### As Standalone

Clone or download this repo and include `austrian-cpi/src/*.js`.

## Features

- **Query CPI** by month (`YYYY-MM`) or year (`YYYY`)
- **Filter** one or many CPI series (e.g. `vpi_2020`, `khpi`)
- Supports **monthly and yearly** frequencies
- **Export** any result to CSV
- **Merge** CPI rows into external datasets on the shared `date` key
- Retrieve the **latest (Month-over-Month, Year-over-Year) CPI value** for any series
- Compute **rate-of-change (RoC)**
  - between the latest two observations
  - between arbitrary two `start → end` dates
- **EXPERIMENTAL: Functions to convert nominal prices to real buying power euros based on series and reference date point**
  - `convertPrice()` – single value
  - `convertPrices()` – vectorised version for full arrays

*Note: All helpers support seamless **monthly → yearly fallback**, so you still get results when a monthly observation is missing but a yearly value for the CPI time series exists.

## 🚀 Quick start

```js
import {
  /* ── Queries API, merging & export ────────────────────────-----─────---------──── */
  queryCPI, mergeWith, exportToCSV,

  /* ── Latest Value and RoC & rate‑of‑change over window computations ──────────---- */
  getLatestValue, getLatestRateOfChange, getRateOfChange,

  /* ── EXPERIMENTAL: Constant‑price conversion ───────────────────────────────────── */
  convertPrice, convertPrices, deflateSeries,

  /* ── EXPERIMENTAL: Inflation metrics ───────────────────────────────────────────── */
  inflationRate, inflationSeries, annualiseRate,

  /* ── EXPERIMENTAL:  Real growth ─────────────────────────────────────────────────── */
  realCAGR,
} from "austrian-cpi";

/* 1 — query CPI rows for different CPI series, iff existing */
const cpi = queryCPI("2010-01", "2015-12", {
  frequency: "monthly",
  series: ["vpi_2020", "khpi"],
});
console.table(cpi);

/* 2 — merge with your data & export as CSV */
const sales = [
  { date: "2012-05", sales: 100 },
  { date: "2013-09", sales: 105 },
];
console.log(exportToCSV(mergeWith(cpi, sales)));

/* 3 — latest value & latest Month-over-Month (MoM), Year-over-Year (YoY) change */
console.log(getLatestValue("vpi_66", "monthly"));
console.log(getLatestRateOfChange("vpi_66", "monthly"));

/* 4 — EXPERIMENTAL: Custom rate‑of‑change window */
console.log(
  getRateOfChange("vpi_66", { start: "2022-01", end: "2023-12" }),
);

/* 5 — EXPERIMENTAL:  deflate prices to constant euros */
const basket = [
  { date: "2022-11", price: 14.9 },
  { date: "2023-08", price: 16.0 },
];
const real = convertPrices(basket, {
  baseDate: "2021-01",
  seriesKey: "vpi_2010",
});
console.table(real);

/* 6 — EXPERIMENTAL: monthly inflation series & annualised rate */
const months2023 = Array.from({ length: 12 }, (_, i) => `${2023}-${String(i + 1).padStart(2, "0")}`);
console.table(inflationSeries(months2023, { seriesKey: "vpi_2020" }));
console.log("Annualised +1 % monthly:", (annualiseRate(0.01, 12) * 100).toFixed(2), "%");

/* 7 — EXPERIMENTAL: real CAGR */
console.log(
  "Real CAGR 2020‑11 → 2024‑12:",
  (realCAGR(14.99, "2020-11", 19.99, "2024-12", { seriesKey: "vpi_66" }) * 100).toFixed(2), "% p.a.");
```

## Data and Legal Disclaimer

This package includes historical Austrian CPI data derived from publicly available statistics by Statistik Austria.
It is not an official source. Use for informational or modeling purposes only. For legally binding or financial decisions, verify against the official data.
(👉 https://www.statistik.at/statistiken/volkswirtschaft-und-oeffentliche-finanzen/preise-und-preisindizes/verbraucherpreisindex-vpi/hvpi, Last Update: 19.7.2025, Additional formats (.ods, .pdf) and details available under "Detailergebnisse" on Statistik Austria's page.)

## License

MIT