How to pull an economic data series

The short way

FRED is the default, and one URL is most of it:

https://api.stlouisfed.org/fred/series/observations?series_id=GDPC1&api_key=YOUR_API_KEY&file_type=json

GDPC1 is real GDP, quarterly, in billions of chained 2017 dollars. CPIAUCSL is seasonally adjusted headline CPI on a 1982-84 = 100 base, UNRATE the unemployment rate, DGS10 the ten-year Treasury constant-maturity yield. The key is free to anyone with an account, the throttle is 120 requests a minute, and one call returns up to 100,000 observations as JSON, XML, CSV or Excel — which is the whole history of most series.

What that URL does not tell you is which version of the series you just received. It is today's, with every revision since baked in, and for a lot of work that is the wrong one. The rest of this page is mostly about that.

What the options are

The aggregator that also keeps the old numbers. FRED republishes 851,100 series from 126 sources — the BLS, the BEA, the Census Bureau, the EIA, the OECD, the BIS, a dozen central banks. It is the fastest way to get a series and the only free API here that hands you past vintages on the same endpoint as current data, through realtime_start, realtime_end, vintage_dates and output_type. It is also an aggregation: the definition, the seasonal adjustment and the errata belong to whoever published them.

The agency that computes the number. BLS Public Data API is where CPI, payrolls, PPI, JOLTS and the Employment Cost Index are actually produced. The reason to come here rather than take the same series second-hand is the footnote array: this is the number with the agency's own caveat attached, including the preliminary flags. Version 1 answers 25 queries a day with no key; a free registered key buys 500 a day, 50 series and 20 years per query, and expires annually.

The euro area's monetary plumbing. ECB Data Portal API is keyless SDMX over 214 dataflows — daily euro reference rates, the fitted AAA yield curve, €STR, bank lending rates. Two parameters do work you would otherwise write yourself: updatedAfter returns only what changed since a timestamp, and includeHistory=true returns previous versions of the matching data alongside the one in production.

European official statistics. Eurostat API is 8,877 datasets over three keyless services, JSON-stat 2.0 on one of them, CORS headers included. Prices, national accounts, labour, trade, government finance. It has no vintages of any kind, and a good share of the catalogue is frozen — 4,066 of those datasets stop at 2022 or earlier and answer queries exactly as readily as the live ones.

Many agencies, one query shape. DBnomics puts one free, keyless API in front of 93 providers and keeps each provider's own codes, so ECB/EXR/D.USD.EUR.SP00.A is the same string in the URL, in the Python client and in the CSV. A series key worked out on the ECB's own site transfers unchanged. It is run by CEPREMAP, a French public research centre, which is the useful thing to know about its lifespan.

The rest of the world, annually. World Bank Open Data is 217 economies with history to 1960, keyless, and the only source on this page whose own datasets carry a plain Creative Commons Attribution 4.0 licence. Everything in it is annual and a year or more behind. OECD Data and IMF Data overlap it with deeper structural detail and a steeper entry cost — both are SDMX, both moved house recently, and the OECD caps you at 60 data downloads an hour per IP, counting browser exports against the same allowance.

Paying for it. Trading Economics has no free key at all: $199 a month is the cheapest plan carrying API access, for 500 requests a month, and the calendar API, live streaming and redistribution sit on a quoted Enterprise plan. EconDB is €24.99 a month for 5,170 macro series plus container-shipping data. What these buy is packaging — house tickers, a calendar, forecasts, one bill — over numbers the agencies publish for nothing. That is a real product for some readers and an odd purchase for anyone who only wanted CPI.

Where this breaks

The series you download today is not the series that existed then. This is the one that quietly ruins a backtest, and it is not an edge case: ALFRED's own framing is that economic data for past observation periods are revised as more accurate estimates become available, and that previous vintages can be superseded and may no longer be available from the source. The US GDP print for one quarter is published three times — the BEA's 2026 schedule lists the advance estimate for the third quarter on 29 October, the second estimate on 25 November and the third on 23 December, all at 8:30 a.m. At the BLS the pattern differs per programme: unadjusted CPI is final when issued, because it is written into escalation agreements, while seasonally adjusted indexes already published are subject to revision for up to five years as the factors are re-estimated. So CPIAUCSL is revisable and its unadjusted twin is not, and nothing in either response says so.

Getting the old number back is a parameter on one API and impossible on most:

• FRED and ALFRED are one database. vintage_dates downloads the data as it existed on those dates; realtime_start and realtime_end bound the real-time period, both defaulting to today; and output_type picks the shape — observations by real-time period, by vintage date, new and revised observations only, or initial release only. That last one is the whole of a naive as-reported study:

https://api.stlouisfed.org/fred/series/observations?series_id=GDPC1&api_key=YOUR_API_KEY&file_type=json&output_type=4

