API Reference: Economic Data and Calendars
Details
Docs navigation
- Getting started: Quickstart, Authentication, Rate limits, Errors and retries
- Guides: Symbol formats, Timestamps and time zones, Pagination, Split and dividend adjustments, WebSocket streaming, Dataset downloads, Excel and Google Sheets, Changelog
- API reference: Stock bars, Stock trades and quotes, Snapshots and movers, Tickers, exchanges, calendar, Splits and dividends, Fundamentals and SEC filings, Options chain and Greeks, Options EOD, bars, OI, Forex, Crypto, Crypto derivatives, Futures bars and continuous, Settlements and COT, Indices, Economic data (you are here), Technical indicators
- SDKs: Python, JavaScript
Macro data comes in two shapes: time series (CPI by month, the 10-year yield by day) and a calendar of when each number is released. This economic data API endpoint reference covers both, along with point-in-time history, which lets a backtest see only what was published on a given date. The source series come from US government agencies and are free on every plan.
Early access. Planned v1 endpoints, not live yet. All public series with full history are free on every plan. Starter ($29/mo) adds release-date history for point-in-time tests. Pro ($79/mo) adds consensus estimates on the calendar once we license a source. Our free economic indicators and yield curve samples are live now.
Details
Time series
GET https://api.marketdata.co/v1/economic/series
Parameters
| Name | Type | Required | Default | Description |
|---|---|---|---|---|
symbol |
string | yes | Series ID, e.g. CPIAUCSL, UNRATE, DGS10, FEDFUNDS |
|
start, end |
string | no | full history | Filter on date |
as_of |
string | no | latest | Return values as they were known on this date (Starter) |
limit, cursor, format |
no | Paging and output |
Response fields
| Field | Type | Description |
|---|---|---|
symbol |
string | Series ID |
name |
string | e.g. CPI, all urban consumers |
date |
string | Period the value refers to (the first day of the month for monthly data) |
value |
number | The number |
unit |
string | e.g. percent, index 1982-84=100 |
frequency |
string | daily, weekly, monthly, quarterly, annual |
country |
string | ISO code, e.g. US |
seasonal_adjustment |
string | SA or NSA (optional) |
tenor |
string | Yield curve only, e.g. 10Y (optional) |
release_date |
string | When this value was published (optional) |
source |
string | Agency, e.g. U.S. Bureau of Labor Statistics |
Example
Example (curl):
curl -H "Authorization: Bearer YOUR_API_KEY" \
"https://api.marketdata.co/v1/economic/series?symbol=CPIAUCSL&start=2015-01-01"
The last three CPI rows in our free sample:
symbol,series_name,date,value
CPIAUCSL,"CPI, all urban consumers",2026-08-01,334.131
CPIAUCSL,"CPI, all urban consumers",2026-09-01,336.298
CPIAUCSL,"CPI, all urban consumers",2026-10-01,337.476
Source: FRED, Federal Reserve Bank of St. Louis
The sample uses series_name; the API returns the same thing as name.
Example (Python), year-over-year CPI inflation:
import os
import requests
import pandas as pd
r = requests.get(
"https://api.marketdata.co/v1/economic/series",
headers={"Authorization": f"Bearer {os.environ['MARKETDATA_API_KEY']}"},
params={"symbol": "CPIAUCSL", "start": "2020-01-01"},
)
cpi = pd.DataFrame(r.json()["results"]).set_index("date")["value"]
print((cpi.pct_change(12) * 100).round(2).tail())
Details
Series list
GET https://api.marketdata.co/v1/economic/series-list?search=yield returns matching series with symbol, name, unit, frequency, country, source and the first and last dates we hold.
Details
Release calendar
GET https://api.marketdata.co/v1/economic/calendar
| Name | Type | Required | Default | Description |
|---|---|---|---|---|
start, end |
string | no | this week | Date range |
country |
string | no | US |
ISO code |
importance |
string | no | all | low, medium, high |
symbol |
string | no | all | Only releases of one series |
Fields: event_id, event_type (economic, central_bank, holiday and more), symbol, event_name (e.g. CPI MoM), country, date, timestamp (release time, UTC), importance, actual, estimate, previous, revised_previous and unit. actual is null until the number is out; estimate is null until consensus is licensed.
Details
Treasury yield curve
Daily par yields by tenor (UST-1M to UST-30Y) are in the same series endpoint, one series per tenor, and as a full curve per date in the bond yields API.
API
Errors for these endpoints
| HTTP | error.code |
When |
|---|---|---|
| 400 | invalid_parameter |
as_of before the series existed |
| 403 | plan_required |
as_of on Free |
| 404 | symbol_not_found |
Unknown series ID; search with series-list |
Watch out
Notes and gotchas
- Economic data is revised. The first payrolls print and the value two months later can be far apart. Without
as_of, you get the latest revised values, which a trader at the time never saw. dateis the period, not the release. October CPI hasdate2026-10-01 and comes out in November. Key backtests onrelease_date.- Daily Treasury yields have gaps on bond market holidays, which are not always stock market holidays.
- Some FRED series carry third-party copyright. We pull from the original agencies (BLS, BEA, the Federal Reserve, Treasury) where we can and credit the source in
source. - Release times on the calendar are UTC. US data at 8:30 New York time shows as
13:30Zin winter and12:30Zin summer.
Keep reading
Next steps
Details
Was this page useful?
[Yes] [No]
Need a series or country we don't carry? Tell us on the custom data form.