# Macro

CPI, GDP, unemployment and policy rates from statistics offices and central banks.

## Macro observations

GET `/v1/macro/observations` 

 1 credit per series 2 credits with fresh=true Operation ID `macro.observations`

Each series' values by period. Where the publisher dates its releases, usually only the latest one, released says when a value came out, and we keep those dates from then on, so a revision shows up as a later release. Setting frequency downsamples to a coarser one, keeping only complete periods.

### Query parameters

- `series` array of strings Required  
Comma-separated codes from /v1/macro/series, up to 100  
Up to 100 items
- `from` date  
First day, YYYY-MM-DD
- `to` date  
Last day, YYYY-MM-DD
- `fresh` boolean  
Skip our cache and get the latest data. Items refreshed this way cost double
- `format` string  
Response format  
One of `json` `csv`  
Defaults to json
- `frequency` string  
Downsample to this frequency, which must not be finer than the series' own  
One of `daily` `weekly` `monthly` `quarterly` `annual`

### Response

- `data` array of objects  

  - `asOf` timestamp  
  The point in time this data describes. For history and events it's the date of the newest record, or the end of your range when there are none. Live values give when they were observed, and reference data gives when we last confirmed it
  - `code` string  
  The canonical code it resolved to
  - `frequency` string  
  The frequency served  
  One of `daily` `weekly` `monthly` `quarterly` `annual`
  - `name` string
  - `observations` array of objects  

    - `period` date  
      First day of the period
    - `released` date or null  
      When this value was published, null when unknown
    - `value` number
  - `series` string  
  The code as sent
  - `unit` string  
  One of `percent` `index` `persons`
- `errors` array of objects  

  - `code` string  
  One of `invalid_symbol` `instrument_not_found` `not_supported` `data_unavailable` `data_pending` `data_failed`
  - `message` string
  - `series` string
- `meta` object  

  - `credits` integer  
  Credits this call cost
  - `requestId` string

### Errors

`400` Bad Request`401` Unauthorized`402` Payment Required`403` Forbidden`422` Unprocessable Entity`429` Too Many Requests`500` Internal Server Error`503` Service Unavailable

