data-analyst-mcp 0.3.0 → 0.3.1

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 (153) hide show
  1. package/README.md +262 -262
  2. package/dist/report/method_audit.js +7 -1
  3. package/dist/report/method_audit.js.map +1 -1
  4. package/dist/report/scan_secrets.d.ts +4 -1
  5. package/dist/report/scan_secrets.js +36 -5
  6. package/dist/report/scan_secrets.js.map +1 -1
  7. package/dist/server.d.ts +1 -1
  8. package/dist/server.js +3 -2
  9. package/dist/server.js.map +1 -1
  10. package/guide/WORKFLOW.md +134 -134
  11. package/guide/assets/disclaimer.txt +1 -1
  12. package/guide/assets/download_data.ps1 +162 -162
  13. package/guide/assets/report_template.html +597 -597
  14. package/guide/references/routing.md +171 -171
  15. package/guide/references/style_guide.md +398 -398
  16. package/package.json +56 -56
  17. package/packs/acf/endpoints.json +114 -114
  18. package/packs/acf/policy.json +104 -104
  19. package/packs/actuaries/endpoints.json +82 -82
  20. package/packs/actuaries/policy.json +109 -109
  21. package/packs/bea/assets/download_bea.ps1 +182 -182
  22. package/packs/bea/docs/bea_api.md +461 -461
  23. package/packs/bea/docs/datasets.md +157 -157
  24. package/packs/bea/docs/report_patterns.md +112 -112
  25. package/packs/bea/policy.json +170 -170
  26. package/packs/bea/source.md +152 -152
  27. package/packs/bls/assets/download_bls.ps1 +152 -152
  28. package/packs/bls/docs/analysis_patterns.md +108 -108
  29. package/packs/bls/docs/bls_api.md +73 -73
  30. package/packs/bls/docs/series_ids.md +149 -149
  31. package/packs/bls/policy.json +238 -238
  32. package/packs/bts/endpoints.json +346 -346
  33. package/packs/bts/policy.json +94 -94
  34. package/packs/cdc/endpoints.json +197 -197
  35. package/packs/cdc/policy.json +83 -83
  36. package/packs/census/endpoints.json +99 -99
  37. package/packs/cfpb/endpoints.json +326 -326
  38. package/packs/cfpb/policy.json +119 -119
  39. package/packs/clinical-trials/endpoints.json +166 -166
  40. package/packs/clinical-trials/policy.json +84 -84
  41. package/packs/cms/endpoints.json +69 -69
  42. package/packs/cms/policy.json +96 -96
  43. package/packs/college-scorecard/endpoints.json +252 -252
  44. package/packs/college-scorecard/policy.json +106 -106
  45. package/packs/congress/endpoints.json +1701 -1701
  46. package/packs/congress/policy.json +117 -117
  47. package/packs/dhs-ohss/endpoints.json +66 -66
  48. package/packs/dhs-ohss/policy.json +107 -107
  49. package/packs/doj-news/endpoints.json +59 -59
  50. package/packs/doj-news/policy.json +96 -96
  51. package/packs/dol/endpoints.json +817 -817
  52. package/packs/dol/policy.json +135 -135
  53. package/packs/eia/endpoints.json +717 -717
  54. package/packs/eia/policy.json +112 -112
  55. package/packs/epa/endpoints.json +291 -291
  56. package/packs/epa/policy.json +99 -99
  57. package/packs/epa-aqs/endpoints.json +173 -173
  58. package/packs/epa-aqs/policy.json +96 -96
  59. package/packs/fbi/endpoints.json +1841 -1841
  60. package/packs/fbi/policy.json +118 -118
  61. package/packs/fda/endpoints.json +237 -237
  62. package/packs/fda/policy.json +121 -121
  63. package/packs/fdic/endpoints.json +416 -416
  64. package/packs/fdic/policy.json +83 -83
  65. package/packs/fec/endpoints.json +707 -707
  66. package/packs/fec/policy.json +93 -93
  67. package/packs/fed-board/endpoints.json +89 -89
  68. package/packs/fed-board/policy.json +136 -136
  69. package/packs/federal-register/endpoints.json +143 -143
  70. package/packs/federal-register/policy.json +86 -86
  71. package/packs/fema/endpoints.json +645 -645
  72. package/packs/fema/policy.json +103 -103
  73. package/packs/fhfa/endpoints.json +105 -105
  74. package/packs/fhfa/policy.json +109 -109
  75. package/packs/fred/assets/download_fred.ps1 +122 -122
  76. package/packs/fred/docs/analysis_patterns.md +124 -124
  77. package/packs/fred/docs/fred_api.md +94 -94
  78. package/packs/fred/docs/series.md +188 -188
  79. package/packs/fred/policy.json +253 -253
  80. package/packs/fsa/endpoints.json +150 -150
  81. package/packs/fsa/policy.json +99 -99
  82. package/packs/govinfo/endpoints.json +519 -519
  83. package/packs/gsa-calc/endpoints.json +93 -93
  84. package/packs/gsa-calc/policy.json +97 -97
  85. package/packs/hud/endpoints.json +146 -146
  86. package/packs/hud/policy.json +84 -84
  87. package/packs/ipums/docs/report_patterns.md +117 -117
  88. package/packs/irs-soi/endpoints.json +114 -114
  89. package/packs/irs-soi/policy.json +107 -107
  90. package/packs/medicaid/endpoints.json +412 -412
  91. package/packs/medicaid/policy.json +108 -108
  92. package/packs/naep/endpoints.json +217 -217
  93. package/packs/naep/policy.json +100 -100
  94. package/packs/nhtsa/endpoints.json +132 -132
  95. package/packs/nhtsa/policy.json +93 -93
  96. package/packs/nih/endpoints.json +452 -452
  97. package/packs/nih/policy.json +86 -86
  98. package/packs/noaa/endpoints.json +431 -431
  99. package/packs/noaa/policy.json +95 -95
  100. package/packs/nrel/endpoints.json +327 -327
  101. package/packs/nrel/policy.json +96 -96
  102. package/packs/nws/endpoints.json +271 -271
  103. package/packs/nws/policy.json +82 -82
  104. package/packs/nyfed/endpoints.json +80 -80
  105. package/packs/nyfed/policy.json +92 -92
  106. package/packs/omb/endpoints.json +460 -460
  107. package/packs/omb/policy.json +106 -106
  108. package/packs/open-payments/endpoints.json +297 -297
  109. package/packs/open-payments/policy.json +101 -101
  110. package/packs/opm/assets/download_opm.ps1 +125 -125
  111. package/packs/opm/docs/fields.md +184 -184
  112. package/packs/opm/docs/opm_api.md +71 -71
  113. package/packs/opm/docs/report_patterns.md +83 -83
  114. package/packs/opm/lib/data_dictionary.csv +73 -73
  115. package/packs/pbgc/endpoints.json +483 -483
  116. package/packs/pbgc/policy.json +94 -94
  117. package/packs/philfed/endpoints.json +85 -85
  118. package/packs/philfed/policy.json +94 -94
  119. package/packs/regulations/endpoints.json +287 -287
  120. package/packs/regulations/policy.json +86 -86
  121. package/packs/sec/endpoints.json +236 -236
  122. package/packs/sec/policy.json +86 -86
  123. package/packs/senate-lobbying/endpoints.json +553 -553
  124. package/packs/senate-lobbying/policy.json +99 -99
  125. package/packs/snapqc/endpoints.json +1426 -1426
  126. package/packs/snapqc/policy.json +92 -92
  127. package/packs/treasury/catalog.json +2267 -2267
  128. package/packs/treasury/docs/api_guide.md +245 -245
  129. package/packs/treasury/docs/datasets.md +56 -56
  130. package/packs/treasury/docs/report_patterns.md +126 -126
  131. package/packs/treasury/policy.json +159 -159
  132. package/packs/treasury/source.md +170 -165
  133. package/packs/treasury-yields/endpoints.json +226 -226
  134. package/packs/treasury-yields/policy.json +86 -86
  135. package/packs/usaspending/endpoints.json +1315 -1315
  136. package/packs/usaspending/policy.json +109 -109
  137. package/packs/usda-fna/policy.json +133 -133
  138. package/packs/usda-fooddata/endpoints.json +180 -180
  139. package/packs/usda-fooddata/policy.json +94 -94
  140. package/packs/usda-nass/endpoints.json +323 -323
  141. package/packs/usda-nass/policy.json +95 -95
  142. package/packs/usda-outlook/endpoints.json +86 -86
  143. package/packs/usda-outlook/policy.json +109 -109
  144. package/packs/usgs/endpoints.json +313 -313
  145. package/packs/usgs/policy.json +95 -95
  146. package/packs/usitc/endpoints.json +74 -74
  147. package/packs/usitc/policy.json +111 -111
  148. package/packs/uspto/endpoints.json +141 -141
  149. package/packs/uspto/policy.json +95 -95
  150. package/packs/va/endpoints.json +414 -414
  151. package/packs/va/policy.json +101 -101
  152. package/packs/world-bank/endpoints.json +122 -122
  153. package/packs/world-bank/policy.json +101 -101
