data-analyst-mcp 0.3.0 → 0.4.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (292) hide show
  1. package/README.md +286 -262
  2. package/dist/adapters/bjs.d.ts +13 -0
  3. package/dist/adapters/bjs.js +28 -0
  4. package/dist/adapters/bjs.js.map +1 -0
  5. package/dist/adapters/cbp.d.ts +5 -0
  6. package/dist/adapters/cbp.js +64 -0
  7. package/dist/adapters/cbp.js.map +1 -0
  8. package/dist/adapters/cdc-wonder.d.ts +5 -0
  9. package/dist/adapters/cdc-wonder.js +68 -0
  10. package/dist/adapters/cdc-wonder.js.map +1 -0
  11. package/dist/adapters/cpsc.d.ts +4 -0
  12. package/dist/adapters/cpsc.js +125 -0
  13. package/dist/adapters/cpsc.js.map +1 -0
  14. package/dist/adapters/fhwa.d.ts +9 -0
  15. package/dist/adapters/fhwa.js +16 -0
  16. package/dist/adapters/fhwa.js.map +1 -0
  17. package/dist/adapters/foreign-assistance.d.ts +9 -0
  18. package/dist/adapters/foreign-assistance.js +42 -0
  19. package/dist/adapters/foreign-assistance.js.map +1 -0
  20. package/dist/adapters/hud-ahar.d.ts +3 -0
  21. package/dist/adapters/hud-ahar.js +80 -0
  22. package/dist/adapters/hud-ahar.js.map +1 -0
  23. package/dist/adapters/nces.d.ts +10 -0
  24. package/dist/adapters/nces.js +32 -0
  25. package/dist/adapters/nces.js.map +1 -0
  26. package/dist/adapters/nsf.d.ts +11 -0
  27. package/dist/adapters/nsf.js +25 -0
  28. package/dist/adapters/nsf.js.map +1 -0
  29. package/dist/adapters/onrr.d.ts +9 -0
  30. package/dist/adapters/onrr.js +35 -0
  31. package/dist/adapters/onrr.js.map +1 -0
  32. package/dist/adapters/sba.d.ts +10 -0
  33. package/dist/adapters/sba.js +134 -0
  34. package/dist/adapters/sba.js.map +1 -0
  35. package/dist/adapters/treasury-tic.d.ts +30 -0
  36. package/dist/adapters/treasury-tic.js +149 -0
  37. package/dist/adapters/treasury-tic.js.map +1 -0
  38. package/dist/adapters/uscourts.d.ts +8 -0
  39. package/dist/adapters/uscourts.js +8 -0
  40. package/dist/adapters/uscourts.js.map +1 -0
  41. package/dist/analysis/cite.d.ts +9 -1
  42. package/dist/analysis/cite.js +9 -2
  43. package/dist/analysis/cite.js.map +1 -1
  44. package/dist/bin/cli.d.ts +2 -0
  45. package/dist/bin/cli.js +17 -0
  46. package/dist/bin/cli.js.map +1 -1
  47. package/dist/core/generic-rest.js +42 -17
  48. package/dist/core/generic-rest.js.map +1 -1
  49. package/dist/core/guard.d.ts +32 -0
  50. package/dist/core/guard.js +176 -0
  51. package/dist/core/guard.js.map +1 -0
  52. package/dist/core/http.d.ts +10 -0
  53. package/dist/core/http.js +36 -7
  54. package/dist/core/http.js.map +1 -1
  55. package/dist/core/keys.d.ts +13 -3
  56. package/dist/core/keys.js +67 -7
  57. package/dist/core/keys.js.map +1 -1
  58. package/dist/core/package.d.ts +12 -3
  59. package/dist/core/package.js +56 -12
  60. package/dist/core/package.js.map +1 -1
  61. package/dist/core/secret_patterns.d.ts +6 -0
  62. package/dist/core/secret_patterns.js +20 -0
  63. package/dist/core/secret_patterns.js.map +1 -0
  64. package/dist/core/tabular.d.ts +43 -1
  65. package/dist/core/tabular.js +149 -6
  66. package/dist/core/tabular.js.map +1 -1
  67. package/dist/envelope.js +3 -1
  68. package/dist/envelope.js.map +1 -1
  69. package/dist/index.d.ts +29 -22
  70. package/dist/index.js +45 -46
  71. package/dist/index.js.map +1 -1
  72. package/dist/remote/app.js +87 -31
  73. package/dist/remote/app.js.map +1 -1
  74. package/dist/remote/oauth.js +8 -1
  75. package/dist/remote/oauth.js.map +1 -1
  76. package/dist/remote/pages.d.ts +3 -7
  77. package/dist/remote/pages.js +49 -19
  78. package/dist/remote/pages.js.map +1 -1
  79. package/dist/remote/sign.d.ts +7 -1
  80. package/dist/remote/sign.js +33 -7
  81. package/dist/remote/sign.js.map +1 -1
  82. package/dist/remote/store.js +14 -5
  83. package/dist/remote/store.js.map +1 -1
  84. package/dist/report/audit_report.js +29 -7
  85. package/dist/report/audit_report.js.map +1 -1
  86. package/dist/report/build_report.js +34 -4
  87. package/dist/report/build_report.js.map +1 -1
  88. package/dist/report/method_audit.js +10 -1
  89. package/dist/report/method_audit.js.map +1 -1
  90. package/dist/report/scan_secrets.d.ts +4 -1
  91. package/dist/report/scan_secrets.js +38 -18
  92. package/dist/report/scan_secrets.js.map +1 -1
  93. package/dist/server.d.ts +3 -1
  94. package/dist/server.js +46 -13
  95. package/dist/server.js.map +1 -1
  96. package/dist/tools.js +27 -6
  97. package/dist/tools.js.map +1 -1
  98. package/guide/WORKFLOW.md +134 -134
  99. package/guide/assets/disclaimer.txt +1 -1
  100. package/guide/assets/download_data.ps1 +164 -162
  101. package/guide/assets/download_data.sh +8 -2
  102. package/guide/assets/report_template.html +597 -597
  103. package/guide/references/routing.md +198 -171
  104. package/guide/references/style_guide.md +398 -398
  105. package/package.json +56 -56
  106. package/packs/acf/endpoints.json +114 -114
  107. package/packs/acf/policy.json +104 -104
  108. package/packs/actuaries/endpoints.json +82 -82
  109. package/packs/actuaries/policy.json +109 -109
  110. package/packs/bea/assets/download_bea.ps1 +182 -182
  111. package/packs/bea/docs/bea_api.md +461 -461
  112. package/packs/bea/docs/datasets.md +157 -157
  113. package/packs/bea/docs/report_patterns.md +112 -112
  114. package/packs/bea/policy.json +170 -170
  115. package/packs/bea/source.md +152 -152
  116. package/packs/bjs/endpoints.json +150 -0
  117. package/packs/bjs/policy.json +114 -0
  118. package/packs/bjs/source.md +98 -0
  119. package/packs/bls/assets/download_bls.ps1 +152 -152
  120. package/packs/bls/docs/analysis_patterns.md +108 -108
  121. package/packs/bls/docs/bls_api.md +73 -73
  122. package/packs/bls/docs/series_ids.md +149 -149
  123. package/packs/bls/policy.json +238 -238
  124. package/packs/bts/endpoints.json +346 -346
  125. package/packs/bts/policy.json +94 -94
  126. package/packs/cbp/endpoints.json +31 -0
  127. package/packs/cbp/policy.json +85 -0
  128. package/packs/cbp/source.md +57 -0
  129. package/packs/cdc/endpoints.json +197 -197
  130. package/packs/cdc/policy.json +83 -83
  131. package/packs/cdc/source.md +1 -1
  132. package/packs/cdc-wonder/endpoints.json +26 -0
  133. package/packs/cdc-wonder/policy.json +84 -0
  134. package/packs/cdc-wonder/source.md +53 -0
  135. package/packs/census/endpoints.json +99 -99
  136. package/packs/cfpb/endpoints.json +326 -326
  137. package/packs/cfpb/policy.json +119 -119
  138. package/packs/clinical-trials/endpoints.json +166 -166
  139. package/packs/clinical-trials/policy.json +84 -84
  140. package/packs/cms/endpoints.json +69 -69
  141. package/packs/cms/policy.json +96 -96
  142. package/packs/college-scorecard/endpoints.json +252 -252
  143. package/packs/college-scorecard/policy.json +106 -106
  144. package/packs/college-scorecard/source.md +1 -1
  145. package/packs/congress/endpoints.json +1701 -1701
  146. package/packs/congress/policy.json +117 -117
  147. package/packs/cpsc/endpoints.json +91 -0
  148. package/packs/cpsc/policy.json +91 -0
  149. package/packs/cpsc/source.md +76 -0
  150. package/packs/dhs-ohss/endpoints.json +66 -66
  151. package/packs/dhs-ohss/policy.json +107 -107
  152. package/packs/dhs-ohss/source.md +1 -1
  153. package/packs/doj-news/endpoints.json +59 -59
  154. package/packs/doj-news/policy.json +96 -96
  155. package/packs/doj-news/source.md +1 -1
  156. package/packs/dol/endpoints.json +817 -817
  157. package/packs/dol/policy.json +135 -135
  158. package/packs/eia/endpoints.json +717 -717
  159. package/packs/eia/policy.json +112 -112
  160. package/packs/epa/endpoints.json +291 -291
  161. package/packs/epa/policy.json +99 -99
  162. package/packs/epa-aqs/endpoints.json +173 -173
  163. package/packs/epa-aqs/policy.json +96 -96
  164. package/packs/fbi/endpoints.json +1841 -1841
  165. package/packs/fbi/policy.json +118 -118
  166. package/packs/fbi/source.md +3 -3
  167. package/packs/fda/endpoints.json +237 -237
  168. package/packs/fda/policy.json +121 -121
  169. package/packs/fdic/endpoints.json +416 -416
  170. package/packs/fdic/policy.json +83 -83
  171. package/packs/fec/endpoints.json +707 -707
  172. package/packs/fec/policy.json +93 -93
  173. package/packs/fed-board/endpoints.json +89 -89
  174. package/packs/fed-board/policy.json +136 -136
  175. package/packs/federal-register/endpoints.json +143 -143
  176. package/packs/federal-register/policy.json +86 -86
  177. package/packs/fema/endpoints.json +645 -645
  178. package/packs/fema/policy.json +103 -103
  179. package/packs/fhfa/endpoints.json +105 -105
  180. package/packs/fhfa/policy.json +109 -109
  181. package/packs/fhwa/endpoints.json +48 -0
  182. package/packs/fhwa/policy.json +91 -0
  183. package/packs/fhwa/source.md +59 -0
  184. package/packs/foreign-assistance/endpoints.json +166 -0
  185. package/packs/foreign-assistance/policy.json +80 -0
  186. package/packs/foreign-assistance/source.md +76 -0
  187. package/packs/fred/assets/download_fred.ps1 +122 -122
  188. package/packs/fred/docs/analysis_patterns.md +124 -124
  189. package/packs/fred/docs/fred_api.md +94 -94
  190. package/packs/fred/docs/series.md +188 -188
  191. package/packs/fred/policy.json +253 -253
  192. package/packs/fsa/endpoints.json +150 -150
  193. package/packs/fsa/policy.json +99 -99
  194. package/packs/fsa/source.md +1 -1
  195. package/packs/govinfo/endpoints.json +519 -519
  196. package/packs/gsa-calc/endpoints.json +93 -93
  197. package/packs/gsa-calc/policy.json +97 -97
  198. package/packs/hud/endpoints.json +146 -146
  199. package/packs/hud/policy.json +84 -84
  200. package/packs/hud/source.md +1 -1
  201. package/packs/hud-ahar/endpoints.json +92 -0
  202. package/packs/hud-ahar/policy.json +88 -0
  203. package/packs/hud-ahar/source.md +72 -0
  204. package/packs/ipums/docs/report_patterns.md +117 -117
  205. package/packs/irs-soi/endpoints.json +114 -114
  206. package/packs/irs-soi/policy.json +107 -107
  207. package/packs/medicaid/endpoints.json +412 -412
  208. package/packs/medicaid/policy.json +108 -108
  209. package/packs/naep/endpoints.json +217 -217
  210. package/packs/naep/policy.json +100 -100
  211. package/packs/naep/source.md +1 -1
  212. package/packs/nces/endpoints.json +101 -0
  213. package/packs/nces/policy.json +99 -0
  214. package/packs/nces/source.md +75 -0
  215. package/packs/nhtsa/endpoints.json +132 -132
  216. package/packs/nhtsa/policy.json +93 -93
  217. package/packs/nhtsa/source.md +1 -1
  218. package/packs/nih/endpoints.json +452 -452
  219. package/packs/nih/policy.json +86 -86
  220. package/packs/noaa/endpoints.json +431 -431
  221. package/packs/noaa/policy.json +95 -95
  222. package/packs/nrel/endpoints.json +327 -327
  223. package/packs/nrel/policy.json +96 -96
  224. package/packs/nsf/endpoints.json +33 -0
  225. package/packs/nsf/policy.json +83 -0
  226. package/packs/nsf/source.md +59 -0
  227. package/packs/nws/endpoints.json +271 -271
  228. package/packs/nws/policy.json +82 -82
  229. package/packs/nyfed/endpoints.json +80 -80
  230. package/packs/nyfed/policy.json +92 -92
  231. package/packs/omb/endpoints.json +460 -460
  232. package/packs/omb/policy.json +106 -106
  233. package/packs/onrr/endpoints.json +198 -0
  234. package/packs/onrr/policy.json +91 -0
  235. package/packs/onrr/source.md +55 -0
  236. package/packs/open-payments/endpoints.json +297 -297
  237. package/packs/open-payments/policy.json +101 -101
  238. package/packs/opm/assets/download_opm.ps1 +125 -125
  239. package/packs/opm/docs/fields.md +184 -184
  240. package/packs/opm/docs/opm_api.md +71 -71
  241. package/packs/opm/docs/report_patterns.md +83 -83
  242. package/packs/opm/lib/data_dictionary.csv +73 -73
  243. package/packs/pbgc/endpoints.json +483 -483
  244. package/packs/pbgc/policy.json +94 -94
  245. package/packs/philfed/endpoints.json +85 -85
  246. package/packs/philfed/policy.json +94 -94
  247. package/packs/port.json +65 -0
  248. package/packs/regulations/endpoints.json +287 -287
  249. package/packs/regulations/policy.json +86 -86
  250. package/packs/sba/endpoints.json +34 -0
  251. package/packs/sba/policy.json +86 -0
  252. package/packs/sba/source.md +60 -0
  253. package/packs/sec/endpoints.json +236 -236
  254. package/packs/sec/policy.json +86 -86
  255. package/packs/senate-lobbying/endpoints.json +553 -553
  256. package/packs/senate-lobbying/policy.json +99 -99
  257. package/packs/snapqc/endpoints.json +1426 -1426
  258. package/packs/snapqc/policy.json +92 -92
  259. package/packs/treasury/catalog.json +2267 -2267
  260. package/packs/treasury/docs/api_guide.md +245 -245
  261. package/packs/treasury/docs/datasets.md +56 -56
  262. package/packs/treasury/docs/report_patterns.md +126 -126
  263. package/packs/treasury/policy.json +159 -159
  264. package/packs/treasury/source.md +170 -165
  265. package/packs/treasury-tic/endpoints.json +77 -0
  266. package/packs/treasury-tic/policy.json +89 -0
  267. package/packs/treasury-tic/source.md +80 -0
  268. package/packs/treasury-yields/endpoints.json +226 -226
  269. package/packs/treasury-yields/policy.json +86 -86
  270. package/packs/usaspending/endpoints.json +1315 -1315
  271. package/packs/usaspending/policy.json +109 -109
  272. package/packs/uscourts/endpoints.json +22 -0
  273. package/packs/uscourts/policy.json +87 -0
  274. package/packs/uscourts/source.md +56 -0
  275. package/packs/usda-fna/policy.json +133 -133
  276. package/packs/usda-fooddata/endpoints.json +180 -180
  277. package/packs/usda-fooddata/policy.json +94 -94
  278. package/packs/usda-nass/endpoints.json +323 -323
  279. package/packs/usda-nass/policy.json +95 -95
  280. package/packs/usda-outlook/endpoints.json +86 -86
  281. package/packs/usda-outlook/policy.json +109 -109
  282. package/packs/usgs/endpoints.json +313 -313
  283. package/packs/usgs/policy.json +95 -95
  284. package/packs/usitc/endpoints.json +74 -74
  285. package/packs/usitc/policy.json +111 -111
  286. package/packs/uspto/endpoints.json +141 -141
  287. package/packs/uspto/policy.json +95 -95
  288. package/packs/uspto/source.md +1 -1
  289. package/packs/va/endpoints.json +414 -414
  290. package/packs/va/policy.json +101 -101
  291. package/packs/world-bank/endpoints.json +122 -122
  292. package/packs/world-bank/policy.json +101 -101
