Economic Data API
Last updated:
Retrieve historical time-series for US economic indicators — GDP, CPI and inflation, the unemployment rate, interest rates, housing starts, retail sales, industrial production, and more — through a single REST endpoint. Every indicator ships with a full descriptor block covering its release frequency, seasonal adjustment status, display unit, decimal precision, and direction, so you never have to hard-code units or hunt for what a series actually measures. Four transformation modes let the API return raw levels, percentage change rebased to the start of your window, drawdown from a running high, or gain from a running low — computed server-side, so you can chart inflation against unemployment without normalising anything yourself. Discover every valid code through the Economic Indicators List API, and pair it with the Economic Calendar API to know when the next print lands. The API is free to use.
Four transformation modes available:
https://data.businessquant.com/economic?code={codes}&mode={mode}&api_key={api_key}
Related endpoints: Look up valid codes and categories in the Economic Indicators List API. Track release schedules and the latest prints with the Economic Calendar API. Overlay macro series on equity prices using the Stock Quotes API, which supports the same four transformation modes. Connect the macro backdrop to company results with the Financial Statements API.
1. Request Parameters
Provide an API key and at least one indicator code. Up to five codes can be requested in a single call, returned as one merged data array keyed by code. The E: prefix is optional — CPIYOY and E:CPIYOY resolve to the same series. Retrieve the full list of valid codes from the Economic Indicators List API.
| Parameter | Description |
|---|---|
| api_key |
Required
Your unique API key for authentication.
|
| code |
Required
Identifier
Comma separated list of economic indicator codes. Maximum of 5 per request. Case insensitive, and the E: prefix is optional. Requesting an unknown code returns 404 naming the codes that failed.
Format:
code=GDP,CPI,UNRATE |
| mode |
Optional
Transformation applied to value before it is returned. One of original (default), normalized, pct_from_high, or pct_from_low. Each series is transformed independently, so multiple codes stay directly comparable. See section 3 for the exact formulas.
Format:
mode=normalized |
| period |
Optional
Relative lookback window, expressed as a number followed by d, w, mo, or y. Also accepts ytd and max. Takes precedence over from_date. Passing max disables pagination and returns the entire history in one response.
Examples:
period=6mo · period=10y · period=ytd · period=max |
| from_date |
Optional
Start of an explicit date window, in YYYY-MM-DD format. Ignored when period is supplied. A malformed date returns 400.
Format:
from_date=2015-01-01 |
| till_date |
Optional
End of an explicit date window, in YYYY-MM-DD format. Used together with from_date. A till_date earlier than from_date returns 400.
Format:
till_date=2026-06-30 |
| skip |
Optional
Number of rows to skip before returning results. Defaults to 0. Not applied when period=max.
Format:
skip=500 |
| limit |
Optional
Maximum number of rows to return. Defaults to 10000. Not applied when period=max. Note that the limit spans the merged result set, so a five code request divides the budget across all five series.
Format:
limit=2000 |
curl -X GET "https://data.businessquant.com/economic?code=CPIYOY&period=10y&api_key=YOUR_API_KEY"
curl -X GET "https://data.businessquant.com/economic?code=GDP,CPI,UNRATE&mode=normalized&period=5y&api_key=YOUR_API_KEY"
curl -X GET "https://data.businessquant.com/economic/list?category=Inflation&api_key=YOUR_API_KEY"
2. Sample Response
The viewer below shows a single indicator returned in original mode. Note the shape of the payload: metadata is an array of descriptor rows, one per requested code, carried once and never repeated. The data array holds only code, date, and value, which keeps multi decade daily series small enough to transfer quickly. Switch to JSON to inspect the raw structure.
File not found:
templates/api-responses/economic-historic.json
3. Response Field Reference
The response splits descriptors from observations. Every field describing what a series is lives in metadata and appears exactly once. Every field describing what a series did lives in data. This is why a twenty year daily series stays compact.
Metadata Fields (array, one object per requested code)
| Field | Type | Description |
|---|---|---|
| indicator_id | integer | Internal series key. History is joined on this rather than on code, because display codes can change over time. |
| code | string | Canonical indicator code, returned in its stored form. Use this value when matching rows in data. |
| name | string | Full descriptive name of the indicator. |
| category | string | Thematic grouping, for example Inflation, Employment, Housing, or Interest Rates. |
| direction | string | Whether a rising value is economically favourable, used for colour coding and scoring. |
| freq | string | Short release frequency code. |
| freq_long | string | Human readable release frequency, for example Monthly or Quarterly. |
| seasonal_adj | string | Seasonal adjustment status of the series. |
| display_unit | string | Unit the raw value is expressed in, for example percent, index level, or thousands of units. |
| decimals | integer | Precision the publisher reports at. Use it to format values rather than assuming two places. |
Data Fields
| Field | Type | Description |
|---|---|---|
| code | string | Indicator code this observation belongs to. Matches a code in the metadata array. |
| date | string | Observation date in YYYY-MM-DD format. This is the reference period the value describes, not the date it was published. |
| value | number|null | The observation, transformed according to mode. Returns null where the publisher reported no value for that period. |
Transformation Modes
| Mode | What value contains |
|---|---|
| original | The raw reported level, exactly as published, in the unit named by display_unit. This is the default. |
| normalized | Percentage change against the first observation inside your date window, rounded to two decimals. The first point of every series is therefore 0, which is what makes several indicators on different scales directly comparable on one axis. |
| pct_from_high | Percentage distance below the running maximum seen up to that point, rounded to two decimals. Values are zero or negative. This is a drawdown view, useful for spotting how far a series has retreated from its own peak. |
| pct_from_low | Percentage distance above the running minimum seen up to that point, rounded to two decimals. Values are zero or positive. This is a recovery view, useful for measuring the extent of a rebound off a trough. |
4. Finding Valid Indicator Codes
This endpoint needs a code before it can return anything, and codes are not something to guess at or hard-code. The Economic Indicators List API returns the full catalog of covered indicators together with their descriptors, and every code it hands back is immediately valid here. Fetch it once at startup, cache the result, and resolve codes at runtime.
Returns every covered indicator with its code, name, category, release frequency, seasonal adjustment status, display unit, and decimal precision — plus a sorted categories array you can bind straight to a filter control. No cap applies on the number of codes you can query there.
https://data.businessquant.com/economic/list?api_key={api_key}
The descriptor fields returned by that endpoint are identical to the ones in this endpoint's metadata array, so a single parser handles both responses. Passing an unknown code here returns 404 naming the codes that failed, with a pointer back to the catalog.
Economic Data Request Examples
Copy any request below directly into your application.
https://data.businessquant.com/economic?code=UNRATE&period=max&api_key=YOUR_API_KEY
https://data.businessquant.com/economic?code=GDP,CPI,UNRATE,PAYEMS,HOUST&mode=normalized&period=5y&api_key=YOUR_API_KEY
https://data.businessquant.com/economic?code=CPIYOY&from_date=2020-01-01&till_date=2026-06-30&api_key=YOUR_API_KEY
https://data.businessquant.com/economic?code=INDPRO&mode=pct_from_high&period=20y&api_key=YOUR_API_KEY
https://data.businessquant.com/economic?code=PAYEMS&mode=pct_from_low&period=max&api_key=YOUR_API_KEY
Frequently Asked Questions
What economic indicators does the API cover?
Coverage spans the major US macro categories, including growth, inflation, employment, interest rates, housing, consumer activity, and industrial production. Call /economic/list for the authoritative catalog with every code, its category, and its release frequency. That endpoint is the source of truth, since new indicators are added over time.
How many indicators can I request at once?
Up to five codes per call to /economic. Requesting more returns a 400 naming how many were supplied. The cap keeps response sizes predictable, since a single daily series can run to thousands of observations. The catalog endpoint has no such limit.
How do I compare indicators measured in different units?
Use mode=normalized. Each series is rebased independently to its own first observation inside your window and expressed as percentage change, so an index level, a percentage rate, and a count in thousands all plot legibly on one axis. The transformation runs in the database, so there is nothing to compute client side.
Why is metadata an array on this endpoint?
Because a single request can return several series. Rather than repeat the name, category, unit, and frequency on every one of thousands of rows, each descriptor is carried once in the metadata array and the observations in data reference it by code. Join the two on that field.
Do I need the E: prefix on indicator codes?
No. Both the prefixed and unprefixed forms resolve to the same series, and matching is case insensitive. Exact matches always take priority, so a code stored without the prefix is never shadowed by a prefixed one. Responses always return the canonical stored form.
When should I use pct_from_high or pct_from_low?
Use pct_from_high to measure how far an indicator has fallen from its own running peak, which is the standard way to size a contraction in output, payrolls, or housing starts. Use pct_from_low to measure the strength of a recovery off a trough. Both are running calculations, so each point compares against the extreme observed up to that date rather than the extreme of the whole series.
Is the Economic Data API free to use?
Yes, the Economic Data API is free to use. Sign up for an API key to start pulling macro time-series immediately.