@@ -1,108 +1,108 @@
1
- # Analysis patterns for BLS time series
2
-
3
- Read this once at the start of any analysis. It lists the choices that change headline numbers (and
4
- so become the critical questions), BLS's own conventions to follow, and how a BLS data product is
5
- laid out.
6
-
7
- Contents: 1. Critical questions catalog · 2. Conventions · 3. Benchmarks and reliability ·
8
- 4. Typical questions · 5. Publication structure · 6. Chart forms
9
-
10
- ## 1. Critical questions catalog
11
- Ask only the ones the request leaves open **and** that would change a headline number. Each has a
12
- default rule for "Don't know — decide empirically".
13
-
14
- | Choice | Typical options | Default rule when the user does not know |
15
- |---|---|---|
16
- | **Which measure** | Unemployment: U-3 (official) vs. U-6. Wages: average hourly earnings (CES, all employees or production and nonsupervisory), median weekly earnings (CPS, full-time), ECI (fixed job mix). Inflation: CPI-U, CPI-W, C-CPI-U; headline vs. core. Jobs: payroll (CES) vs. household (CPS) employment | Use the measure BLS leads with in its news release (U-3, CES payrolls, CPI-U headline). For wages, show AHE and say that composition shifts move it (2020); add ECI when the period includes large composition changes |
17
- | **Seasonal adjustment** | SA vs. NSA | Month-to-month or short-run changes, levels in charts: SA. 12-month changes of the CPI: NSA (BLS's headline 12-month CPI change uses NSA indexes). Import/export price indexes have no SA version: NSA throughout. Annual averages: NSA (BLS computes them from NSA data) |
18
- | **Frequency** | Monthly, quarterly, annual averages | Monthly for spans up to about 10 years; annual averages for long histories. Use BLS-published annual averages (v2 key) over computed ones |
19
- | **Period and baseline** | Since a date (Feb 2020 pre-pandemic peak, Jan 2021, 10 years), calendar years, a recession | The business-cycle peak before the event the user cares about (Feb 2020 for the pandemic); otherwise the latest 10 years. Show a sensitivity with one alternative baseline (2019 average) |
20
- | **Nominal vs. real** | Current dollars vs. constant dollars; deflator CPI-U, CPI-W, C-CPI-U (PCE is BEA, not BLS) | Real, deflated as BLS does it: CPI-W for production and nonsupervisory employees, CPI-U for all employees and other groups (all items, NSA for annual, SA for monthly), base = latest full year; say "in <year> dollars". CPI-U-RS is not in the API |
21
- | **Change measure** | Net change, percent change, 12-month change, annualized 3- or 6-month rate, CAGR | Follow the series' BLS convention: payrolls as net change (thousands); rates as percentage-point change; prices and wages as 12-month percent change, plus annualized 3-month for momentum |
22
- | **Geography** | U.S., state (LAUS, CES state), metro, county | As asked. State unemployment: LAUS SA. Note that LAUS and state CES are model-based and revised each March |
23
- | **Gaps and preliminary data** | Interpolate a missing month or leave it; include preliminary months | Leave gaps empty; compute changes only between published values (say so); include preliminary values but label them |
24
- | **Comparison groups** | Demographic groups (CPS), industries (CES), areas | As asked; flag thin CPS groups (small groups have wide confidence intervals; use 12-month averages or annual averages) |
25
-
26
- Ask at most four, in one round. A question about which series ID to use is never put to the user:
27
- resolve it yourself with the `request_schema` search `describe <ID>` and the tables in `series_ids.md`.
28
-
29
- ## 2. Conventions
30
- - **Definitions:** unemployment rate = unemployed ÷ labor force; participation rate = labor force ÷
31
- civilian noninstitutional population; employment-population ratio = employed ÷ population. CES counts
32
- jobs (a person with two jobs counts twice); CPS counts people.
33
- - **Units:** CES and CPS levels are in thousands. JOLTS levels are in thousands; rates are percentages.
34
- CPI is an index (1982-84=100); never report an index level as a price.
35
- - **Percent changes of indexes:** compute from the published index values (rounded to three decimals) and
36
- round the result to one decimal; that reproduces BLS's published CPI changes.
37
- - **Social Security COLA** (SSA's rule, not a BLS series): the CPI-W, not seasonally adjusted (`CWUR0000SA0`),
38
- averaged over July-September and rounded to three decimals, compared with the same average of the last
39
- year a COLA was paid; the percent increase rounded to one decimal is the COLA payable from the next
40
- January. SSA announces it with the September CPI (mid-October); benchmark against SSA's announcement.
41
- - **12-month change across a gap:** October 2026 vs. October 2025 has no value when October 2025 was not
42
- collected. Say so; do not substitute September or an interpolated value.
43
- - **Revisions:** CES revises the two prior months each release and benchmarks every February (back to the
44
- previous March); seasonal factors for CPI are revised each February for five years; LAUS is revised each
45
- March; C-CPI-U is final 10 to 12 months later. State the retrieval date (the builder adds it).
46
- - **January population controls (CPS):** levels shift in January; compare levels across Januaries only with
47
- a note, or use rates.
48
- - **Annual averages:** BLS's M13 values are preferred. A computed average needs all 12 months; a year with a
49
- gap has no computed average (leave it empty).
50
- - **Recessions (NBER):** March–November 2001, December 2007–June 2009, February–April 2020. Use the note
51
- "Recessions begin just after a peak in economic activity and run through the subsequent trough."
52
- - **Correlation, not cause:** a policy or event "coincided with" a change unless a method that supports a
53
- causal claim was used.
54
-
55
- ## 3. Benchmarks and reliability
56
- - **Benchmark every headline number** against a BLS publication: the latest news release (Employment
57
- Situation, CPI, JOLTS, Employment Cost Index, Productivity and Costs, State Employment and Unemployment),
58
- or the API's own `calculations` (fetch with a key and `"calculations": true`; they arrive as
59
- `bls_pct_12m`, `bls_net_1m` ... columns). Record the comparison in Data and Methods.
60
- - **Statistical significance:** BLS tests at the 90-percent level. Published thresholds (read the current
61
- technical note before using, they are updated; values below are from 2026-10-19):
62
- - CES total nonfarm monthly change: about ±122,000 (Employment Situation technical note).
63
- - CPS monthly change in unemployment: about ±425,000; in the unemployment rate: about ±0.3 percentage point.
64
- - JOLTS: median standard errors in the "significant change" tables on the JOLTS page.
65
- - CPI: standard errors of 1-, 2-, 6- and 12-month changes on the CPI variance estimates page.
66
- Compare each change with its threshold before describing it. Call a change "statistically significant"
67
- only when it exceeds the threshold; otherwise "little changed" (BLS's own phrase) or "about the same".
68
- - Sampling error does not apply to QCEW (a census of UI records), but revisions do.
69
-
70
- ## 4. Typical questions
71
- - **Labor market since the pandemic:** unemployment (U-3, U-6), participation and prime-age employment rate,
72
- payrolls vs. February 2020, job openings and quits. Benchmark: the latest Employment Situation and JOLTS.
73
- - **Inflation:** 12-month CPI-U change (NSA), core vs. headline, contributions of food, energy, shelter;
74
- 3-month annualized core for momentum. Benchmark: CPI news release table A.
75
- - **Real wages:** BLS's own real AHE: `CES0500000013` all employees (CPI-U), `CES0500000032` production and
76
- nonsupervisory employees (CPI-W, `CWSR0000SA0`), as the Real Earnings release reports them; real median weekly
77
- earnings, `LES1252881600` seasonally adjusted, as the Usual Weekly Earnings release headlines it); ECI vs. CPI over 12 months.
78
- - **States and metros:** LAUS unemployment rates ranked, change over a year; state payrolls (SM).
79
- - **Industries:** CES employment by supersector, net change since a baseline; JOLTS by industry.
80
- - **Productivity and labor costs:** quarterly annualized rates; long-run averages by business cycle.
81
-
82
- ## 5. Publication structure (the report builder's `"mode": "report"`)
83
- Same exhibit chartbook as the style guide describes:
84
- 1. Cover with the month and year, the title with the period, and an optional hero chart.
85
- 2. **At a Glance:** one framing paragraph (which measures, which period) and 3–5 findings, each with a bold
86
- lead naming its section.
87
- 3. Contents and List of Exhibits (built automatically).
88
- 4. **Notes About This Report:** calendar years; rounding; seasonal adjustment; dollar year and deflator;
89
- data source and retrieval date; definitions; preliminary values and gaps; recession shading.
90
- 5. **Introduction:** a lead paragraph with the headline numbers; question-style subsections ("How Has
91
- Unemployment Changed Since 2019?") and "What Data Were Used?".
92
- 6. **Sections** (2–5): a summary page, then one exhibit per page with 2–4 paragraphs beside the chart
93
- (level, change, comparison).
94
- 7. **Appendix A: Data and Methods:** series IDs and titles, seasonal adjustment, definitions, computations
95
- (change measures, deflation, annual averages), benchmark comparisons, significance thresholds,
96
- limitations. The builder appends the data vintage and the BLS terms statement.
97
- 8. References; About This Document (optional); replication materials and audit trail.
98
-
99
- Exhibit titles end with the period: "Unemployment Rate, January 2019 to September 2026". The units line
100
- names the adjustment: "Percent, seasonally adjusted". Source line: "Analyst calculations using data from the
101
- Bureau of Labor Statistics, Current Population Survey (series LNS14000000)."
102
-
103
- ## 6. Chart forms
104
- - Trends: line charts, at most 4–5 series; facet rather than crowd. Monthly x-axis labels "Sep 2026".
105
- - Changes by group at one date: horizontal bars when labels are long (industries, states), columns otherwise.
106
- - Composition (contributions to CPI change, payroll gains by industry): stacked columns.
107
- - Index comparisons (wages vs. prices): rebase both to 100 at the same date (a `compute` derive step).
108
- - No dual axes, no pies, no 3-D. Do not draw a line through a gap: leave the cell empty in the exhibit CSV.
1
+ # Analysis patterns for BLS time series
2
+
3
+ Read this once at the start of any analysis. It lists the choices that change headline numbers (and
4
+ so become the critical questions), BLS's own conventions to follow, and how a BLS data product is
5
+ laid out.
6
+
7
+ Contents: 1. Critical questions catalog · 2. Conventions · 3. Benchmarks and reliability ·
8
+ 4. Typical questions · 5. Publication structure · 6. Chart forms
9
+
10
+ ## 1. Critical questions catalog
11
+ Ask only the ones the request leaves open **and** that would change a headline number. Each has a
12
+ default rule for "Don't know — decide empirically".
13
+
14
+ | Choice | Typical options | Default rule when the user does not know |
15
+ |---|---|---|
16
+ | **Which measure** | Unemployment: U-3 (official) vs. U-6. Wages: average hourly earnings (CES, all employees or production and nonsupervisory), median weekly earnings (CPS, full-time), ECI (fixed job mix). Inflation: CPI-U, CPI-W, C-CPI-U; headline vs. core. Jobs: payroll (CES) vs. household (CPS) employment | Use the measure BLS leads with in its news release (U-3, CES payrolls, CPI-U headline). For wages, show AHE and say that composition shifts move it (2020); add ECI when the period includes large composition changes |
17
+ | **Seasonal adjustment** | SA vs. NSA | Month-to-month or short-run changes, levels in charts: SA. 12-month changes of the CPI: NSA (BLS's headline 12-month CPI change uses NSA indexes). Import/export price indexes have no SA version: NSA throughout. Annual averages: NSA (BLS computes them from NSA data) |
18
+ | **Frequency** | Monthly, quarterly, annual averages | Monthly for spans up to about 10 years; annual averages for long histories. Use BLS-published annual averages (v2 key) over computed ones |
19
+ | **Period and baseline** | Since a date (Feb 2020 pre-pandemic peak, Jan 2021, 10 years), calendar years, a recession | The business-cycle peak before the event the user cares about (Feb 2020 for the pandemic); otherwise the latest 10 years. Show a sensitivity with one alternative baseline (2019 average) |
20
+ | **Nominal vs. real** | Current dollars vs. constant dollars; deflator CPI-U, CPI-W, C-CPI-U (PCE is BEA, not BLS) | Real, deflated as BLS does it: CPI-W for production and nonsupervisory employees, CPI-U for all employees and other groups (all items, NSA for annual, SA for monthly), base = latest full year; say "in <year> dollars". CPI-U-RS is not in the API |
21
+ | **Change measure** | Net change, percent change, 12-month change, annualized 3- or 6-month rate, CAGR | Follow the series' BLS convention: payrolls as net change (thousands); rates as percentage-point change; prices and wages as 12-month percent change, plus annualized 3-month for momentum |
22
+ | **Geography** | U.S., state (LAUS, CES state), metro, county | As asked. State unemployment: LAUS SA. Note that LAUS and state CES are model-based and revised each March |
23
+ | **Gaps and preliminary data** | Interpolate a missing month or leave it; include preliminary months | Leave gaps empty; compute changes only between published values (say so); include preliminary values but label them |
24
+ | **Comparison groups** | Demographic groups (CPS), industries (CES), areas | As asked; flag thin CPS groups (small groups have wide confidence intervals; use 12-month averages or annual averages) |
25
+
26
+ Ask at most four, in one round. A question about which series ID to use is never put to the user:
27
+ resolve it yourself with the `request_schema` search `describe <ID>` and the tables in `series_ids.md`.
28
+
29
+ ## 2. Conventions
30
+ - **Definitions:** unemployment rate = unemployed ÷ labor force; participation rate = labor force ÷
31
+ civilian noninstitutional population; employment-population ratio = employed ÷ population. CES counts
32
+ jobs (a person with two jobs counts twice); CPS counts people.
33
+ - **Units:** CES and CPS levels are in thousands. JOLTS levels are in thousands; rates are percentages.
34
+ CPI is an index (1982-84=100); never report an index level as a price.
35
+ - **Percent changes of indexes:** compute from the published index values (rounded to three decimals) and
36
+ round the result to one decimal; that reproduces BLS's published CPI changes.
37
+ - **Social Security COLA** (SSA's rule, not a BLS series): the CPI-W, not seasonally adjusted (`CWUR0000SA0`),
38
+ averaged over July-September and rounded to three decimals, compared with the same average of the last
39
+ year a COLA was paid; the percent increase rounded to one decimal is the COLA payable from the next
40
+ January. SSA announces it with the September CPI (mid-October); benchmark against SSA's announcement.
41
+ - **12-month change across a gap:** October 2026 vs. October 2025 has no value when October 2025 was not
42
+ collected. Say so; do not substitute September or an interpolated value.
43
+ - **Revisions:** CES revises the two prior months each release and benchmarks every February (back to the
44
+ previous March); seasonal factors for CPI are revised each February for five years; LAUS is revised each
45
+ March; C-CPI-U is final 10 to 12 months later. State the retrieval date (the builder adds it).
46
+ - **January population controls (CPS):** levels shift in January; compare levels across Januaries only with
47
+ a note, or use rates.
48
+ - **Annual averages:** BLS's M13 values are preferred. A computed average needs all 12 months; a year with a
49
+ gap has no computed average (leave it empty).
50
+ - **Recessions (NBER):** March–November 2001, December 2007–June 2009, February–April 2020. Use the note
51
+ "Recessions begin just after a peak in economic activity and run through the subsequent trough."
52
+ - **Correlation, not cause:** a policy or event "coincided with" a change unless a method that supports a
53
+ causal claim was used.
54
+
55
+ ## 3. Benchmarks and reliability
56
+ - **Benchmark every headline number** against a BLS publication: the latest news release (Employment
57
+ Situation, CPI, JOLTS, Employment Cost Index, Productivity and Costs, State Employment and Unemployment),
58
+ or the API's own `calculations` (fetch with a key and `"calculations": true`; they arrive as
59
+ `bls_pct_12m`, `bls_net_1m` ... columns). Record the comparison in Data and Methods.
60
+ - **Statistical significance:** BLS tests at the 90-percent level. Published thresholds (read the current
61
+ technical note before using, they are updated; values below are from 2026-10-19):
62
+ - CES total nonfarm monthly change: about ±122,000 (Employment Situation technical note).
63
+ - CPS monthly change in unemployment: about ±425,000; in the unemployment rate: about ±0.3 percentage point.
64
+ - JOLTS: median standard errors in the "significant change" tables on the JOLTS page.
65
+ - CPI: standard errors of 1-, 2-, 6- and 12-month changes on the CPI variance estimates page.
66
+ Compare each change with its threshold before describing it. Call a change "statistically significant"
67
+ only when it exceeds the threshold; otherwise "little changed" (BLS's own phrase) or "about the same".
68
+ - Sampling error does not apply to QCEW (a census of UI records), but revisions do.
69
+
70
+ ## 4. Typical questions
71
+ - **Labor market since the pandemic:** unemployment (U-3, U-6), participation and prime-age employment rate,
72
+ payrolls vs. February 2020, job openings and quits. Benchmark: the latest Employment Situation and JOLTS.
73
+ - **Inflation:** 12-month CPI-U change (NSA), core vs. headline, contributions of food, energy, shelter;
74
+ 3-month annualized core for momentum. Benchmark: CPI news release table A.
75
+ - **Real wages:** BLS's own real AHE: `CES0500000013` all employees (CPI-U), `CES0500000032` production and
76
+ nonsupervisory employees (CPI-W, `CWSR0000SA0`), as the Real Earnings release reports them; real median weekly
77
+ earnings, `LES1252881600` seasonally adjusted, as the Usual Weekly Earnings release headlines it); ECI vs. CPI over 12 months.
78
+ - **States and metros:** LAUS unemployment rates ranked, change over a year; state payrolls (SM).
79
+ - **Industries:** CES employment by supersector, net change since a baseline; JOLTS by industry.
80
+ - **Productivity and labor costs:** quarterly annualized rates; long-run averages by business cycle.
81
+
82
+ ## 5. Publication structure (the report builder's `"mode": "report"`)
83
+ Same exhibit chartbook as the style guide describes:
84
+ 1. Cover with the month and year, the title with the period, and an optional hero chart.
85
+ 2. **At a Glance:** one framing paragraph (which measures, which period) and 3–5 findings, each with a bold
86
+ lead naming its section.
87
+ 3. Contents and List of Exhibits (built automatically).
88
+ 4. **Notes About This Report:** calendar years; rounding; seasonal adjustment; dollar year and deflator;
89
+ data source and retrieval date; definitions; preliminary values and gaps; recession shading.
90
+ 5. **Introduction:** a lead paragraph with the headline numbers; question-style subsections ("How Has
91
+ Unemployment Changed Since 2019?") and "What Data Were Used?".
92
+ 6. **Sections** (2–5): a summary page, then one exhibit per page with 2–4 paragraphs beside the chart
93
+ (level, change, comparison).
94
+ 7. **Appendix A: Data and Methods:** series IDs and titles, seasonal adjustment, definitions, computations
95
+ (change measures, deflation, annual averages), benchmark comparisons, significance thresholds,
96
+ limitations. The builder appends the data vintage and the BLS terms statement.
97
+ 8. References; About This Document (optional); replication materials and audit trail.
98
+
99
+ Exhibit titles end with the period: "Unemployment Rate, January 2019 to September 2026". The units line
100
+ names the adjustment: "Percent, seasonally adjusted". Source line: "Analyst calculations using data from the
101
+ Bureau of Labor Statistics, Current Population Survey (series LNS14000000)."
102
+
103
+ ## 6. Chart forms
104
+ - Trends: line charts, at most 4–5 series; facet rather than crowd. Monthly x-axis labels "Sep 2026".
105
+ - Changes by group at one date: horizontal bars when labels are long (industries, states), columns otherwise.
106
+ - Composition (contributions to CPI change, payroll gains by industry): stacked columns.
107
+ - Index comparisons (wages vs. prices): rebase both to 100 at the same date (a `compute` derive step).
108
+ - No dual axes, no pies, no 3-D. Do not draw a line through a gap: leave the cell empty in the exhibit CSV.
@@ -1,73 +1,73 @@
1
- # BLS Public Data API cheat sheet
2
-
3
- The `fetch` tool already handles all of this. Read this file when you debug an API problem or need a feature
4
- the bls spec does not expose. Behaviors marked ✔ were tested on 2026-10-19.
5
-
6
- ## Versions and limits (https://www.bls.gov/developers/api_faqs.htm)
7
- | | v2, registered key | v1, no key |
8
- |---|---|---|
9
- | Queries per day | 500 | 25 |
10
- | Series per query | 50 | 25 |
11
- | Years per query | 20 | 10 |
12
- | Requests per 10 seconds | 50 | 50 |
13
- | Annual averages, catalog (titles), net/percent changes | yes | no |
14
-
15
- - Register at https://data.bls.gov/registrationEngine/ (email + organization; the key arrives by email
16
- from labstat@bls.gov). **Keys expire after a year**; a rejected key that used to work is usually expired.
17
- - Daily limits are per key (v2) or per IP address (v1). This server does not count the queries used today;
18
- only BLS knows how many remain, and it says so only by refusing once the limit is used up.
19
- - Calling v2 without a key works ✔ but gets v1 limits and no catalog ("The catalog has been disabled for
20
- this request").
21
-
22
- ## Endpoint
23
- `POST https://api.bls.gov/publicAPI/v2/timeseries/data/` (or `/v1/`) with `Content-Type: application/json`:
24
- ```json
25
- {"seriesid": ["LNS14000000", "CES0000000001"], "startyear": "2015", "endyear": "2024",
26
- "annualaverage": true, "catalog": true, "calculations": true, "aspects": false,
27
- "registrationkey": "<key>"}
28
- ```
29
- - `GET .../timeseries/data/<SERIES_ID>` returns the last three years of one series; `?latest=true` the latest value.
30
- - A bare GET of the endpoint returns HTTP 415 and costs no query ✔ (it shows the host is reachable, but not
31
- whether POSTs are blocked: see HTTP 503 below).
32
- - Responses:
33
- `{"status": "REQUEST_SUCCEEDED", "message": [...], "Results": {"series": [{"seriesID", "data": [...], "catalog"?}]}}`.
34
- Each observation: `{"year": "2026", "period": "M09", "periodName": "September", "latest": "true",
35
- "value": "4.2", "footnotes": [{"code": "P", "text": "preliminary"}], "calculations"?: {...}}`.
36
-
37
- ## Gotchas (all handled by fetch; check for them in any code you write yourself)
38
- - **HTTP 200 even on failure ✔.** Read `status` and `message`. A rejected key gives
39
- `REQUEST_NOT_PROCESSED` and a message that **echoes the key** ✔, so always pass messages through `redact()`.
40
- - **Silent truncation ✔.** Asking v1 for more than 10 years returns `REQUEST_SUCCEEDED` with only 10 years
41
- and the message "Year range has been reduced to the system-allowed limit of 10 years." fetch splits
42
- the request so this never happens and stops if it does.
43
- - **Bad series IDs do not fail the request ✔.** The series comes back with `"data": []` and a message such as
44
- "Series does not exist", "Database is locked for Series X" or "No Data Available for Series X Year: 2024".
45
- fetch lists them in `problems`.
46
- - **Missing values ✔** come as `"value": "-"` with a footnote, for example code `X` / `9` "Data unavailable due
47
- to the 2025 lapse in appropriations" (October 2025 CPI, CPS and LAUS were not collected) or code `10`
48
- (CPS weekly earnings, 2025 Q4 not produced). They are empty in `bls_series.csv`.
49
- - **"Unable to get Catalog Data for series X" ✔** can come back for some series (JOLTS, for example) even on v1,
50
- which never asks for the catalog. It is informational: the data are complete. It is kept in
51
- `series.csv` `bls_messages`; titles then come from data.bls.gov (`request_schema` search `describe <ID>`).
52
- - **Preliminary values ✔** carry footnote code `P` (CES: the two latest months; JOLTS and LAUS: the latest).
53
- - **Population controls ✔.** CPS January values carry footnote code `12` when new population controls were
54
- introduced: levels (employment, labor force) are not comparable from December to January; rates are
55
- little affected. Say so when comparing levels across January.
56
- - **Periods:** `M01`–`M12` months, `M13` annual average (v2 with `annualaverage`), `Q01`–`Q04` quarters,
57
- `Q05` annual average of a quarterly series, `S01`/`S02` half-years, `S03` annual, `A01` annual (OEWS).
58
- - **Calculations** (v2): `net_changes` and `pct_changes` over 1, 3, 6 and 12 months, BLS's own numbers.
59
- They are the best benchmark for changes you compute (`bls_pct_12m` etc. in `bls_series.csv`).
60
- - HTTP 429 means the rate or daily limit was hit; the client backs off once, then fetch fails with
61
- `agency_unavailable` (the daily limit resets the next day).
62
- - HTTP 503 "The BLS website is busy" (an HTML page) can answer POSTs for hours while the bare GET still
63
- answers 415 (seen 2026-10-22); after retries fetch fails with `agency_unavailable`.
64
-
65
- ## Other BLS data services (not used by fetch)
66
- - QCEW has its own open-data CSV slices (https://www.bls.gov/cew/additional-resources/open-data/); QCEW
67
- series (prefix EN) are also in the time-series API.
68
- - Bulk flat files (download.bls.gov/pub/time.series/) need a User-Agent with a contact email; this pack does
69
- not use them. A very large request (hundreds of series) is split across days or narrowed instead.
70
- - Web pages on www.bls.gov often answer HTTP 403 to scripts and to WebFetch. Read publications in the
71
- browser, or through the Wayback Machine (`https://web.archive.org/web/<year>/<url>`), and cite the original URL.
72
- `https://data.bls.gov/timeseries/<ID>` (series titles, used by the `request_schema` search `describe <ID>`)
73
- does answer scripts ✔.
1
+ # BLS Public Data API cheat sheet
2
+
3
+ The `fetch` tool already handles all of this. Read this file when you debug an API problem or need a feature
4
+ the bls spec does not expose. Behaviors marked ✔ were tested on 2026-10-19.
5
+
6
+ ## Versions and limits (https://www.bls.gov/developers/api_faqs.htm)
7
+ | | v2, registered key | v1, no key |
8
+ |---|---|---|
9
+ | Queries per day | 500 | 25 |
10
+ | Series per query | 50 | 25 |
11
+ | Years per query | 20 | 10 |
12
+ | Requests per 10 seconds | 50 | 50 |
13
+ | Annual averages, catalog (titles), net/percent changes | yes | no |
14
+
15
+ - Register at https://data.bls.gov/registrationEngine/ (email + organization; the key arrives by email
16
+ from labstat@bls.gov). **Keys expire after a year**; a rejected key that used to work is usually expired.
17
+ - Daily limits are per key (v2) or per IP address (v1). This server does not count the queries used today;
18
+ only BLS knows how many remain, and it says so only by refusing once the limit is used up.
19
+ - Calling v2 without a key works ✔ but gets v1 limits and no catalog ("The catalog has been disabled for
20
+ this request").
21
+
22
+ ## Endpoint
23
+ `POST https://api.bls.gov/publicAPI/v2/timeseries/data/` (or `/v1/`) with `Content-Type: application/json`:
24
+ ```json
25
+ {"seriesid": ["LNS14000000", "CES0000000001"], "startyear": "2015", "endyear": "2024",
26
+ "annualaverage": true, "catalog": true, "calculations": true, "aspects": false,
27
+ "registrationkey": "<key>"}
28
+ ```
29
+ - `GET .../timeseries/data/<SERIES_ID>` returns the last three years of one series; `?latest=true` the latest value.
30
+ - A bare GET of the endpoint returns HTTP 415 and costs no query ✔ (it shows the host is reachable, but not
31
+ whether POSTs are blocked: see HTTP 503 below).
32
+ - Responses:
33
+ `{"status": "REQUEST_SUCCEEDED", "message": [...], "Results": {"series": [{"seriesID", "data": [...], "catalog"?}]}}`.
34
+ Each observation: `{"year": "2026", "period": "M09", "periodName": "September", "latest": "true",
35
+ "value": "4.2", "footnotes": [{"code": "P", "text": "preliminary"}], "calculations"?: {...}}`.
36
+
37
+ ## Gotchas (all handled by fetch; check for them in any code you write yourself)
38
+ - **HTTP 200 even on failure ✔.** Read `status` and `message`. A rejected key gives
39
+ `REQUEST_NOT_PROCESSED` and a message that **echoes the key** ✔, so always pass messages through `redact()`.
40
+ - **Silent truncation ✔.** Asking v1 for more than 10 years returns `REQUEST_SUCCEEDED` with only 10 years
41
+ and the message "Year range has been reduced to the system-allowed limit of 10 years." fetch splits
42
+ the request so this never happens and stops if it does.
43
+ - **Bad series IDs do not fail the request ✔.** The series comes back with `"data": []` and a message such as
44
+ "Series does not exist", "Database is locked for Series X" or "No Data Available for Series X Year: 2024".
45
+ fetch lists them in `problems`.
46
+ - **Missing values ✔** come as `"value": "-"` with a footnote, for example code `X` / `9` "Data unavailable due
47
+ to the 2025 lapse in appropriations" (October 2025 CPI, CPS and LAUS were not collected) or code `10`
48
+ (CPS weekly earnings, 2025 Q4 not produced). They are empty in `bls_series.csv`.
49
+ - **"Unable to get Catalog Data for series X" ✔** can come back for some series (JOLTS, for example) even on v1,
50
+ which never asks for the catalog. It is informational: the data are complete. It is kept in
51
+ `series.csv` `bls_messages`; titles then come from data.bls.gov (`request_schema` search `describe <ID>`).
52
+ - **Preliminary values ✔** carry footnote code `P` (CES: the two latest months; JOLTS and LAUS: the latest).
53
+ - **Population controls ✔.** CPS January values carry footnote code `12` when new population controls were
54
+ introduced: levels (employment, labor force) are not comparable from December to January; rates are
55
+ little affected. Say so when comparing levels across January.
56
+ - **Periods:** `M01`–`M12` months, `M13` annual average (v2 with `annualaverage`), `Q01`–`Q04` quarters,
57
+ `Q05` annual average of a quarterly series, `S01`/`S02` half-years, `S03` annual, `A01` annual (OEWS).
58
+ - **Calculations** (v2): `net_changes` and `pct_changes` over 1, 3, 6 and 12 months, BLS's own numbers.
59
+ They are the best benchmark for changes you compute (`bls_pct_12m` etc. in `bls_series.csv`).
60
+ - HTTP 429 means the rate or daily limit was hit; the client backs off once, then fetch fails with
61
+ `agency_unavailable` (the daily limit resets the next day).
62
+ - HTTP 503 "The BLS website is busy" (an HTML page) can answer POSTs for hours while the bare GET still
63
+ answers 415 (seen 2026-10-22); after retries fetch fails with `agency_unavailable`.
64
+
65
+ ## Other BLS data services (not used by fetch)
66
+ - QCEW has its own open-data CSV slices (https://www.bls.gov/cew/additional-resources/open-data/); QCEW
67
+ series (prefix EN) are also in the time-series API.
68
+ - Bulk flat files (download.bls.gov/pub/time.series/) need a User-Agent with a contact email; this pack does
69
+ not use them. A very large request (hundreds of series) is split across days or narrowed instead.
70
+ - Web pages on www.bls.gov often answer HTTP 403 to scripts and to WebFetch. Read publications in the
71
+ browser, or through the Wayback Machine (`https://web.archive.org/web/<year>/<url>`), and cite the original URL.
72
+ `https://data.bls.gov/timeseries/<ID>` (series titles, used by the `request_schema` search `describe <ID>`)
73
+ does answer scripts ✔.