@@ -1,94 +1,94 @@
1
- # FRED, ALFRED and GeoFRED: what the fetch relies on
2
-
3
- Checked live on 2026-10-20 unless marked "(docs)". The `fetch` tool implements all of this; read this file
4
- when a download fails or a request needs a parameter the spec does not expose.
5
-
6
- ## Two routes
7
- | | FRED API (`api.stlouisfed.org/fred/`) | Keyless graph downloads (`fred.stlouisfed.org/graph/`) |
8
- |---|---|---|
9
- | Key | `api_key=<32 lowercase letters/digits>` query parameter; free at https://fredaccount.stlouisfed.org/apikeys; one key per user (terms) | none |
10
- | Data | `series/observations`, JSON, `"."` = missing | `fredgraph.csv?id=X`, `""` = missing |
11
- | Metadata | `series` (title, units, frequency, SA, last_updated, **notes**), `series/release`, `release/sources` (the source agency for the citation) | `fredgraph.xlsx?id=A,B,...` README sheet: title, units, frequency, SA, "Data Updated". No notes, source or copyright |
12
- | Vintages (ALFRED) | `realtime_start/realtime_end`, `vintage_dates`, `output_type` (1 by real-time period, 2/3 by vintage, 4 initial release), `series/vintagedates` | `alfred.stlouisfed.org/graph/alfredgraph.csv?id=X,X&vintage_date=D1,D2&cosd=..,..&coed=..,..` (one repeated ID per vintage; columns `X_YYYYMMDD`). No first-release or full history |
13
- | Search | `series/search` (`search_text`, `order_by=popularity`, `filter_variable`, `tag_names`) | none: use https://fred.stlouisfed.org/searchresults/?st=... in a browser, then the `request_schema` search `describe <IDs>` |
14
- | Regional | GeoFRED `geofred/series/group?series_id=`, `geofred/regional/data` (`series_group`, `region_type` state/county/msa/bea/frb/necta/censusregion/country, `date`, `season`, `units`, `frequency`) | explicit per-area IDs (CAUR, TXUR ...; CAPCPI ...) through fredgraph.csv |
15
- | Errors | HTTP 400 JSON `{"error_code":400,"error_message":"Bad Request. The value for variable api_key is not registered. ..."}`; 429 above 120 requests a minute; 404 unknown series (docs) | 404 with an **HTML page** for an unknown ID (not CSV); check the content |
16
- | Limits | 120 requests/minute; `limit` 100000 observations per call (paged); 2000 vintage dates per call (docs) | not published: be gentle (fetch paces about 1.8 requests a second); a graph holds **at most 12 series** and silently drops the rest |
17
-
18
- ## Parameters worth knowing (`series/observations`, and the graph equivalents)
19
- - Dates: `observation_start`/`observation_end` (graph: `cosd`/`coed`, one value per ID).
20
- - `units` (graph: `transformation`): `lin` levels, `chg` change, `ch1` change from a year ago, `pch` percent
21
- change, `pc1` percent change from a year ago, `pca` compounded annual rate, `cch`/`cca` continuously
22
- compounded, `log`. The column becomes `X_PC1` etc. on the graph route.
23
- - `frequency` (graph: `fq` = Monthly, Quarterly, Annual ...) with `aggregation_method` `avg`/`sum`/`eop`
24
- (graph: `fam`). Only to a lower frequency. **FRED averages whatever observations exist**: a quarter with a
25
- missing month still gets a value (CPI, October 2025). Prefer native frequency and convert only complete
26
- periods yourself (count the observations in each period).
27
- - Several IDs in one graph CSV: date bounds must be given per ID (`cosd=a,b`); mixed frequencies come back as
28
- a **zip** with `monthly.csv`, `quarterly.csv`. fetch sends one ID per CSV request.
29
-
30
- ## Dates that mean something else
31
- - Fiscal-year dollar series (FYONET, FYFR, FYFSD, FYOINT) are dated at the **end** of the fiscal year
32
- (2025-09-30 = FY2025); fiscal-year percent-of-GDP series (FYFSGDA188S, FYOIGDA188S) at **January 1** of the
33
- fiscal year's number. `compute`'s `fiscal_year` maps both to 2025.
34
- - Quarterly data are dated at the first day of the quarter (2026-04-01 = 2026 Q2); monthly at the first of
35
- the month; weekly at the week's end day (MORTGAGE30US: Thursday); "Quarterly, End of Period" stocks
36
- (FYGFDPUN, GFDEBTN) are still dated at the quarter's first day.
37
- - CBO series (GDPPOT, NGDPPOT, NROU) run about **ten years into the future**: projections, not data.
38
- - USREC is 1 "from the period following the peak through the trough": the first shaded month is the month
39
- after the NBER peak.
40
-
41
- ## Terms of use (https://fred.stlouisfed.org/docs/api/terms_of_use.html, https://fred.stlouisfed.org/legal/)
42
- - Every user uses their own API key. Never share or embed one; the server keeps the key out of every file.
43
- - No wholesale downloading, and no building a cache or archive of FRED content: request only the series and
44
- dates the question needs. The `data/fred/` folder is the working copy for one analysis.
45
- - Products built on the API carry: "This product uses the FRED® API but is not endorsed or certified by the
46
- Federal Reserve Bank of St. Louis." (fetch puts it in the README when the data came from the API.)
47
- - Copyright: each series page shows a tag: **Public Domain: Citation Requested**, **Copyrighted: Citation
48
- Required**, or **Copyrighted: Pre-Approval Required** (S&P, some Moody's, ICE BofA ... series; for example
49
- SP500: reproduction needs the owner's written permission). Every page also shows a generic banner "Data in
50
- this graph are copyrighted": ignore the banner, read the **tag**. With a key fetch reads that tag
51
- from `fred/series/tags` (group `cc`, e.g. "public domain: citation requested"; verified live 2026-10-22)
52
- and fall back to the notes ("Copyright, ..." → `copyrighted`) only when the tags cannot be read; keyless
53
- downloads are `unknown`. `no_copyright_notice` (notes fallback) is not proof of public domain: USREC's
54
- notes carry no "Copyright", yet its tag is Copyrighted: Citation Required (checked 2026-10-20). Both are shareable with a
55
- citation; for a report, read the tag of any series from a private publisher before sharing its data.
56
- - Citation (the series page's "Suggested Citation"): "U.S. Bureau of Economic Analysis, Real Gross Domestic
57
- Product [GDPC1], retrieved from FRED, Federal Reserve Bank of St. Louis; https://fred.stlouisfed.org/series/GDPC1,
58
- October 20, 2026."
59
-
60
- ## Keyed responses (checked live with a key, 2026-10-20)
61
- - **As of a date** (`vintage_dates=D1,D2`): rows by real-time period (`realtime_start`/`realtime_end`); fetch
62
- assigns each row to every requested vintage date inside its period.
63
- - **Full history** (`realtime_start=1776-07-04&realtime_end=9999-12-31`): one row per value and real-time period;
64
- `vintage` = the date the value was published. To rebuild the series as known on a date, keep for each period
65
- the row whose real-time window contains that date (`realtime_start` <= date <= `realtime_end`).
66
- - **First release** (`output_type=4`): needs the same full real-time window, or FRED answers HTTP 400 "No
67
- vintage dates exist for the specified real-time period". Each row's `realtime_start` is its first publication
68
- date (GDPC1 2020 Q2: 17,205.822, published 2020-07-30).
69
- - **GeoFRED** `regional/data`: `{"meta": {"title", "region", "seasonality", "units", "frequency", "data": {date:
70
- [{region, code, value (a number), series_id}]}}}`. The title can name a different month than the date key
71
- (a September title for 2026-08-01 data); trust the date key. `series/group` gives the group, region type,
72
- season, units, frequency and `max_date` for a member series (CAUR → group 1224, 50 states and DC).
73
- - Output types 2 and 3 (by vintage, in columns) are not used by fetch; it still parses their documented
74
- `<ID>_<YYYYMMDD>` columns in case a raw file has them.
75
- - In the manual bundle, a GeoFRED request without `series_group` takes two calls; the download scripts make one
76
- request per file and cannot chain them, so INSTRUCTIONS.md marks it as step 1 of 2: put `series_group` in the
77
- spec's `regional` block to download it in one step.
78
- - `series/vintagedates` of a derived series lists only the releases in which one of its (rounded) values changed:
79
- A191RL1Q225SBEA has 68 vintages since July 30, 2020, GDPC1 has 74. Count or list releases from the levels
80
- series (or the union), never from a growth-rate series alone.
81
-
82
- ## Release calendar and whole releases (checked live 2026-10-20)
83
- - `fred/release/dates?release_id=N&realtime_start=D&realtime_end=9999-12-31&include_release_dates_with_no_data=true`
84
- lists a release's dates, scheduled future dates included (Employment Situation, release 50: 2026-10-02,
85
- 2026-11-06, 2026-12-04); `fred/releases/dates` lists every release between two dates. The one-release form
86
- gives no `release_name`. `request_schema` search `release_dates [ID]` or spec `release_dates`.
87
- - FRED API v2 `fred/v2/release/observations?release_id=N&format=json&limit=L` returns every series of a
88
- release with its observations and FRED's copyright tag (`copyright_id`, e.g. "public domain: citation
89
- requested"), which v1 does not expose. Paging: `has_more` + `next_cursor` ("SERIES_ID,YYYY-MM-DD"); a page
90
- can end inside a series, so the next page continues it (the pack merges them). **The key goes in the header
91
- `Authorization: Bearer <key>`**; `api_key` in the query answers HTTP 401 `{"code":401,"message":"Missing or
92
- invalid credentials."}`. v2 error
93
- bodies arrive gzip-compressed even without `Accept-Encoding`. Release 53 (GDP) holds thousands of series:
94
- cap with `limit`, `max_pages` and a `series` filter.
1
+ # FRED, ALFRED and GeoFRED: what the fetch relies on
2
+
3
+ Checked live on 2026-10-20 unless marked "(docs)". The `fetch` tool implements all of this; read this file
4
+ when a download fails or a request needs a parameter the spec does not expose.
5
+
6
+ ## Two routes
7
+ | | FRED API (`api.stlouisfed.org/fred/`) | Keyless graph downloads (`fred.stlouisfed.org/graph/`) |
8
+ |---|---|---|
9
+ | Key | `api_key=<32 lowercase letters/digits>` query parameter; free at https://fredaccount.stlouisfed.org/apikeys; one key per user (terms) | none |
10
+ | Data | `series/observations`, JSON, `"."` = missing | `fredgraph.csv?id=X`, `""` = missing |
11
+ | Metadata | `series` (title, units, frequency, SA, last_updated, **notes**), `series/release`, `release/sources` (the source agency for the citation) | `fredgraph.xlsx?id=A,B,...` README sheet: title, units, frequency, SA, "Data Updated". No notes, source or copyright |
12
+ | Vintages (ALFRED) | `realtime_start/realtime_end`, `vintage_dates`, `output_type` (1 by real-time period, 2/3 by vintage, 4 initial release), `series/vintagedates` | `alfred.stlouisfed.org/graph/alfredgraph.csv?id=X,X&vintage_date=D1,D2&cosd=..,..&coed=..,..` (one repeated ID per vintage; columns `X_YYYYMMDD`). No first-release or full history |
13
+ | Search | `series/search` (`search_text`, `order_by=popularity`, `filter_variable`, `tag_names`) | none: use https://fred.stlouisfed.org/searchresults/?st=... in a browser, then the `request_schema` search `describe <IDs>` |
14
+ | Regional | GeoFRED `geofred/series/group?series_id=`, `geofred/regional/data` (`series_group`, `region_type` state/county/msa/bea/frb/necta/censusregion/country, `date`, `season`, `units`, `frequency`) | explicit per-area IDs (CAUR, TXUR ...; CAPCPI ...) through fredgraph.csv |
15
+ | Errors | HTTP 400 JSON `{"error_code":400,"error_message":"Bad Request. The value for variable api_key is not registered. ..."}`; 429 above 120 requests a minute; 404 unknown series (docs) | 404 with an **HTML page** for an unknown ID (not CSV); check the content |
16
+ | Limits | 120 requests/minute; `limit` 100000 observations per call (paged); 2000 vintage dates per call (docs) | not published: be gentle (fetch paces about 1.8 requests a second); a graph holds **at most 12 series** and silently drops the rest |
17
+
18
+ ## Parameters worth knowing (`series/observations`, and the graph equivalents)
19
+ - Dates: `observation_start`/`observation_end` (graph: `cosd`/`coed`, one value per ID).
20
+ - `units` (graph: `transformation`): `lin` levels, `chg` change, `ch1` change from a year ago, `pch` percent
21
+ change, `pc1` percent change from a year ago, `pca` compounded annual rate, `cch`/`cca` continuously
22
+ compounded, `log`. The column becomes `X_PC1` etc. on the graph route.
23
+ - `frequency` (graph: `fq` = Monthly, Quarterly, Annual ...) with `aggregation_method` `avg`/`sum`/`eop`
24
+ (graph: `fam`). Only to a lower frequency. **FRED averages whatever observations exist**: a quarter with a
25
+ missing month still gets a value (CPI, October 2025). Prefer native frequency and convert only complete
26
+ periods yourself (count the observations in each period).
27
+ - Several IDs in one graph CSV: date bounds must be given per ID (`cosd=a,b`); mixed frequencies come back as
28
+ a **zip** with `monthly.csv`, `quarterly.csv`. fetch sends one ID per CSV request.
29
+
30
+ ## Dates that mean something else
31
+ - Fiscal-year dollar series (FYONET, FYFR, FYFSD, FYOINT) are dated at the **end** of the fiscal year
32
+ (2025-09-30 = FY2025); fiscal-year percent-of-GDP series (FYFSGDA188S, FYOIGDA188S) at **January 1** of the
33
+ fiscal year's number. `compute`'s `fiscal_year` maps both to 2025.
34
+ - Quarterly data are dated at the first day of the quarter (2026-04-01 = 2026 Q2); monthly at the first of
35
+ the month; weekly at the week's end day (MORTGAGE30US: Thursday); "Quarterly, End of Period" stocks
36
+ (FYGFDPUN, GFDEBTN) are still dated at the quarter's first day.
37
+ - CBO series (GDPPOT, NGDPPOT, NROU) run about **ten years into the future**: projections, not data.
38
+ - USREC is 1 "from the period following the peak through the trough": the first shaded month is the month
39
+ after the NBER peak.
40
+
41
+ ## Terms of use (https://fred.stlouisfed.org/docs/api/terms_of_use.html, https://fred.stlouisfed.org/legal/)
42
+ - Every user uses their own API key. Never share or embed one; the server keeps the key out of every file.
43
+ - No wholesale downloading, and no building a cache or archive of FRED content: request only the series and
44
+ dates the question needs. The `data/fred/` folder is the working copy for one analysis.
45
+ - Products built on the API carry: "This product uses the FRED® API but is not endorsed or certified by the
46
+ Federal Reserve Bank of St. Louis." (fetch puts it in the README when the data came from the API.)
47
+ - Copyright: each series page shows a tag: **Public Domain: Citation Requested**, **Copyrighted: Citation
48
+ Required**, or **Copyrighted: Pre-Approval Required** (S&P, some Moody's, ICE BofA ... series; for example
49
+ SP500: reproduction needs the owner's written permission). Every page also shows a generic banner "Data in
50
+ this graph are copyrighted": ignore the banner, read the **tag**. With a key fetch reads that tag
51
+ from `fred/series/tags` (group `cc`, e.g. "public domain: citation requested"; verified live 2026-10-22)
52
+ and fall back to the notes ("Copyright, ..." → `copyrighted`) only when the tags cannot be read; keyless
53
+ downloads are `unknown`. `no_copyright_notice` (notes fallback) is not proof of public domain: USREC's
54
+ notes carry no "Copyright", yet its tag is Copyrighted: Citation Required (checked 2026-10-20). Both are shareable with a
55
+ citation; for a report, read the tag of any series from a private publisher before sharing its data.
56
+ - Citation (the series page's "Suggested Citation"): "U.S. Bureau of Economic Analysis, Real Gross Domestic
57
+ Product [GDPC1], retrieved from FRED, Federal Reserve Bank of St. Louis; https://fred.stlouisfed.org/series/GDPC1,
58
+ October 20, 2026."
59
+
60
+ ## Keyed responses (checked live with a key, 2026-10-20)
61
+ - **As of a date** (`vintage_dates=D1,D2`): rows by real-time period (`realtime_start`/`realtime_end`); fetch
62
+ assigns each row to every requested vintage date inside its period.
63
+ - **Full history** (`realtime_start=1776-07-04&realtime_end=9999-12-31`): one row per value and real-time period;
64
+ `vintage` = the date the value was published. To rebuild the series as known on a date, keep for each period
65
+ the row whose real-time window contains that date (`realtime_start` <= date <= `realtime_end`).
66
+ - **First release** (`output_type=4`): needs the same full real-time window, or FRED answers HTTP 400 "No
67
+ vintage dates exist for the specified real-time period". Each row's `realtime_start` is its first publication
68
+ date (GDPC1 2020 Q2: 17,205.822, published 2020-07-30).
69
+ - **GeoFRED** `regional/data`: `{"meta": {"title", "region", "seasonality", "units", "frequency", "data": {date:
70
+ [{region, code, value (a number), series_id}]}}}`. The title can name a different month than the date key
71
+ (a September title for 2026-08-01 data); trust the date key. `series/group` gives the group, region type,
72
+ season, units, frequency and `max_date` for a member series (CAUR → group 1224, 50 states and DC).
73
+ - Output types 2 and 3 (by vintage, in columns) are not used by fetch; it still parses their documented
74
+ `<ID>_<YYYYMMDD>` columns in case a raw file has them.
75
+ - In the manual bundle, a GeoFRED request without `series_group` takes two calls; the download scripts make one
76
+ request per file and cannot chain them, so INSTRUCTIONS.md marks it as step 1 of 2: put `series_group` in the
77
+ spec's `regional` block to download it in one step.
78
+ - `series/vintagedates` of a derived series lists only the releases in which one of its (rounded) values changed:
79
+ A191RL1Q225SBEA has 68 vintages since July 30, 2020, GDPC1 has 74. Count or list releases from the levels
80
+ series (or the union), never from a growth-rate series alone.
81
+
82
+ ## Release calendar and whole releases (checked live 2026-10-20)
83
+ - `fred/release/dates?release_id=N&realtime_start=D&realtime_end=9999-12-31&include_release_dates_with_no_data=true`
84
+ lists a release's dates, scheduled future dates included (Employment Situation, release 50: 2026-10-02,
85
+ 2026-11-06, 2026-12-04); `fred/releases/dates` lists every release between two dates. The one-release form
86
+ gives no `release_name`. `request_schema` search `release_dates [ID]` or spec `release_dates`.
87
+ - FRED API v2 `fred/v2/release/observations?release_id=N&format=json&limit=L` returns every series of a
88
+ release with its observations and FRED's copyright tag (`copyright_id`, e.g. "public domain: citation
89
+ requested"), which v1 does not expose. Paging: `has_more` + `next_cursor` ("SERIES_ID,YYYY-MM-DD"); a page
90
+ can end inside a series, so the next page continues it (the pack merges them). **The key goes in the header
91
+ `Authorization: Bearer <key>`**; `api_key` in the query answers HTTP 401 `{"code":401,"message":"Missing or
92
+ invalid credentials."}`. v2 error
93
+ bodies arrive gzip-compressed even without `Accept-Encoding`. Release 53 (GDP) holds thousands of series:
94
+ cap with `limit`, `max_pages` and a `series` filter.
@@ -1,188 +1,188 @@
1
- # FRED series for budget and economic analysis
2
-
3
- Every ID below was checked to exist on 2026-10-20 (titles, units, frequency and adjustment as FRED shows
4
- them). FRED edits titles and adds series; confirm with the `request_schema` search `describe <IDs>` before downloading, and
5
- read the title back against the concept. Copyright tags were read on the series page only where marked ✔;
6
- read the page for the others before sharing data.
7
-
8
- Contents: 1. Output and potential · 2. Prices · 3. Labor · 4. Interest rates · 5. The federal budget ·
9
- 6. Income and other · 7. Recessions · 8. States and areas · 9. Finding a series you do not know
10
-
11
- ## 1. Output and potential output
12
- | ID | What | Units, frequency | Notes |
13
- |---|---|---|---|
14
- | `GDP` | Gross domestic product | Billions of dollars, quarterly, SAAR | Nominal; the denominator for shares of GDP (average the 4 quarters of a fiscal year) |
15
- | `GDPA` | GDP, annual | Billions of dollars, annual | Calendar year; the denominator of FRED's FY*GDA188S ratios |
16
- | `FYGDP` | GDP, fiscal year (OMB) | Billions of dollars, annual, fiscal year (dated Sep 30) | OMB's figure from its latest budget; lags BEA revisions. The mean of the four quarters of `GDP` is the current-vintage alternative |
17
- | `GDPC1` | Real GDP | Billions of chained 2017 dollars, quarterly, SAAR | BEA; Public Domain ✔ |
18
- | `A191RL1Q225SBEA` | Real GDP, percent change from preceding period | Percent, quarterly, SAAR | BEA's published growth rate: the benchmark for an annualized growth rate computed from `GDPC1` |
19
- | `A939RX0Q048SBEA` | Real GDP per capita | Chained 2017 dollars, quarterly, SAAR | |
20
- | `GDPPOT` | Real potential GDP (CBO) | Billions of chained 2017 dollars, quarterly, NSA | CBO; Public Domain ✔; **projected ~10 years ahead**; last updated with CBO's latest outlook, so it may rest on an older GDP vintage than GDPC1 |
21
- | `NGDPPOT` | Nominal potential GDP (CBO) | Billions of dollars, quarterly | Projections as above |
22
- | `NROU` | Noncyclical rate of unemployment (CBO) | Percent, quarterly | Projections as above |
23
- | `GDPDEF` | GDP implicit price deflator | Index 2017=100, quarterly, SA | |
24
-
25
- Output gap = `GDPC1 / GDPPOT - 1` (both chained 2017 dollars), on dates both have (join on date; stop at the last date both series hold).
26
-
27
- ## 2. Prices
28
- | ID | What | Units, frequency | Notes |
29
- |---|---|---|---|
30
- | `PCEPI` | PCE price index | Index 2017=100, monthly, SA | The measure in the Federal Reserve's 2 percent objective; CBO projects it alongside the CPI-U |
31
- | `PCEPILFE` | Core PCE price index | Index 2017=100, monthly, SA | |
32
- | `CPIAUCSL` | CPI-U, all items | Index 1982-84=100, monthly, SA | Monthly changes |
33
- | `CPIAUCNS` | CPI-U, all items | Index 1982-84=100, monthly, NSA | 12-month changes as BLS reports them; annual averages |
34
- | `CPILFENS` | Core CPI-U, not seasonally adjusted (12-month changes) | Index 1982-84=100, monthly, NSA | |
35
- | `CPILFESL` | Core CPI-U | Index 1982-84=100, monthly, SA | |
36
- | `CWUR0000SA0` | CPI-W, all items | Index 1982-84=100, monthly, NSA | Social Security COLA: average of July-September over the same quarter a year earlier |
37
- | `SUUR0000SA0` | Chained CPI-U (C-CPI-U) | Index Dec 1999=100, monthly, NSA | Tax-bracket indexing; preliminary for 10-12 months |
38
- | `T10YIE` | 10-year breakeven inflation | Percent, daily | Market-based expectation (10-year nominal minus 10-year TIPS yield) |
39
- | `T5YIE` | 5-year breakeven inflation | Percent, daily | 5-year nominal minus 5-year TIPS yield; monthly averages `T5YIEM` |
40
- | `T5YIFR` | 5-year, 5-year forward inflation expectation | Percent, daily | (((1+b10/100)^10/(1+b5/100)^5)^(1/5)-1)*100 from the 10- and 5-year breakevens; monthly `T5YIFRM` |
41
- | `UMCSENT` | University of Michigan consumer sentiment | Index 1966:Q1=100, monthly, NSA | **Posted on FRED one month late** at UMich's request: the latest final and preliminary months are on sca.isr.umich.edu (save them in published/). UMich moved from phone to web interviews in 2024, which shifts levels |
42
-
43
- ## 3. Labor
44
- | ID | What | Units, frequency |
45
- |---|---|---|
46
- | `UNRATE` | Unemployment rate | Percent, monthly, SA |
47
- | `PAYEMS` | All employees, total nonfarm | Thousands, monthly, SA |
48
- | `CIVPART` | Labor force participation rate | Percent, monthly, SA |
49
- | `CNP16OV` | Civilian noninstitutional population 16+ | Thousands, monthly, NSA |
50
- | `CES0500000003` | Average hourly earnings, total private | Dollars per hour, monthly, SA |
51
- | `ECIWAG` | ECI, wages and salaries, private industry | Index Dec 2005=100, quarterly, SA |
52
-
53
- For more detail on BLS series (demographic groups, industries, significance), the bls pack is the
54
- better tool; FRED mirrors the same data.
55
-
56
- ## 4. Interest rates
57
- | ID | What | Units, frequency |
58
- |---|---|---|
59
- | `DFEDTARU` / `DFEDTARL` | Federal funds target range, upper / lower limit (FOMC) | Percent, daily (steps on decision dates). "Cut since the peak": when the path reverses, report the net change and the gross cuts separately (2024-2026: 1.75 points of cuts, 1.50 net after a 2026 raise); the Board's Open Market Operations table is the benchmark |
60
- | `FEDFUNDS` | Effective federal funds rate | Percent, monthly average |
61
- | `DFF` | Effective federal funds rate | Percent, daily (7-day) |
62
- | `DGS10` | 10-year Treasury constant-maturity yield | Percent, daily (business days; gaps on holidays) |
63
- | `GS10` | 10-year Treasury yield | Percent, monthly average |
64
- | `TB3MS` | 3-month Treasury bill, secondary market | Percent, monthly (discount basis) |
65
- | `MORTGAGE30US` | 30-year fixed mortgage rate (Freddie Mac) | Percent, weekly ending Thursday |
66
- | `T10Y2Y` / `T10Y2YM` | 10-year minus 2-year Treasury spread (curve inversion when negative) | Percentage points, daily / monthly average |
67
- | `T10Y3M` | 10-year minus 3-month Treasury spread | Percentage points, daily |
68
-
69
- Use the monthly averages (GS10, TB3MS) for annual or fiscal-year averages; CBO's interest-rate projections
70
- are calendar- or fiscal-year averages of these rates.
71
-
72
- ## 5. The federal budget
73
- | ID | What | Units, frequency | Notes |
74
- |---|---|---|---|
75
- | `FYFR` | Federal receipts (revenues) | Millions of dollars, annual, **fiscal year** | OMB/Treasury; dated Sep 30 |
76
- | `FYONET` | Federal net outlays | Millions of dollars, annual, fiscal year | |
77
- | `FYFSD` | Federal surplus or deficit (negative = deficit) | Millions of dollars, annual, fiscal year | |
78
- | `FYOINT` | Federal outlays: interest | Millions of dollars, annual, fiscal year | OMB, Public Domain ✔. OMB's net interest (budget function 900, matches OMB Historical Table 3.1): $970.1 billion in FY2025. CBO's Monthly Budget Review reports "net interest on the public debt" above $1 trillion for FY2025, a different budget category; say which one the text means and benchmark it against its own source |
79
- | `FYFSGDA188S` | Surplus or deficit as percent of GDP | Percent of GDP, annual (fiscal year, dated Jan 1) | |
80
- | `FYOIGDA188S` | Interest outlays as percent of GDP | Percent of GDP, annual (fiscal year, dated Jan 1) | Benchmark only: divides by calendar-year GDP (GDPA), not fiscal-year GDP |
81
- | `FYGFDPUN` | Federal debt held by the public | Millions of dollars, quarterly, end of period | |
82
- | `FYGFGDQ188S` | Debt held by the public as percent of GDP | Percent of GDP, quarterly, SA | |
83
- | `GFDEBTN` | Total public debt | Millions of dollars, quarterly, end of period | Includes intragovernmental debt: not "debt held by the public" |
84
- | `GFDEGDQ188S` | Total public debt as percent of GDP | Percent of GDP, quarterly, SA | |
85
- | `A091RC1Q027SBEA` | Federal interest payments (NIPA) | Billions of dollars, quarterly, SAAR | National-accounts basis, not budget basis |
86
- | `W006RC1Q027SBEA` | Federal current tax receipts (NIPA) | Billions of dollars, quarterly, SAAR | NIPA basis |
87
- | `FGEXPND` | Federal current expenditures (NIPA) | Billions of dollars, quarterly, SAAR | NIPA basis |
88
-
89
- Budget-basis (OMB/Treasury, fiscal year) and NIPA-basis (BEA, calendar quarters) measures differ in timing and
90
- coverage; never mix them in one ratio without saying so. For CBO's own baseline projections and historical
91
- budget data, use CBO's data files (cbo.gov), not FRED.
92
-
93
- ## 6. Income and other
94
- | ID | What | Units, frequency |
95
- |---|---|---|
96
- | `PCE` | Personal consumption expenditures | Billions of dollars, monthly, SAAR |
97
- | `DSPIC96` | Real disposable personal income | Billions of chained 2017 dollars, monthly, SAAR |
98
- | `PSAVERT` / `A072RC1Q156SBEA` | Personal saving rate (NIPA Table 2.6 / 2.1 line 35) | Percent of disposable income, monthly / quarterly |
99
- | `MEHOINUSA672N` | Real median household income (Census) | Dollars of the latest year (C-CPI-U), annual |
100
- | `SP500` | S&P 500 index | Index, daily; **Copyrighted: Pre-Approval Required** ✔ (only 10 years on FRED) |
101
-
102
- **International trade** (the Census/BEA monthly release, FT-900, mirrored keyless; BEA's ITA needs a key)
103
- | ID | What | Units, frequency |
104
- |---|---|---|
105
- | `BOPGSTB` / `BOPGTB` / `BOPSTB` | Trade balance: goods and services / goods / services, balance of payments basis | Millions of dollars, monthly, SA |
106
- | `BOPTEXP` / `BOPTIMP` | Exports / imports of goods and services, BOP basis | Millions of dollars, monthly, SA |
107
- | `EXPCH` / `IMPCH` | Goods exports to / imports from China, Census basis (other partners: EXP / IMP + country code) | Millions of dollars, monthly, NSA |
108
-
109
- Annual totals are sums of the months; the June annual revision replaces the first-published year. Partner
110
- balances are on the Census basis, as the release gives them.
111
-
112
- ## 4b. Money stock (Federal Reserve H.6, monthly)
113
- `M2SL` M2 (billions of dollars, SA), `M1SL` M1, `M2NS` M2 not adjusted, `WM2NS` weekly M2. The H.6 has not
114
- published growth rates since February 2021: 12-month growth is computed from levels (`pc1`), and the H.6
115
- data file is the level benchmark.
116
-
117
- ## 5a. Industrial production and capacity utilization (Federal Reserve G.17, monthly)
118
- `INDPRO` industrial production, total (index 2017=100), `IPMAN` manufacturing; `TCU` capacity
119
- utilization, total (percent), `MCUMFN` manufacturing (metadata checked on 2026-10-21). The
120
- latest months are preliminary and revised for several months. G.17 states the gap to the long-run
121
- average as the difference of its one-decimal rates (76.9 - 79.4 = 2.5 points below): compute it the
122
- same way to match, and show the unrounded gap as a sensitivity.
123
-
124
- ## 5c. Housing starts and permits (Census New Residential Construction, monthly)
125
- `HOUST` total starts, `HOUST1F` single-family, `PERMIT` permits (thousands of units, SAAR; metadata checked
126
- on 2026-10-21); `HOUSTNSA` not adjusted. The latest month is preliminary and revised twice.
127
- An annual total from FRED sums rounded months: Census's annual sheet sums unrounded estimates (0.1 apart).
128
-
129
- ## 5b. Unemployment insurance claims (DOL, weekly)
130
- `ICSA` initial claims (SA), `IC4WSA` 4-week moving average (SA), `ICNSA` (NSA), `CCSA` continued claims.
131
- Weeks end on Saturday; the latest week is an advance figure (preliminary). The keyless route when the dol
132
- pack has no key. A calendar-year average needs all the weeks of the year (count them; never average a
133
- partial year).
134
-
135
- ## 6a. Household debt service (Federal Reserve DSR release)
136
- Quarterly, percent of disposable personal income: `TDSP` total, `MDSP` mortgage, `CDSP` consumer debt
137
- service. The Fed rebuilt the series on credit-bureau data in 2024: its levels are about 2.5 points above the
138
- archived lender-based series (2007 Q4 15.8 against 13.3), so never mix the two; the latest quarter is
139
- preliminary. Benchmark: federalreserve.gov/releases/dsr.
140
-
141
- ## 6b. Federal Reserve balance sheet (H.4.1)
142
- Weekly, millions of dollars (metadata checked on 2026-10-21). Wednesday levels: `WALCL` total
143
- assets, `TREAST` Treasury securities held outright, `WSHOMCB` mortgage-backed securities, `WSHOSHO` all
144
- securities held outright, `WLRRAL` reverse repurchase agreements (liability). Week averages (not Wednesday
145
- levels; do not mix with the above): `WRESBAL` reserve balances, `WTREGEN` Treasury General Account.
146
- `RRPONTSYD` overnight reverse repos is daily and in billions. Changes between two weeks are differences of
147
- published levels, not published figures: say so in benchmark.csv. Other assets (premiums, loans, the
148
- rest) are total minus the securities.
149
-
150
- ## 6d. House prices and the international investment position
151
- | ID | What | Units, frequency | Notes |
152
- |---|---|---|---|
153
- | `CSUSHPINSA`, `CSUSHPISA` | S&P CoreLogic Case-Shiller U.S. National home price index, NSA / SA | Index Jan 2000=100, monthly, two months' lag | `copyright` preapproval_required: say the values may not be republished; S&P's release leads with NSA 12-month changes |
154
- | `USSTHPI` | FHFA all-transactions house price index, U.S. | Index 1980:Q1=100, quarterly | Public domain |
155
- | `IIPUSNETIQ`, `IIPUSNETIA` | U.S. net international investment position (BEA), quarterly / annual | Millions of dollars | The keyless route to BEA's IIP (the BEA pack needs a key for IIP); preliminary for the latest quarter |
156
-
157
- ## 6c. Exchange rates (Federal Reserve H.10)
158
- | ID | What | Units, frequency | Notes |
159
- |---|---|---|---|
160
- | `DTWEXBGS` | Nominal broad dollar index (trade-weighted, 26 currencies) | Index Jan 2006=100, daily | The Fed's headline dollar index; checked against H.10 [2026-10-22] |
161
- | `TWEXBGSMTH` | Nominal broad dollar index, monthly average | Index Jan 2006=100, monthly | A year-to-date change can differ in sign between daily end points and monthly averages: say which |
162
- | `RTWEXBGS` | Real broad dollar index | Index Jan 2006=100, monthly | Adjusted for relative consumer prices |
163
- | `DEXUSEU`, `DEXJPUS`, `DEXCHUS`, `DEXCAUS`, `DEXMXUS` | Bilateral rates: dollars per euro; yen, yuan, Canadian dollars, pesos per dollar | daily | Mind the quote direction (US per foreign for the euro) |
164
-
165
- ## 7. Recessions
166
- `USREC` (monthly; FRBSL from NBER dates; **Copyrighted: Citation Required** ✔), `USRECQ` (quarterly), `USRECD`
167
- (daily). 1 from the month after the NBER peak through the trough. `"recessions": true` in the spec adds USREC;
168
- for chart shading, turn its runs of 1 into start and end dates.
169
- Sahm rule: `SAHMREALTIME` (real-time, as first published; empty where a month's unemployment rate was not
170
- collected, Oct 2025) and `SAHMCURRENT` (from current UNRATE vintages): the 3-month average of the unemployment
171
- rate minus its low of the prior 12 months; 0.50 or more signals a recession start.
172
-
173
- ## 8. States and areas
174
- - Unemployment rate: `<ST>UR` (CAUR, TXUR ...), monthly, SA (BLS LAUS).
175
- - Per capita personal income: `<ST>PCPI` (CAPCPI ...), annual (BEA).
176
- - A full cross-section in one call needs a key: spec `"regional": [{"series_id": "CAUR", "region_type": "state",
177
- "date": "2026-08-01"}]` (GeoFRED finds the group from any member series). Without a key, list the 50 state IDs
178
- plus DC explicitly; check each with the `request_schema` search `describe <IDs>` (a 404 means the pattern does
179
- not hold for that series).
180
-
181
- ## 9. Finding a series you do not know
182
- 1. With a key: `request_schema` for fred with the search "federal outlays interest" (sorted by
183
- popularity; prefer the most popular series from the official source).
184
- 2. Without a key: search https://fred.stlouisfed.org/searchresults/?st=<words> in the browser (or WebSearch
185
- "site:fred.stlouisfed.org <words>").
186
- 3. Confirm with the `request_schema` search `describe <IDs>`: title, units, frequency, seasonal adjustment, last updated. Prefer the series
187
- published by the original agency (BEA, BLS, OMB, Treasury, CBO, the Board of Governors) over derived copies,
188
- and an SA series for short-run changes, NSA for 12-month changes and annual averages.
1
+ # FRED series for budget and economic analysis
2
+
3
+ Every ID below was checked to exist on 2026-10-20 (titles, units, frequency and adjustment as FRED shows
4
+ them). FRED edits titles and adds series; confirm with the `request_schema` search `describe <IDs>` before downloading, and
5
+ read the title back against the concept. Copyright tags were read on the series page only where marked ✔;
6
+ read the page for the others before sharing data.
7
+
8
+ Contents: 1. Output and potential · 2. Prices · 3. Labor · 4. Interest rates · 5. The federal budget ·
9
+ 6. Income and other · 7. Recessions · 8. States and areas · 9. Finding a series you do not know
10
+
11
+ ## 1. Output and potential output
12
+ | ID | What | Units, frequency | Notes |
13
+ |---|---|---|---|
14
+ | `GDP` | Gross domestic product | Billions of dollars, quarterly, SAAR | Nominal; the denominator for shares of GDP (average the 4 quarters of a fiscal year) |
15
+ | `GDPA` | GDP, annual | Billions of dollars, annual | Calendar year; the denominator of FRED's FY*GDA188S ratios |
16
+ | `FYGDP` | GDP, fiscal year (OMB) | Billions of dollars, annual, fiscal year (dated Sep 30) | OMB's figure from its latest budget; lags BEA revisions. The mean of the four quarters of `GDP` is the current-vintage alternative |
17
+ | `GDPC1` | Real GDP | Billions of chained 2017 dollars, quarterly, SAAR | BEA; Public Domain ✔ |
18
+ | `A191RL1Q225SBEA` | Real GDP, percent change from preceding period | Percent, quarterly, SAAR | BEA's published growth rate: the benchmark for an annualized growth rate computed from `GDPC1` |
19
+ | `A939RX0Q048SBEA` | Real GDP per capita | Chained 2017 dollars, quarterly, SAAR | |
20
+ | `GDPPOT` | Real potential GDP (CBO) | Billions of chained 2017 dollars, quarterly, NSA | CBO; Public Domain ✔; **projected ~10 years ahead**; last updated with CBO's latest outlook, so it may rest on an older GDP vintage than GDPC1 |
21
+ | `NGDPPOT` | Nominal potential GDP (CBO) | Billions of dollars, quarterly | Projections as above |
22
+ | `NROU` | Noncyclical rate of unemployment (CBO) | Percent, quarterly | Projections as above |
23
+ | `GDPDEF` | GDP implicit price deflator | Index 2017=100, quarterly, SA | |
24
+
25
+ Output gap = `GDPC1 / GDPPOT - 1` (both chained 2017 dollars), on dates both have (join on date; stop at the last date both series hold).
26
+
27
+ ## 2. Prices
28
+ | ID | What | Units, frequency | Notes |
29
+ |---|---|---|---|
30
+ | `PCEPI` | PCE price index | Index 2017=100, monthly, SA | The measure in the Federal Reserve's 2 percent objective; CBO projects it alongside the CPI-U |
31
+ | `PCEPILFE` | Core PCE price index | Index 2017=100, monthly, SA | |
32
+ | `CPIAUCSL` | CPI-U, all items | Index 1982-84=100, monthly, SA | Monthly changes |
33
+ | `CPIAUCNS` | CPI-U, all items | Index 1982-84=100, monthly, NSA | 12-month changes as BLS reports them; annual averages |
34
+ | `CPILFENS` | Core CPI-U, not seasonally adjusted (12-month changes) | Index 1982-84=100, monthly, NSA | |
35
+ | `CPILFESL` | Core CPI-U | Index 1982-84=100, monthly, SA | |
36
+ | `CWUR0000SA0` | CPI-W, all items | Index 1982-84=100, monthly, NSA | Social Security COLA: average of July-September over the same quarter a year earlier |
37
+ | `SUUR0000SA0` | Chained CPI-U (C-CPI-U) | Index Dec 1999=100, monthly, NSA | Tax-bracket indexing; preliminary for 10-12 months |
38
+ | `T10YIE` | 10-year breakeven inflation | Percent, daily | Market-based expectation (10-year nominal minus 10-year TIPS yield) |
39
+ | `T5YIE` | 5-year breakeven inflation | Percent, daily | 5-year nominal minus 5-year TIPS yield; monthly averages `T5YIEM` |
40
+ | `T5YIFR` | 5-year, 5-year forward inflation expectation | Percent, daily | (((1+b10/100)^10/(1+b5/100)^5)^(1/5)-1)*100 from the 10- and 5-year breakevens; monthly `T5YIFRM` |
41
+ | `UMCSENT` | University of Michigan consumer sentiment | Index 1966:Q1=100, monthly, NSA | **Posted on FRED one month late** at UMich's request: the latest final and preliminary months are on sca.isr.umich.edu (save them in published/). UMich moved from phone to web interviews in 2024, which shifts levels |
42
+
43
+ ## 3. Labor
44
+ | ID | What | Units, frequency |
45
+ |---|---|---|
46
+ | `UNRATE` | Unemployment rate | Percent, monthly, SA |
47
+ | `PAYEMS` | All employees, total nonfarm | Thousands, monthly, SA |
48
+ | `CIVPART` | Labor force participation rate | Percent, monthly, SA |
49
+ | `CNP16OV` | Civilian noninstitutional population 16+ | Thousands, monthly, NSA |
50
+ | `CES0500000003` | Average hourly earnings, total private | Dollars per hour, monthly, SA |
51
+ | `ECIWAG` | ECI, wages and salaries, private industry | Index Dec 2005=100, quarterly, SA |
52
+
53
+ For more detail on BLS series (demographic groups, industries, significance), the bls pack is the
54
+ better tool; FRED mirrors the same data.
55
+
56
+ ## 4. Interest rates
57
+ | ID | What | Units, frequency |
58
+ |---|---|---|
59
+ | `DFEDTARU` / `DFEDTARL` | Federal funds target range, upper / lower limit (FOMC) | Percent, daily (steps on decision dates). "Cut since the peak": when the path reverses, report the net change and the gross cuts separately (2024-2026: 1.75 points of cuts, 1.50 net after a 2026 raise); the Board's Open Market Operations table is the benchmark |
60
+ | `FEDFUNDS` | Effective federal funds rate | Percent, monthly average |
61
+ | `DFF` | Effective federal funds rate | Percent, daily (7-day) |
62
+ | `DGS10` | 10-year Treasury constant-maturity yield | Percent, daily (business days; gaps on holidays) |
63
+ | `GS10` | 10-year Treasury yield | Percent, monthly average |
64
+ | `TB3MS` | 3-month Treasury bill, secondary market | Percent, monthly (discount basis) |
65
+ | `MORTGAGE30US` | 30-year fixed mortgage rate (Freddie Mac) | Percent, weekly ending Thursday |
66
+ | `T10Y2Y` / `T10Y2YM` | 10-year minus 2-year Treasury spread (curve inversion when negative) | Percentage points, daily / monthly average |
67
+ | `T10Y3M` | 10-year minus 3-month Treasury spread | Percentage points, daily |
68
+
69
+ Use the monthly averages (GS10, TB3MS) for annual or fiscal-year averages; CBO's interest-rate projections
70
+ are calendar- or fiscal-year averages of these rates.
71
+
72
+ ## 5. The federal budget
73
+ | ID | What | Units, frequency | Notes |
74
+ |---|---|---|---|
75
+ | `FYFR` | Federal receipts (revenues) | Millions of dollars, annual, **fiscal year** | OMB/Treasury; dated Sep 30 |
76
+ | `FYONET` | Federal net outlays | Millions of dollars, annual, fiscal year | |
77
+ | `FYFSD` | Federal surplus or deficit (negative = deficit) | Millions of dollars, annual, fiscal year | |
78
+ | `FYOINT` | Federal outlays: interest | Millions of dollars, annual, fiscal year | OMB, Public Domain ✔. OMB's net interest (budget function 900, matches OMB Historical Table 3.1): $970.1 billion in FY2025. CBO's Monthly Budget Review reports "net interest on the public debt" above $1 trillion for FY2025, a different budget category; say which one the text means and benchmark it against its own source |
79
+ | `FYFSGDA188S` | Surplus or deficit as percent of GDP | Percent of GDP, annual (fiscal year, dated Jan 1) | |
80
+ | `FYOIGDA188S` | Interest outlays as percent of GDP | Percent of GDP, annual (fiscal year, dated Jan 1) | Benchmark only: divides by calendar-year GDP (GDPA), not fiscal-year GDP |
81
+ | `FYGFDPUN` | Federal debt held by the public | Millions of dollars, quarterly, end of period | |
82
+ | `FYGFGDQ188S` | Debt held by the public as percent of GDP | Percent of GDP, quarterly, SA | |
83
+ | `GFDEBTN` | Total public debt | Millions of dollars, quarterly, end of period | Includes intragovernmental debt: not "debt held by the public" |
84
+ | `GFDEGDQ188S` | Total public debt as percent of GDP | Percent of GDP, quarterly, SA | |
85
+ | `A091RC1Q027SBEA` | Federal interest payments (NIPA) | Billions of dollars, quarterly, SAAR | National-accounts basis, not budget basis |
86
+ | `W006RC1Q027SBEA` | Federal current tax receipts (NIPA) | Billions of dollars, quarterly, SAAR | NIPA basis |
87
+ | `FGEXPND` | Federal current expenditures (NIPA) | Billions of dollars, quarterly, SAAR | NIPA basis |
88
+
89
+ Budget-basis (OMB/Treasury, fiscal year) and NIPA-basis (BEA, calendar quarters) measures differ in timing and
90
+ coverage; never mix them in one ratio without saying so. For CBO's own baseline projections and historical
91
+ budget data, use CBO's data files (cbo.gov), not FRED.
92
+
93
+ ## 6. Income and other
94
+ | ID | What | Units, frequency |
95
+ |---|---|---|
96
+ | `PCE` | Personal consumption expenditures | Billions of dollars, monthly, SAAR |
97
+ | `DSPIC96` | Real disposable personal income | Billions of chained 2017 dollars, monthly, SAAR |
98
+ | `PSAVERT` / `A072RC1Q156SBEA` | Personal saving rate (NIPA Table 2.6 / 2.1 line 35) | Percent of disposable income, monthly / quarterly |
99
+ | `MEHOINUSA672N` | Real median household income (Census) | Dollars of the latest year (C-CPI-U), annual |
100
+ | `SP500` | S&P 500 index | Index, daily; **Copyrighted: Pre-Approval Required** ✔ (only 10 years on FRED) |
101
+
102
+ **International trade** (the Census/BEA monthly release, FT-900, mirrored keyless; BEA's ITA needs a key)
103
+ | ID | What | Units, frequency |
104
+ |---|---|---|
105
+ | `BOPGSTB` / `BOPGTB` / `BOPSTB` | Trade balance: goods and services / goods / services, balance of payments basis | Millions of dollars, monthly, SA |
106
+ | `BOPTEXP` / `BOPTIMP` | Exports / imports of goods and services, BOP basis | Millions of dollars, monthly, SA |
107
+ | `EXPCH` / `IMPCH` | Goods exports to / imports from China, Census basis (other partners: EXP / IMP + country code) | Millions of dollars, monthly, NSA |
108
+
109
+ Annual totals are sums of the months; the June annual revision replaces the first-published year. Partner
110
+ balances are on the Census basis, as the release gives them.
111
+
112
+ ## 4b. Money stock (Federal Reserve H.6, monthly)
113
+ `M2SL` M2 (billions of dollars, SA), `M1SL` M1, `M2NS` M2 not adjusted, `WM2NS` weekly M2. The H.6 has not
114
+ published growth rates since February 2021: 12-month growth is computed from levels (`pc1`), and the H.6
115
+ data file is the level benchmark.
116
+
117
+ ## 5a. Industrial production and capacity utilization (Federal Reserve G.17, monthly)
118
+ `INDPRO` industrial production, total (index 2017=100), `IPMAN` manufacturing; `TCU` capacity
119
+ utilization, total (percent), `MCUMFN` manufacturing (metadata checked on 2026-10-21). The
120
+ latest months are preliminary and revised for several months. G.17 states the gap to the long-run
121
+ average as the difference of its one-decimal rates (76.9 - 79.4 = 2.5 points below): compute it the
122
+ same way to match, and show the unrounded gap as a sensitivity.
123
+
124
+ ## 5c. Housing starts and permits (Census New Residential Construction, monthly)
125
+ `HOUST` total starts, `HOUST1F` single-family, `PERMIT` permits (thousands of units, SAAR; metadata checked
126
+ on 2026-10-21); `HOUSTNSA` not adjusted. The latest month is preliminary and revised twice.
127
+ An annual total from FRED sums rounded months: Census's annual sheet sums unrounded estimates (0.1 apart).
128
+
129
+ ## 5b. Unemployment insurance claims (DOL, weekly)
130
+ `ICSA` initial claims (SA), `IC4WSA` 4-week moving average (SA), `ICNSA` (NSA), `CCSA` continued claims.
131
+ Weeks end on Saturday; the latest week is an advance figure (preliminary). The keyless route when the dol
132
+ pack has no key. A calendar-year average needs all the weeks of the year (count them; never average a
133
+ partial year).
134
+
135
+ ## 6a. Household debt service (Federal Reserve DSR release)
136
+ Quarterly, percent of disposable personal income: `TDSP` total, `MDSP` mortgage, `CDSP` consumer debt
137
+ service. The Fed rebuilt the series on credit-bureau data in 2024: its levels are about 2.5 points above the
138
+ archived lender-based series (2007 Q4 15.8 against 13.3), so never mix the two; the latest quarter is
139
+ preliminary. Benchmark: federalreserve.gov/releases/dsr.
140
+
141
+ ## 6b. Federal Reserve balance sheet (H.4.1)
142
+ Weekly, millions of dollars (metadata checked on 2026-10-21). Wednesday levels: `WALCL` total
143
+ assets, `TREAST` Treasury securities held outright, `WSHOMCB` mortgage-backed securities, `WSHOSHO` all
144
+ securities held outright, `WLRRAL` reverse repurchase agreements (liability). Week averages (not Wednesday
145
+ levels; do not mix with the above): `WRESBAL` reserve balances, `WTREGEN` Treasury General Account.
146
+ `RRPONTSYD` overnight reverse repos is daily and in billions. Changes between two weeks are differences of
147
+ published levels, not published figures: say so in benchmark.csv. Other assets (premiums, loans, the
148
+ rest) are total minus the securities.
149
+
150
+ ## 6d. House prices and the international investment position
151
+ | ID | What | Units, frequency | Notes |
152
+ |---|---|---|---|
153
+ | `CSUSHPINSA`, `CSUSHPISA` | S&P CoreLogic Case-Shiller U.S. National home price index, NSA / SA | Index Jan 2000=100, monthly, two months' lag | `copyright` preapproval_required: say the values may not be republished; S&P's release leads with NSA 12-month changes |
154
+ | `USSTHPI` | FHFA all-transactions house price index, U.S. | Index 1980:Q1=100, quarterly | Public domain |
155
+ | `IIPUSNETIQ`, `IIPUSNETIA` | U.S. net international investment position (BEA), quarterly / annual | Millions of dollars | The keyless route to BEA's IIP (the BEA pack needs a key for IIP); preliminary for the latest quarter |
156
+
157
+ ## 6c. Exchange rates (Federal Reserve H.10)
158
+ | ID | What | Units, frequency | Notes |
159
+ |---|---|---|---|
160
+ | `DTWEXBGS` | Nominal broad dollar index (trade-weighted, 26 currencies) | Index Jan 2006=100, daily | The Fed's headline dollar index; checked against H.10 [2026-10-22] |
161
+ | `TWEXBGSMTH` | Nominal broad dollar index, monthly average | Index Jan 2006=100, monthly | A year-to-date change can differ in sign between daily end points and monthly averages: say which |
162
+ | `RTWEXBGS` | Real broad dollar index | Index Jan 2006=100, monthly | Adjusted for relative consumer prices |
163
+ | `DEXUSEU`, `DEXJPUS`, `DEXCHUS`, `DEXCAUS`, `DEXMXUS` | Bilateral rates: dollars per euro; yen, yuan, Canadian dollars, pesos per dollar | daily | Mind the quote direction (US per foreign for the euro) |
164
+
165
+ ## 7. Recessions
166
+ `USREC` (monthly; FRBSL from NBER dates; **Copyrighted: Citation Required** ✔), `USRECQ` (quarterly), `USRECD`
167
+ (daily). 1 from the month after the NBER peak through the trough. `"recessions": true` in the spec adds USREC;
168
+ for chart shading, turn its runs of 1 into start and end dates.
169
+ Sahm rule: `SAHMREALTIME` (real-time, as first published; empty where a month's unemployment rate was not
170
+ collected, Oct 2025) and `SAHMCURRENT` (from current UNRATE vintages): the 3-month average of the unemployment
171
+ rate minus its low of the prior 12 months; 0.50 or more signals a recession start.
172
+
173
+ ## 8. States and areas
174
+ - Unemployment rate: `<ST>UR` (CAUR, TXUR ...), monthly, SA (BLS LAUS).
175
+ - Per capita personal income: `<ST>PCPI` (CAPCPI ...), annual (BEA).
176
+ - A full cross-section in one call needs a key: spec `"regional": [{"series_id": "CAUR", "region_type": "state",
177
+ "date": "2026-08-01"}]` (GeoFRED finds the group from any member series). Without a key, list the 50 state IDs
178
+ plus DC explicitly; check each with the `request_schema` search `describe <IDs>` (a 404 means the pattern does
179
+ not hold for that series).
180
+
181
+ ## 9. Finding a series you do not know
182
+ 1. With a key: `request_schema` for fred with the search "federal outlays interest" (sorted by
183
+ popularity; prefer the most popular series from the official source).
184
+ 2. Without a key: search https://fred.stlouisfed.org/searchresults/?st=<words> in the browser (or WebSearch
185
+ "site:fred.stlouisfed.org <words>").
186
+ 3. Confirm with the `request_schema` search `describe <IDs>`: title, units, frequency, seasonal adjustment, last updated. Prefer the series
187
+ published by the original agency (BEA, BLS, OMB, Treasury, CBO, the Board of Governors) over derived copies,
188
+ and an SA series for short-run changes, NSA for 12-month changes and annual averages.