• The ECB returns previous versions with includeHistory=true, on the ordinary data endpoint, with no second product and no account.
• The BLS API has no vintage parameter at all. Neither does Eurostat, which states that its database always contains the latest version of the datasets, meaning there is no versioning or documentation of past versions. The World Bank restates history at each quarterly refresh and publishes the errata afterwards. The IMF keeps the current World Economic Outlook round plus one archived predecessor, and that is the whole of its vintage history.

If your source is in the second group, the snapshot is your job, and it starts the day you notice.

The release calendar is the schedule, and the embargo is why there is no shortcut. Statistical Policy Directive No. 3 governs the US Principal Federal Economic Indicators, and it is worth reading once. Release must be prompt and according to an established, publicly available schedule; the last report of each calendar year must carry the time and date of every report in the next one; agencies keep one or two release times a day and release only at those times. Any prerelease under embargo may not precede the official release time by more than 30 minutes, and only to the extent necessary for an orderly review. Of the 35 indicators OMB designates, 15 currently release at 8:30 a.m. Eastern.

Mechanically, that means two things. Polling an API through the night buys nothing a scheduled pull at the release minute does not, because the number does not exist until then. And every layer above the agency adds its own lag — FRED's unemployment page carried an update stamp of 4 September 2026 at 8:27 a.m. Central, the same morning as the release rather than the same minute; its daily dollar–euro series stood at 4 September when read on the 14th; EconDB's US CPI was four months behind an agency that publishes monthly. Read the last observation date, not the wall clock.

Series are discontinued and re-based, and the API is the last to know. Eurostat retired prc_hicp_manr — the obvious code for monthly HICP annual rates — by retitling it to end in 1997-2025 and moving live data to the ECOICOP ver.2 dataflows, where the dimension is coicop18 rather than coicop, the all-items code is TOTAL rather than CP00, and the index base is 2025 = 100. The old code still returns HTTP 200 with a series that stops in December 2025. The IMF dissolved International Financial Statistics into thematic dataflows and retired the host the old examples call, which now fails at DNS resolution rather than with a status code. The OECD took stats.oecd.org offline on 1 July 2024 and left a 301 to the Data Explorer, so a dead integration looks half-alive. The World Bank leaves Doing Business, last updated in August 2021, answering as readily as its live databases.

Re-basing is the quieter version of the same problem. An index level means nothing without its base period — CPI's is 1982-84 = 100, the new European HICP series' is 2025 = 100 — and a rebasing changes every level in the series while leaving the percentage changes alone. Directive No. 3 requires US agencies to announce a planned change in collection, analysis or estimation as far ahead as possible, and for monthly and quarterly series at least three reports before the first one affected. The notice exists. It simply does not arrive through the endpoint you are calling, so someone has to read the release notes.

Free to call is not free to republish. Every source on this page attaches conditions, and they differ:

• FRED warns in capitals that you must contact the data owner before using third-party series for anything other than personal use, forbids taking all the data and claiming it as a unique product, requires any application using the API to display the notice that it is not endorsed or certified by the Federal Reserve Bank of St. Louis, and bars use of the API in developing or training machine-learning systems including large language models.
• The ECB asks for citation and accuracy, and adds the clause most people miss: where the information goes into a document that is sold, buyers must be told, before they pay and each time they access it, that it can be obtained free of charge from the ECB.
• Eurostat permits commercial reuse with attribution, minus carve-outs — data for countries outside the EU, EFTA and the candidate list is outside the permission, which is exactly the euro area against the United States comparison a dashboard wants.
• The IMF permits publication and distribution with attribution, then bars bulk download by automated technology and language-model training without explicit permission.
• The BLS is public domain: cite it, and state that it cannot vouch for data or analyses derived after the numbers left BLS.gov.
• The World Bank is CC BY 4.0 for its own datasets, with third-party datasets under their own terms — the cleanest answer on this page, and still not a blanket one.

An aggregator does not resolve any of this. DBnomics publishes its aggregated datasets under the Open Database Licence and says in the same terms that data remains subject to the licence of its original source provider. Check the provider, not the middle.

If you outgrow this

When you need point-in-time outside the US, the options thin to the ECB's includeHistory and your own archive. Store every pull with the date you pulled it and the response as it arrived; nobody will reconstruct it for you afterwards, and Eurostat has said plainly that it will not.

When you are pulling from five agencies at once, DBnomics is the shape that saves the most work, because the series key you worked out on the agency's own site is the series key it takes. OpenBB is the other shape of the same idea — one Python interface over FRED, the SEC, the ECB, the IMF and the OECD rather than one converted copy of them.

When the calendar itself is the product, that is a purchase rather than a scrape. The schedules are published by each agency and the API to query them is not: Trading Economics puts its calendar endpoint on a quoted plan, and no free source here exposes one.

When the question is really what is free at all, what financial data is genuinely free covers where the line sits and why it sits there. The APIs on this page and everything beside them are in market data APIs.