Economic Calendar API
Last updated:
Know what macro data is landing next, and what the last print said. This endpoint returns the release schedule for every covered US economic indicator — last release date, next release date, days remaining, and release state — bundled with the latest reported value, the prior value, and the absolute and percentage change between them. One call gives you everything an economic calendar widget needs, already sorted by the next release date, so you never have to stitch a schedule table to a values table yourself. Filter by category, by release state, by specific codes, or by a date window to build a week ahead view. Pair it with the Economic Data API when you need the full history behind any of these numbers. The API is free to use.
Every row carries a release state:
https://data.businessquant.com/calendar/economic?category={categories}&api_key={api_key}
Related endpoints: Pull the full time-series behind any calendar row with the Economic Data API, which shares the same indicator codes. Discover valid codes and categories through /economic/list. Track company level events alongside macro releases with the Corporate Actions API.
1. Request Parameters
Every parameter except api_key is optional. Calling the endpoint bare returns the full calendar for all active indicators, ordered by next release date with unscheduled indicators last. Filters combine with AND logic, so a category filter and a release state filter narrow the set together.
| Parameter | Description |
|---|---|
| api_key |
Required
Your unique API key for authentication.
|
| category |
Optional
Comma separated list of indicator categories. Valid values come from the categories array returned by /economic/list.
Format:
category=Inflation,Employment |
| release_state |
Optional
Comma separated list of release states. Use upcoming to build a week ahead view, or released to show only indicators whose latest print is already published.
Format:
release_state=upcoming |
| code |
Optional
Identifier
Comma separated list of indicator codes, for watchlist style calendars. Case insensitive. No maximum count applies on this endpoint.
Format:
code=CPIYOY,UNRATE |
| from_date |
Paired
Lower bound on next_release, in YYYY-MM-DD format. Must be supplied together with till_date — sending one without the other returns 400.
Format:
from_date=2026-08-01 |
| till_date |
Paired
Upper bound on next_release, in YYYY-MM-DD format. Must be on or after from_date, otherwise the request returns 400.
Format:
till_date=2026-08-07 |
curl -X GET "https://data.businessquant.com/calendar/economic?api_key=YOUR_API_KEY"
curl -X GET "https://data.businessquant.com/calendar/economic?from_date=2026-08-01&till_date=2026-08-07&api_key=YOUR_API_KEY"
2. Sample Response
Rows arrive sorted by next_release ascending, with indicators that have no scheduled date pushed to the end. Each row is self contained: the descriptor fields tell you what the indicator is, the release fields tell you when it moves, and the value fields tell you where it stands. Numeric values are rounded to each indicator's own declared precision, so you can render them directly without stripping floating point artefacts.
File not found:
templates/api-responses/economic-calendar.json
3. Response Field Reference
Unlike the historic endpoint, every calendar row is flat and complete. The fields below are grouped by what they describe, though they all arrive as siblings inside each object in the data array.
Metadata Fields
| Field | Type | Description |
|---|---|---|
| total_indicators | integer | Number of calendar entries returned after all filters were applied. |
Data Fields — Indicator Descriptors
| Field | Type | Description |
|---|---|---|
| indicator_id | integer | Internal series key, stable across code changes. |
| code | string | Indicator code. Pass this straight to /economic to retrieve the full history. |
| name | string | Full descriptive name of the indicator. |
| category | string | Thematic grouping used by the category filter. |
| direction | string | Whether a rising value is economically favourable. Use it to decide whether green or red is the correct colour for a positive change. |
| freq | string | Short release frequency code. |
| freq_long | string | Human readable release frequency, suitable for display. |
| seasonal_adj | string | Seasonal adjustment status of the series. |
| display_unit | string | Unit the values are expressed in. |
| decimals | integer | Precision this indicator publishes at. Values below are already rounded to it. |
Data Fields — Release Schedule
| Field | Type | Description |
|---|---|---|
| last_release | string|null | Date the most recent print was published. |
| next_release | string|null | Date the next print is scheduled for. Rows are sorted on this field, and rows where it is null appear last. |
| days_until_next | integer|null | Days remaining until the next release. Drive countdown badges from this rather than computing it client side. |
| release_state | string | Either upcoming or released. Matches the values accepted by the release_state filter. |
Data Fields — Latest Values
| Field | Type | Description |
|---|---|---|
| latest_date | string|null | Reference period the latest value describes, which is usually earlier than last_release. |
| latest_value | number|null | Most recent reported value, rounded to the indicator's own decimals. |
| prior_value | number|null | Value from the preceding period, for direct period on period comparison. |
| change_abs | number|null | Absolute change from prior to latest, in the indicator's own unit, rounded to its declared precision. |
| change_pct | number|null | Percentage change from prior to latest, always rounded to two decimals regardless of the indicator's precision. |
4. Behaviour Notes
An empty result is not an error
When you apply filters and nothing matches, the endpoint returns 200 with an empty data array and total_indicators: 0. Nothing scheduled in a quiet week is a legitimate answer, not a failure. A 404 only occurs on an unfiltered call that comes back empty, which indicates a data problem on our side.
Date filters apply to the next release
The from_date and till_date window filters on next_release, not on last_release or latest_date. It answers what is coming in this window, which is what a calendar view needs. Supply both bounds or neither.
Only active indicators are returned
Discontinued and retired series are excluded from the calendar automatically. Their history remains available through the Economic Data API, so archived charts continue to render even once an indicator stops publishing.
Values are pre rounded
Each indicator declares its own precision, and latest, prior, and absolute change are rounded to it before serialisation. This removes binary floating point artefacts, so a value reads as 1.98 rather than 1.9799999999999898. Percentage change is always given to two decimals.
Economic Calendar Request Examples
Copy any request below directly into your application.
https://data.businessquant.com/calendar/economic?api_key=YOUR_API_KEY
https://data.businessquant.com/calendar/economic?from_date=2026-08-01&till_date=2026-08-07&api_key=YOUR_API_KEY
https://data.businessquant.com/calendar/economic?category=Inflation,Employment&release_state=upcoming&api_key=YOUR_API_KEY
https://data.businessquant.com/calendar/economic?code=CPIYOY,UNRATE,GDP&api_key=YOUR_API_KEY
Frequently Asked Questions
What does the Economic Calendar API return?
One row per active US economic indicator, carrying its release schedule and its latest reading together. That includes the last release date, the next scheduled release date, days remaining, release state, the latest and prior values, and the absolute and percentage change between them. Rows arrive sorted by next release date.
How do I build a week ahead economic calendar?
Pass from_date and till_date covering the week you want. The window filters on the next scheduled release date, and results come back already ordered, so you can render the response directly without sorting. Add release_state=upcoming to exclude anything already published.
Why do I need to send both from_date and till_date?
The date filter is a bounded window rather than an open ended one, so sending only one bound returns a 400 asking for the pair. This is deliberate: an open ended calendar query would return every future release ever scheduled, which is rarely what a calendar view wants.
What is the difference between latest_date and last_release?
The latest_date is the period the number describes, and last_release is the day it was published. A monthly figure for June is typically released in July, so the two dates differ. Display latest_date when labelling the value, and last_release when talking about the event.
Can I get the full history behind a calendar entry?
Yes. Every calendar row includes a code, which you can pass straight to the Economic Data API for the complete time-series, with optional transformation into percentage change, drawdown from a running high, or gain from a running low.
Is the Economic Calendar API free to use?
Yes, the Economic Calendar API is free to use. Sign up for an API key to start pulling release schedules immediately.