# Macro data

> The economic calendar, official macro series and their observations, and derived series.

Page: https://docs.aggre.org/api/data/macro · Section: API reference · All pages: https://docs.aggre.org/llms.txt

Official macroeconomic series and the release calendar. Read the [macro guide](https://docs.aggre.org/datasets/macro.md) first for versions (revisions), units and the attribution rule.

On this page:

- [Scheduled economic releases](#listCalendarEvents): `GET /v1/finance/macro/calendar_events`
- [The macro series catalogue](#listMacroSeries): `GET /v1/finance/macro/series`
- [Observations of one series](#listMacroObservations): `GET /v1/finance/macro/observations`
- [The computed macro series catalogue](#listMacroDerivedSeries): `GET /v1/finance/macro_derived/series`
- [Computed values of one series](#listMacroDerivedObservations): `GET /v1/finance/macro_derived/observations`

## Scheduled economic releases {#listCalendarEvents}

`GET /v1/finance/macro/calendar_events`

The schedule only: no estimates, no actual or previous values. `impact` is Aggre's own grading. Whoever shows an event shows its `credit`. `next_cursor` is always null. Dataset `finance.macro.calendar_events`.

**Parameters**

| Name | In | Required | Type | Description |
|---|---|---|---|---|
| `from` | query | no | integer, int64 | Unix ms, inclusive (on `ts`). |
| `to` | query | no | integer, int64 | Unix ms, exclusive (on `ts`). Must be later than `from`. |
| `source` | query | no | `BLS` \| `BEA` \| `CENSUS` \| `FOMC` \| `ECB` \| `ONS` \| `EUROSTAT` |  |
| `economy` | query | no | string, pattern `^[A-Z]{2}$` | Two uppercase letters; EU = euro area. |
| `limit` | query | no | integer, 1–1000, default `100` | Rows per page. |
| `order` | query | no | `asc` \| `desc` (default `asc`) | Sort direction (default oldest first). |

**Example**

```bash
curl -s "https://api.aggre.org/v1/finance/macro/calendar_events?limit=3" \
  -H "Authorization: Bearer $AGGRE_API_KEY"
```

**Response** `200`: the envelope `{ "data": [...], "meta": {...}, "next_cursor": ... }` (see [Response format](https://docs.aggre.org/concepts/response-format.md)); each row of `data` follows the schema [`calendar_events`](https://docs.aggre.org/api/schemas.md#calendar_events).

**Errors**: `400`, `401`, `403`, `429`, `503`, in the shared envelope ([Errors](https://docs.aggre.org/concepts/errors.md)).

## The macro series catalogue {#listMacroSeries}

`GET /v1/finance/macro/series`

Ordered by `series_id`. Dataset `finance.macro.series`.

**Parameters**

| Name | In | Required | Type | Description |
|---|---|---|---|---|
| `source` | query | no | string | Lowercase letters, digits and underscores. |
| `economy` | query | no | string, pattern `^[A-Z]{2}$` | Two uppercase letters; EU = euro area. |
| `frequency` | query | no | `daily` \| `weekly` \| `monthly` \| `quarterly` \| `annual` \| `irregular` |  |
| `cursor` | query | no | string | The previous page's `next_cursor`, unchanged. Opaque; a cursor from another route is 400. |
| `limit` | query | no | integer, 1–1000, default `100` | Rows per page. |

**Example**

```bash
curl -s "https://api.aggre.org/v1/finance/macro/series?limit=3" \
  -H "Authorization: Bearer $AGGRE_API_KEY"
```

**Response** `200`: the envelope `{ "data": [...], "meta": {...}, "next_cursor": ... }` (see [Response format](https://docs.aggre.org/concepts/response-format.md)); each row of `data` follows the schema [`macro_series`](https://docs.aggre.org/api/schemas.md#macro_series).

**Errors**: `400`, `401`, `403`, `429`, `503`, in the shared envelope ([Errors](https://docs.aggre.org/concepts/errors.md)).

## Observations of one series {#listMacroObservations}

`GET /v1/finance/macro/observations`

A revision is a new `version`, never an overwrite. `value x unit_multiplier` is in `unit`. Whoever shows a value shows its `credit`. `meta.series` is the series row. Dataset `finance.macro.observations`.

**Parameters**

| Name | In | Required | Type | Description |
|---|---|---|---|---|
| `series_id` | query | yes | string | e.g. fed.effr; list them at /v1/finance/macro/series. An unknown id is 404. |
| `from` | query | no | string, date | YYYY-MM-DD on `period`, inclusive. |
| `to` | query | no | string, date | YYYY-MM-DD on `period`, exclusive. |
| `as_of` | query | no | integer, int64 | Unix ms: each period as Aggre knew it then (the highest version first seen at or before it). |
| `versions` | query | no | `latest` \| `all` (default `latest`) | `latest` = highest version per period; `all` = every revision. |
| `order` | query | no | `asc` \| `desc` (default `asc`) | Sort direction (default oldest first). |
| `cursor` | query | no | string | The previous page's `next_cursor`, unchanged. Opaque; a cursor from another route is 400. |
| `limit` | query | no | integer, 1–1000, default `100` | Rows per page. |

**Example**

```bash
curl -s "https://api.aggre.org/v1/finance/macro/observations?series_id=fed&limit=3" \
  -H "Authorization: Bearer $AGGRE_API_KEY"
```

**Response** `200`: the envelope `{ "data": [...], "meta": {...}, "next_cursor": ... }` (see [Response format](https://docs.aggre.org/concepts/response-format.md)); each row of `data` follows the schema [`macro_observation`](https://docs.aggre.org/api/schemas.md#macro_observation).

**Errors**: `400`, `401`, `403`, `404`, `429`, `503`, in the shared envelope ([Errors](https://docs.aggre.org/concepts/errors.md)).

## The computed macro series catalogue {#listMacroDerivedSeries}

`GET /v1/finance/macro_derived/series`

Series Aggre computes on read; nothing is stored: the year-over-year change of 30 stored series (`twtrade`, `twdgbas`), ten sums and ratios over the rows of the FSC Banking Bureau's issuer and bank files, five sums, counts and medians over the exchange's monthly revenue file (`twfsc.*`), fourteen monthly series of counted deals and median price per ping from the Ministry of the Interior's actual-price registry (`twrealprice.*`), the Treasury's monthly interest expense on public issues (`fiscal.interest_expense_public`, the sum of the 29 stored `fiscal.ie_*` lines; `rows_used` counts the lines present) and, for every CFTC contract whose long, short and open-interest series are stored, the net position (long - short, `cftc.<key>_net`) and its share of open interest in percent (`cftc.<key>`). Listed only while what it is computed from exists, and, for rows of an entity dataset, only once somebody has read the publisher's terms. Same filters as the stored catalogue; `inputs` and `formula` say what each is computed from. Ordered by `series_id`. Dataset `finance.macro_derived.series`.

**Parameters**

| Name | In | Required | Type | Description |
|---|---|---|---|---|
| `source` | query | no | string | Lowercase letters, digits and underscores. |
| `economy` | query | no | string, pattern `^[A-Z]{2}$` | Two uppercase letters; EU = euro area. |
| `frequency` | query | no | `daily` \| `weekly` \| `monthly` \| `quarterly` \| `annual` \| `irregular` |  |
| `cursor` | query | no | string | The previous page's `next_cursor`, unchanged. Opaque; a cursor from another route is 400. |
| `limit` | query | no | integer, 1–1000, default `100` | Rows per page. |

**Example**

```bash
curl -s "https://api.aggre.org/v1/finance/macro_derived/series?limit=3" \
  -H "Authorization: Bearer $AGGRE_API_KEY"
```

**Response** `200`: the envelope `{ "data": [...], "meta": {...}, "next_cursor": ... }` (see [Response format](https://docs.aggre.org/concepts/response-format.md)); each row of `data` follows the schema [`macro_derived_series`](https://docs.aggre.org/api/schemas.md#macro_derived_series).

**Errors**: `400`, `401`, `403`, `429`, `503`, in the shared envelope ([Errors](https://docs.aggre.org/concepts/errors.md)).

## Computed values of one series {#listMacroDerivedObservations}

`GET /v1/finance/macro_derived/observations`

`value x unit_multiplier` is in `unit`. A year-over-year value (percent) is the input's change against the same period one year earlier (`compared_with`), from the newest stored version of both; a value over rows carries `rows_used`, how many issuers, banks, companies or deals it is computed from; a `twrealprice` value carries `provisional`, true for the latest three months published. A revised input revises the value on the next read. A period with nothing to compute from has no row. Whoever shows a value shows its `credit`. `meta.series` is the computed series row; `meta.status` follows what it is computed from. 404 `not_found` for an id that is not computed from anything read yet; 503 `terms_unread` for one over an entity dataset whose publisher terms nobody has read. Dataset `finance.macro_derived.observations`.

**Parameters**

| Name | In | Required | Type | Description |
|---|---|---|---|---|
| `series_id` | query | yes | string | e.g. twtrade.exports_yoy; list them at /v1/finance/macro_derived/series. An unknown id is 404. |
| `from` | query | no | string, date | YYYY-MM-DD on `period`, inclusive. |
| `to` | query | no | string, date | YYYY-MM-DD on `period`, exclusive. |
| `order` | query | no | `asc` \| `desc` (default `asc`) | Sort direction (default oldest first). |
| `cursor` | query | no | string | The previous page's `next_cursor`, unchanged. Opaque; a cursor from another route is 400. |
| `limit` | query | no | integer, 1–1000, default `100` | Rows per page. |

**Example**

```bash
curl -s "https://api.aggre.org/v1/finance/macro_derived/observations?series_id=twtrade&limit=3" \
  -H "Authorization: Bearer $AGGRE_API_KEY"
```

**Response** `200`: the envelope `{ "data": [...], "meta": {...}, "next_cursor": ... }` (see [Response format](https://docs.aggre.org/concepts/response-format.md)); each row of `data` follows the schema [`macro_derived_observation`](https://docs.aggre.org/api/schemas.md#macro_derived_observation).

**Errors**: `400`, `401`, `403`, `404`, `429`, `503`, in the shared envelope ([Errors](https://docs.aggre.org/concepts/errors.md)).