Macro data

Official macroeconomic data read from the publishers themselves (central banks, statistics agencies, ministries), never from an aggregator. Reference: Macro routes.

Series and observations#

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#

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#

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#

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.

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#

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#

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). terms_read_on is the day a person last read the publisher's terms; null means nobody has.

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); a publisher whose terms forbid redistribution is not read. The catalogue (/series) is the authoritative list of what is served.

Computed series#

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#

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.