# Macro data

> Official macroeconomic series, their revisions as versions, the release calendar and computed series.

Page: https://docs.aggre.org/datasets/macro · Section: Datasets · All pages: https://docs.aggre.org/llms.txt

Official macroeconomic data read from the **publishers themselves** (central banks, statistics agencies, ministries), never from an aggregator. Reference: [Macro routes](https://docs.aggre.org/api/data/macro.md).

## Series and observations {#series}

`GET /v1/finance/macro/series` is the catalogue (ordered by `series_id`; filters `source`, `economy`, `frequency`). `GET /v1/finance/macro/observations?series_id=...` returns the values of one series. An unknown `series_id` is `404 not_found`.

A series has a `series_id` of the form `{source}.{code}` (for example `fed.effr`), an `economy` (two uppercase letters, `EU` for the euro area), a `frequency` (`daily`, `weekly`, `monthly`, `quarterly`, `annual`, `irregular`), a `unit`, a `unit_multiplier`, an optional seasonal adjustment, its `credit` and `terms_read_on`.

### Units {#units}

`unit` says what the number is (`percent`, `index`, `usd`, ...) and `unit_multiplier` how many of that unit one stored value is, so **`value × unit_multiplier` is in `unit`**. Nothing is converted on the way in: a publisher that states "millions of dollars" is stored as unit `usd`, multiplier `1000000`, value as published. Once a series has observations its unit, multiplier, currency, frequency, adjustment, economy and source never change; a series whose meaning changes gets a new id.

### Periods {#periods}

`period` is a date: a month or a quarter is its first day, a year is 1 January, a week is the day the publisher assigns, a day is itself. A value the publisher leaves out (`ND`, `-`, empty) is absent, never zero.

### Revisions {#revisions}

A revision is a **new version**, never an overwrite. An observation is identified by `(series_id, period, version)`; the first value read for a period is version 1, and a later read that returns a different value or label stores the next version.

| Parameter | Result |
|---|---|
| `versions=latest` (default) | The highest version per period |
| `versions=all` | Every version (a page never splits one period's versions) |
| `as_of=<Unix ms>` | Each period as Aggre knew it then: the highest version first seen at or before that instant; periods first read later are absent. An `as_of` view is never reported stale |

`revision` (`advance`, `preliminary`, `revised`, `final`, ...) and `published_on` are the publisher's own words, `null` when it states none. Use `as_of` for backtests that must not see later revisions.

### Freshness {#freshness}

`meta.dataDate` on observations is Aggre's last successful read of the publisher (`last_read_at`), not an observation period. `meta.status` is `stale` when the series has a freshness window and the last read is older than it, not judged for `as_of` views or for a series with `discontinued_on`.

## Attribution {#attribution}

`credit` is the text the publisher's terms ask for, stored once per series and returned on every observation row. **Whoever shows a value shows its `credit`** ([Attribution](https://docs.aggre.org/concepts/attribution.md)). `terms_read_on` is the day a person last read the publisher's terms; `null` means nobody has.

## Publishers {#publishers}

The macro collector is built to read official sources including the Federal Reserve, BLS, BEA, the Census Bureau, the New York Fed, the US Treasury, CFTC, EIA, FHFA and OFR in the United States; the ECB, the Bank of England, Eurostat, ONS and OECD in Europe; the Ministry of Finance, Japan Customs, the Cabinet Office and e-Stat in Japan; Hong Kong's Census and Statistics Department; Taiwan's DGBAS, NDC, Central Bank, Ministry of Finance, FSC and Ministry of the Interior; and the BIS, IMF and World Bank. A source is served only after its terms are recorded as read ([Freshness](https://docs.aggre.org/concepts/freshness.md#terms)); a publisher whose terms forbid redistribution is not read. The catalogue (`/series`) is the authoritative list of what is served.

## Computed series {#derived}

`GET /v1/finance/macro_derived/series` and `/observations` serve values **Aggre computes on read**: nothing is stored and none appears in `macro/series`. All rows have `kind: computed`.

1. The year-over-year change of stored series (the derived id is the input's plus `_yoy`): `value = (input at period / input at compared_with − 1) × 100`, from the newest stored version of both; no row where the earlier value is absent or zero.
2. Sums and ratios over the rows of Taiwan FSC Banking Bureau files (cards, deposits, loans, non-performing ratios).
3. Counts and median prices per ping over Taiwan Ministry of the Interior actual-price deals, nationally and for six cities, by month.
4. Sums, counts and medians over the exchange's monthly revenue file for listed companies. These medians are computed from amounts and can differ slightly from medians of published percentages.

A row is `{series_id, period, value, unit, unit_multiplier, compared_with, rows_used, provisional, credit}`. A revised input revises the value on the next read. The series `credit` is the publisher's followed by a sentence saying Aggre computed the figure. A derived series over an entity dataset is listed only while its terms are read; `/observations` of one whose terms are unread is `503 terms_unread`.

## Economic calendar {#calendar}

`GET /v1/finance/macro/calendar_events` lists scheduled releases: **the schedule only**, no estimates and no actual or previous values.

- Filters (all optional; unknown or repeated ones are 400): `from`, `to` (Unix ms on `ts`), `source` (`BLS`, `BEA`, `CENSUS`, `FOMC`, `ECB`, `ONS`, `EUROSTAT`), `economy`, `limit`, `order` (default `asc`: a calendar reads forward).
- `ts` is the release instant (UTC). Where the publisher gives the day and not the time, `date_only` is `true` and `ts` is the start of that UTC day; no time is made up.
- `impact` is Aggre's own grading (`impact_basis` is always `editorial`), not the publisher's.
- `origin` is `feed` (read from the publisher's machine-readable schedule) or `manual` (a hand-kept table a person checked against the publisher on `verified_on`); a manual row without a verification date is never served.
- A schedule is replaced as a whole per source, so a moved or withdrawn release disappears from the future while past events stay.