Every error body is problem+json with a stable `code`. See [errors](https://quova.io/docs/index.md#errors).

```shell
curl "https://api.quova.io/v1/macro/observations?series=AU.CPI.YOY,US.POLICY_RATE&from=2026-01-01&to=2026-06-30&frequency=quarterly" \
  -H "Authorization: Bearer $QUOVA_API_KEY"
```

Response 

 200 OK 

```json
{
  "data": [
    {
      "series": "AU.CPI.YOY",
      "asOf": "2026-07-30T00:00:00Z",
      "code": "AU.CPI.YOY",
      "name": "Australia CPI, all groups, year-ended change",
      "unit": "percent",
      "frequency": "quarterly",
      "observations": [
        {
          "period": "2026-01-01",
          "value": 4.1,
          "released": null
        },
        {
          "period": "2026-04-01",
          "value": 3.9,
          "released": "2026-07-30"
        }
      ]
    },
    {
      "series": "US.POLICY_RATE",
      "asOf": "2026-04-01T00:00:00Z",
      "code": "US.POLICY_RATE",
      "name": "Federal funds target range, upper limit",
      "unit": "percent",
      "frequency": "quarterly",
      "observations": [
        {
          "period": "2026-01-01",
          "value": 3.75,
          "released": null
        },
        {
          "period": "2026-04-01",
          "value": 3.75,
          "released": null
        }
      ]
    }
  ],
  "errors": [],
  "meta": {
    "credits": 2,
    "requestId": "req_34VoxwcmYCKspnbZkBUpO"
  }
}
```

## Macro series

GET `/v1/macro/series` 

 Free Operation ID `macro.series`

Every economic series we carry, like AU.CPI.YOY or US.POLICY\_RATE, with its unit, frequency and the next expected release.

### Query parameters

- `country` string  
ISO country code, EA for the euro area  
Matches ^\[A-Za-z\]{2}$
- `category` string  
One of `inflation` `gdp` `labour` `rates`
- `frequency` string  
One of `daily` `weekly` `monthly` `quarterly` `annual`
- `fresh` boolean  
Skip our cache and get the latest data. Items refreshed this way cost double
- `format` string  
Response format  
One of `json` `csv`  
Defaults to json

### Response

- `data` array of objects  

  - `adjustment` string  
  Seasonally adjusted (sa) or not (nsa)  
  One of `sa` `nsa`
  - `aggregation` string  
  How periods combine when a coarser frequency is asked for  
  One of `mean` `sum` `last`
  - `aliases` array of strings  
  Other codes that resolve to this series
  - `category` string  
  One of `inflation` `gdp` `labour` `rates`
  - `code` string
  - `country` string
  - `frequency` string  
  One of `daily` `weekly` `monthly` `quarterly` `annual`
  - `name` string
  - `nextRelease` date or null  
  Our estimate of the next release, from the series' recent release dates once it has been fetched, and from its usual lag until then
  - `unit` string  
  One of `percent` `index` `persons`
- `meta` object  

  - `credits` integer  
  Credits this call cost
  - `nextCursor` string or null  
  Pass as cursor to get the next page, null on the last page
  - `requestId` string

### Errors

`400` Bad Request`401` Unauthorized`402` Payment Required`403` Forbidden`422` Unprocessable Entity`429` Too Many Requests`500` Internal Server Error`503` Service Unavailable

Every error body is problem+json with a stable `code`. See [errors](https://quova.io/docs/index.md#errors).

```shell
curl "https://api.quova.io/v1/macro/series?country=AU" \
  -H "Authorization: Bearer $QUOVA_API_KEY"
```

Response 

 200 OK 

```json
{
  "data": [
    {
      "code": "AU.CPI.MONTHLY.YOY",
      "aliases": [],
      "name": "Australia monthly CPI, all groups, year-ended change",
      "country": "AU",
      "category": "inflation",
      "unit": "percent",
      "frequency": "monthly",
      "adjustment": "nsa",
      "aggregation": "mean",
      "nextRelease": null
    },
    {
      "code": "AU.CPI.YOY",
      "aliases": [],
      "name": "Australia CPI, all groups, year-ended change",
      "country": "AU",
      "category": "inflation",
      "unit": "percent",
      "frequency": "quarterly",
      "adjustment": "nsa",
      "aggregation": "mean",
      "nextRelease": "2026-10-30"
    },
    {
      "code": "AU.GDP.ANNUAL_GROWTH",
      "aliases": [],
      "name": "Australia real GDP growth, calendar year",
      "country": "AU",
      "category": "gdp",
      "unit": "percent",
      "frequency": "annual",
      "adjustment": "nsa",
      "aggregation": "mean",
      "nextRelease": null
    },
    {
      "code": "AU.GDP.YOY",
      "aliases": [],
      "name": "Australia real GDP, year-ended change",
      "country": "AU",
      "category": "gdp",
      "unit": "percent",
      "frequency": "quarterly",
      "adjustment": "sa",
      "aggregation": "mean",
      "nextRelease": null
    },
    {
      "code": "AU.POLICY_RATE",
      "aliases": [
        "AU.CASH_RATE"
      ],
      "name": "RBA cash rate target",
      "country": "AU",
      "category": "rates",
      "unit": "percent",
      "frequency": "daily",
      "adjustment": "nsa",
      "aggregation": "last",
      "nextRelease": "2026-09-26"
    },
    {
      "code": "AU.UNEMPLOYMENT",
      "aliases": [],
      "name": "Australia unemployment rate",
      "country": "AU",
      "category": "labour",
      "unit": "percent",
      "frequency": "monthly",
      "adjustment": "sa",
      "aggregation": "mean",
      "nextRelease": null
    },
    {
      "code": "AU.YIELD_10Y",
      "aliases": [],
      "name": "Australian Government 10 year bond yield",
      "country": "AU",
      "category": "rates",
      "unit": "percent",
      "frequency": "daily",
      "adjustment": "nsa",
      "aggregation": "mean",
      "nextRelease": null
    }
  ],
  "meta": {
    "credits": 0,
    "requestId": "req_34Voxwd4Y4VtEstnINcCJ",
    "nextCursor": null
  }
}
```