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,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 ✔.
@@ -1,149 +1,149 @@
1
- # Series IDs
2
-
3
- A wrong series ID is the most common silent error: the number exists, it is just not the number the
4
- user asked about. Before downloading, call `request_schema` for bls with the search `describe <ID> ...` and read
5
- the title, the seasonal adjustment and the dimensions back against the request.
6
-
7
- Contents: 1. How IDs are built · 2. Verified common series · 3. Finding an ID you do not know · 4. ID builders
8
-
9
- ## 1. How IDs are built
10
- The first two letters name the survey; for most surveys the third is **S** (seasonally adjusted) or
11
- **U** (not seasonally adjusted). Full formats: https://www.bls.gov/help/hlpforma.htm.
12
-
13
- | Prefix | Survey | Structure (after the prefix and S/U) |
14
- |---|---|---|
15
- | LN | Current Population Survey (household survey) | 8-digit series code, e.g. `LNS14000000` |
16
- | CE | Current Employment Statistics (payroll survey), national | 8-digit industry + 2-digit data type (`01` employment, thousands; `02` avg weekly hours; `03` avg hourly earnings; `08` AHE production and nonsupervisory; `11` avg weekly earnings; `13` real AHE, 1982-84 dollars (CPI-U); `32` real AHE of production and nonsupervisory employees (CPI-W)) |
17
- | SM | CES state and metro | 2-digit state FIPS + 5-digit area + 8-digit industry + 2-digit data type |
18
- | CU / CW / SU | CPI-U / CPI-W / chained CPI-U | `R` (monthly) or `S` (semiannual) + 4-char area (`0000` U.S. city average, `S49A` Los Angeles ...) + item (`SA0` all items, `SA0L1E` less food and energy, `SAF1` food, `SAF11` food at home, `SEFV` food away from home, `SA0E` energy, `SAH1` shelter, `SEHA` rent, `SEHC` owners' equivalent rent, `SETB01` gasoline, `SAM` medical care, `SAM2` medical care services, `SETE` motor vehicle insurance, `SETA02` used cars and trucks, `SAS` services) |
19
- | WP / PC | PPI commodities and final demand / industries | `WPSFD4` final demand SA, `WPUFD4` NSA |
20
- | JT | JOLTS | 6-digit industry + 2-digit state + 5-digit area + 2-char size class + 2-char element (`JO` openings, `HI` hires, `QU` quits, `TS` total separations, `LD` layoffs) + `L` level (thousands) or `R` rate |
21
- | LA | Local Area Unemployment Statistics | 2-char area type (`ST` state, `MT` metro, `CN` county) + 13-digit area code + 2-digit measure (`03` rate, `04` unemployed, `05` employed, `06` labor force) |
22
- | EN | QCEW | `U` + area (5) + data type (1) + size (1) + ownership (1) + industry code as written, not padded (`10` = all industries, or the NAICS code): `ENU2403110110` = Montgomery County MD, federal government employment [checked 2026-10-22] |
23
- | OE | OEWS (annual, period A01) | area type + area + industry + occupation (SOC) + data type |
24
- | CI | Employment Cost Index (quarterly) | `CI` + S/U + owner (`1` civilian, `2` private industry, `3` state and local government) + `0` + component (`1` total compensation, `2` wages and salaries, `3` benefits) + `0000000000` + `I` index or `A` 12-month percent change (NSA; BLS's headline 12-month changes): `CIU2020000000000A` private wages and salaries, `CIU3020000000000A` state and local (titles read back from data.bls.gov on 2026-10-21) |
25
- | PR | Productivity and costs (quarterly) | `PRS85006092` nonfarm business labor productivity, percent change at annual rate; `PRS85006112` unit labor costs; indexes 2017=100 (for growth since a date): `PRS85006093` productivity, `PRS85006103` hourly compensation, `PRS85006153` real hourly compensation, `PRS85006173` labor share, `PRS85006143` output price deflator |
26
- | LE | CPS usual weekly earnings (quarterly) | `LEU0252881500` median weekly earnings, full-time wage and salary workers |
27
-
28
- ## 2. Verified common series ✔ (returned data on 2026-10-19; labels checked against the BLS series titles on 2026-10-21)
29
- | Measure | SA | NSA / other |
30
- |---|---|---|
31
- | Unemployment rate (U-3), 16+ | `LNS14000000` | `LNU04000000` |
32
- | U-6 rate | `LNS13327709` | |
33
- | Labor force participation rate | `LNS11300000` | |
34
- | Employment-population ratio | `LNS12300000` | |
35
- | Participation rate, ages 25 to 54 | `LNS11300060` | |
36
- | Employment-population ratio, ages 25 to 54 (total; men `LNS12300061`, women `LNS12300062`) | `LNS12300060` | |
37
- | Employed / unemployed, levels (thousands) | `LNS12000000` / `LNS13000000` | |
38
- | Unemployment rate: men 16+, women 16+ | `LNS14000001`, `LNS14000002` | |
39
- | Unemployment rate: White, Black, Hispanic, Asian | `LNS14000003`, `LNS14000006` (from 1972), `LNS14000009` (from 1973), `LNS14032183` (from 2000) | `LNU04000003`, `LNU04000006`, `LNU04000009`, `LNU04032183` |
40
- | Unemployment rate, ages 16 to 24 / 16 to 19 / 20 to 24 | `LNS14024887` / `LNS14000012` / `LNS14000036` | `LNU04024887` (16 to 24) |
41
- | Unemployment rate by education, 25 and over: less than high school / high school, no college / some college or associate / bachelor's and higher | `LNS14027659` / `LNS14027660` / `LNS14027689` / `LNS14027662` (from 1992) | `LNU04027659` ... (same suffixes) |
42
- | Total nonfarm payrolls (thousands) | `CES0000000001` | `CEU0000000001` |
43
- | Total private / government / manufacturing payrolls | `CES0500000001` / `CES9000000001` / `CES3000000001` | |
44
- | Average hourly earnings, all private employees | `CES0500000003` | |
45
- | AHE, production and nonsupervisory | `CES0500000008` | |
46
- | Real AHE (1982-84 dollars) | `CES0500000013` | |
47
- | Average weekly hours, private | `CES0500000002` | |
48
- | CPI-U all items (1982-84=100) | `CUSR0000SA0` | `CUUR0000SA0` |
49
- | CPI-U less food and energy (core) | `CUSR0000SA0L1E` | `CUUR0000SA0L1E` |
50
- | CPI-U food / energy / shelter / gasoline | | `CUUR0000SAF1` / `CUUR0000SA0E` / `CUUR0000SAH1` / `CUUR0000SETB01` |
51
- | CPI-W, chained CPI-U (C-CPI-U is revised for 10 to 12 months: "Interim") | | `CWUR0000SA0`, `SUUR0000SA0` |
52
- | CPI-U, Los Angeles area | | `CUURS49ASA0` |
53
- | CPI-U, metro areas | | see the area table below |
54
- | PPI final demand | `WPSFD4` | `WPUFD4` |
55
- | Job openings (thousands) / rate | `JTS000000000000000JOL` / `JTS000000000000000JOR` | |
56
- | Hires rate / quits rate | `JTS000000000000000HIR` / `JTS000000000000000QUR` | |
57
- | State unemployment rate (California) | `LASST060000000000003` | `LAUST060000000000003` |
58
- | ECI, total compensation, civilian: index / 12-month change | `CIS1010000000000I` | `CIU1010000000000A` |
59
- | Nonfarm business labor productivity / unit labor costs | `PRS85006092` / `PRS85006112` | |
60
- | Median usual weekly earnings, full-time (current / 1982-84 dollars) | `LES1252881500` / `LES1252881600` (the news release headline) | `LEU0252881500` / `LEU0252881600` |
61
- | OEWS, all occupations, U.S., annual mean wage | | `OEUN000000000000000000004` (annual, latest year only) |
62
-
63
- State codes in LA and SM IDs are FIPS codes (`06` California, `36` New York, `48` Texas ...). For other
64
- states, change the two digits and confirm with the `request_schema` search `describe <ID>`.
65
-
66
- ## 3. Finding an ID you do not know
67
- 1. Build it from the structure in §1 and confirm it with the `request_schema` search `describe <ID>`, or build it
68
- with a spec `build` entry (§4): a missing title means
69
- the ID does not exist (not for OEWS: data.bls.gov has no catalog page for OE IDs, so the search decodes
70
- them from their layout and says so; a wrong OEWS ID shows up as a series with no data at fetch time).
71
- 2. Search tools for the user or the browser: https://data.bls.gov/dataQuery/find (keyword search),
72
- https://beta.bls.gov/dataQuery/search, the survey's "Databases, Tables & Calculators" page, or the
73
- series list behind each table in a BLS news release.
74
- 3. Never guess an ID from memory and download it without reading its title; never report a number from a series
75
- whose title you have not read.
76
-
77
- ## 4. ID builders (`"build"` in the spec; the `request_schema` search `build {json}` previews the IDs)
78
- Every
79
- pattern below returned data from the API on 2026-10-20 for Maryland / Baltimore County / SOC 15-1252.
80
-
81
- | Builder | Arguments | ID pattern | Example |
82
- |---|---|---|---|
83
- | `laus` (state) | `state` (MD, 24, Maryland), `measure`, `seasonal` S/U | `LA` + S/U + `ST` + FIPS + 11 zeros + measure | `LASST240000000000003` |
84
- | `laus` (county) | `county` (5-digit FIPS), `measure` | `LAUCN` + FIPS + 8 zeros + measure (NSA only) | `LAUCN240050000000003` |
85
- | `ces_state` | `state`, `industry` (8 digits), `datatype` (01 employment), `seasonal` | `SM` + S/U + FIPS + `00000` + industry + datatype | `SMS24000000000000001` |
86
- | `state` | `state` | LAUS rate, employment, labor force (SA) + CES total nonfarm | 4 IDs |
87
- | `oews` | `occupation` (SOC `15-1252`), `measure`, `state` (optional) | `OEU` + `N0000000` or `S`+FIPS+`00000` + `000000` + SOC + datatype | `OEUN000000000000015125213` |
88
- | `jolts` | `industry` (code, name, comma list or `all`), `measure`, `rate` (default true), `seasonal` | `JT` + S/U + industry + `000000000` + element + `R`/`L` | `JTS720000000000000QUR` |
89
-
90
- LAUS measures: `unemployment_rate` 03, `unemployment` 04, `employment` 05, `labor_force` 06. OEWS
91
- measures: `employment` 01, `hourly_mean_wage` 03, `annual_mean_wage` 04, `hourly_median_wage` 08,
92
- `annual_10th_percentile_wage` 11, `annual_median_wage` 13, `annual_90th_percentile_wage` 15.
93
- JOLTS measures: `job_openings` JO, `hires` HI, `total_separations` TS, `quits` QU, `layoffs` LD,
94
- `other_separations` OS. JOLTS industry codes (national; the irregular ones end in 099): 000000 total
95
- nonfarm, 100000 total private, 110099 mining and logging, 230000 construction, 300000 manufacturing
96
- (320000 durable, 340000 nondurable), 400000 trade, transportation and utilities (420000 wholesale, 440000
97
- retail, 480099 transportation, warehousing and utilities), 510000 information, 510099 financial activities
98
- (520000 finance and insurance, 530000 real estate), 540099 professional and business services, 600000
99
- private education and health (610000 educational services, 620000 health care and social assistance),
100
- 700000 leisure and hospitality (710000 arts, 720000 accommodation and food), 810000 other services, 900000
101
- government (910000 federal, 920000 state and local, 923000 state and local education, 929000 state and local
102
- excluding education). All 28 quits-rate IDs were read back from data.bls.gov on 2026-10-21. OEWS is
103
- annual (period `A01`) and the API returns only the latest survey year (2025 on 2026-10-20: SOC 15-1252
104
- annual median wage $135,980 U.S., $138,680 Maryland); a request for the current year adds a "No Data
105
- Available" message, not an error. County LAUS lags the state data by a month.
106
-
107
- Common ID mix-ups (titles checked on data.bls.gov on 2026-10-20): U-6 is `LNS13327709`;
108
- `LNS13023621` is "(Seas) Unemployment Level - Job Losers" (thousands). `WPUFD4` is PPI final demand (not
109
- "finished goods"); `WPUFD49104` is final demand less foods and energy (not "finished consumer foods");
110
- `CES6562000003` covers health care and social assistance. Prefix `EI` is not the Employment Cost
111
- Index; `EI` is import/export prices and the ECI is `CI`.
112
-
113
- ## Union membership (CPS annual averages, `LU`)
114
- `LUU0204899600` is the union membership rate (percent of employed wage and salary workers), United States;
115
- the last two digits are the state FIPS code (`LUU0204899615` Hawaii, `LUU0204899646` South Dakota).
116
- Annual only (period A01); BLS publishes no state standard errors, and 2025 values are 11-month averages
117
- (October 2025 not collected). BLS's Union Members news release, Table 5, lists every state.
118
-
119
- ## Metro-area CPI-U (all items, NSA; IDs checked 2026-10-22)
120
- Only New York, Chicago and Los Angeles are priced monthly; the others every other month (odd months: Jan,
121
- Mar ...; even months: Feb, Apr ...), so "the latest" month differs by area and the off months come back
122
- empty (`n_missing`/`absent_periods` count them). Compare 12-month changes at each area's own latest month
123
- (match each month to the same month a year earlier by date, not by row) and say which month each is. BLS's news release Table 4 lists them all.
124
-
125
- | Series | Area | Priced |
126
- |---|---|---|
127
- | `CUURS11ASA0` | Boston-Cambridge-Newton | odd |
128
- | `CUURS12ASA0` | New York-Newark-Jersey City | monthly |
129
- | `CUURS12BSA0` | Philadelphia-Camden-Wilmington | even |
130
- | `CUURS23ASA0` | Chicago-Naperville-Elgin | monthly |
131
- | `CUURS23BSA0` | Detroit-Warren-Dearborn | even |
132
- | `CUURS24ASA0` | Minneapolis-St. Paul-Bloomington | odd |
133
- | `CUURS24BSA0` | St. Louis | even |
134
- | `CUURS35ASA0` | Washington-Arlington-Alexandria | odd |
135
- | `CUURS35BSA0` | Miami-Fort Lauderdale-West Palm Beach | even |
136
- | `CUURS35CSA0` | Atlanta-Sandy Springs-Roswell | even |
137
- | `CUURS35DSA0` | Tampa-St. Petersburg-Clearwater | odd |
138
- | `CUURS35ESA0` | Baltimore-Columbia-Towson | even |
139
- | `CUURS37ASA0` | Dallas-Fort Worth-Arlington | odd |
140
- | `CUURS37BSA0` | Houston-The Woodlands-Sugar Land | even |
141
- | `CUURS48ASA0` | Phoenix-Mesa-Scottsdale | even |
142
- | `CUURS48BSA0` | Denver-Aurora-Lakewood | odd |
143
- | `CUURS49ASA0` | Los Angeles-Long Beach-Anaheim | monthly |
144
- | `CUURS49BSA0` | San Francisco-Oakland-Hayward | even |
145
- | `CUURS49CSA0` | Riverside-San Bernardino-Ontario | odd |
146
- | `CUURS49DSA0` | Seattle-Tacoma-Bellevue | even |
147
- | `CUURS49ESA0` | San Diego-Carlsbad | odd |
148
- | `CUURS49FSA0` | Urban Hawaii | odd |
149
- | `CUURS49GSA0` | Urban Alaska | even |
1
+ # Series IDs
2
+
3
+ A wrong series ID is the most common silent error: the number exists, it is just not the number the
4
+ user asked about. Before downloading, call `request_schema` for bls with the search `describe <ID> ...` and read
5
+ the title, the seasonal adjustment and the dimensions back against the request.
6
+
7
+ Contents: 1. How IDs are built · 2. Verified common series · 3. Finding an ID you do not know · 4. ID builders
8
+
9
+ ## 1. How IDs are built
10
+ The first two letters name the survey; for most surveys the third is **S** (seasonally adjusted) or
11
+ **U** (not seasonally adjusted). Full formats: https://www.bls.gov/help/hlpforma.htm.
12
+
13
+ | Prefix | Survey | Structure (after the prefix and S/U) |
14
+ |---|---|---|
15
+ | LN | Current Population Survey (household survey) | 8-digit series code, e.g. `LNS14000000` |
16
+ | CE | Current Employment Statistics (payroll survey), national | 8-digit industry + 2-digit data type (`01` employment, thousands; `02` avg weekly hours; `03` avg hourly earnings; `08` AHE production and nonsupervisory; `11` avg weekly earnings; `13` real AHE, 1982-84 dollars (CPI-U); `32` real AHE of production and nonsupervisory employees (CPI-W)) |
17
+ | SM | CES state and metro | 2-digit state FIPS + 5-digit area + 8-digit industry + 2-digit data type |
18
+ | CU / CW / SU | CPI-U / CPI-W / chained CPI-U | `R` (monthly) or `S` (semiannual) + 4-char area (`0000` U.S. city average, `S49A` Los Angeles ...) + item (`SA0` all items, `SA0L1E` less food and energy, `SAF1` food, `SAF11` food at home, `SEFV` food away from home, `SA0E` energy, `SAH1` shelter, `SEHA` rent, `SEHC` owners' equivalent rent, `SETB01` gasoline, `SAM` medical care, `SAM2` medical care services, `SETE` motor vehicle insurance, `SETA02` used cars and trucks, `SAS` services) |
19
+ | WP / PC | PPI commodities and final demand / industries | `WPSFD4` final demand SA, `WPUFD4` NSA |
20
+ | JT | JOLTS | 6-digit industry + 2-digit state + 5-digit area + 2-char size class + 2-char element (`JO` openings, `HI` hires, `QU` quits, `TS` total separations, `LD` layoffs) + `L` level (thousands) or `R` rate |
21
+ | LA | Local Area Unemployment Statistics | 2-char area type (`ST` state, `MT` metro, `CN` county) + 13-digit area code + 2-digit measure (`03` rate, `04` unemployed, `05` employed, `06` labor force) |
22
+ | EN | QCEW | `U` + area (5) + data type (1) + size (1) + ownership (1) + industry code as written, not padded (`10` = all industries, or the NAICS code): `ENU2403110110` = Montgomery County MD, federal government employment [checked 2026-10-22] |
23
+ | OE | OEWS (annual, period A01) | area type + area + industry + occupation (SOC) + data type |
24
+ | CI | Employment Cost Index (quarterly) | `CI` + S/U + owner (`1` civilian, `2` private industry, `3` state and local government) + `0` + component (`1` total compensation, `2` wages and salaries, `3` benefits) + `0000000000` + `I` index or `A` 12-month percent change (NSA; BLS's headline 12-month changes): `CIU2020000000000A` private wages and salaries, `CIU3020000000000A` state and local (titles read back from data.bls.gov on 2026-10-21) |
25
+ | PR | Productivity and costs (quarterly) | `PRS85006092` nonfarm business labor productivity, percent change at annual rate; `PRS85006112` unit labor costs; indexes 2017=100 (for growth since a date): `PRS85006093` productivity, `PRS85006103` hourly compensation, `PRS85006153` real hourly compensation, `PRS85006173` labor share, `PRS85006143` output price deflator |
26
+ | LE | CPS usual weekly earnings (quarterly) | `LEU0252881500` median weekly earnings, full-time wage and salary workers |
27
+
28
+ ## 2. Verified common series ✔ (returned data on 2026-10-19; labels checked against the BLS series titles on 2026-10-21)
29
+ | Measure | SA | NSA / other |
30
+ |---|---|---|
31
+ | Unemployment rate (U-3), 16+ | `LNS14000000` | `LNU04000000` |
32
+ | U-6 rate | `LNS13327709` | |
33
+ | Labor force participation rate | `LNS11300000` | |
34
+ | Employment-population ratio | `LNS12300000` | |
35
+ | Participation rate, ages 25 to 54 | `LNS11300060` | |
36
+ | Employment-population ratio, ages 25 to 54 (total; men `LNS12300061`, women `LNS12300062`) | `LNS12300060` | |
37
+ | Employed / unemployed, levels (thousands) | `LNS12000000` / `LNS13000000` | |
38
+ | Unemployment rate: men 16+, women 16+ | `LNS14000001`, `LNS14000002` | |
39
+ | Unemployment rate: White, Black, Hispanic, Asian | `LNS14000003`, `LNS14000006` (from 1972), `LNS14000009` (from 1973), `LNS14032183` (from 2000) | `LNU04000003`, `LNU04000006`, `LNU04000009`, `LNU04032183` |
40
+ | Unemployment rate, ages 16 to 24 / 16 to 19 / 20 to 24 | `LNS14024887` / `LNS14000012` / `LNS14000036` | `LNU04024887` (16 to 24) |
41
+ | Unemployment rate by education, 25 and over: less than high school / high school, no college / some college or associate / bachelor's and higher | `LNS14027659` / `LNS14027660` / `LNS14027689` / `LNS14027662` (from 1992) | `LNU04027659` ... (same suffixes) |
42
+ | Total nonfarm payrolls (thousands) | `CES0000000001` | `CEU0000000001` |
43
+ | Total private / government / manufacturing payrolls | `CES0500000001` / `CES9000000001` / `CES3000000001` | |
44
+ | Average hourly earnings, all private employees | `CES0500000003` | |
45
+ | AHE, production and nonsupervisory | `CES0500000008` | |
46
+ | Real AHE (1982-84 dollars) | `CES0500000013` | |
47
+ | Average weekly hours, private | `CES0500000002` | |
48
+ | CPI-U all items (1982-84=100) | `CUSR0000SA0` | `CUUR0000SA0` |
49
+ | CPI-U less food and energy (core) | `CUSR0000SA0L1E` | `CUUR0000SA0L1E` |
50
+ | CPI-U food / energy / shelter / gasoline | | `CUUR0000SAF1` / `CUUR0000SA0E` / `CUUR0000SAH1` / `CUUR0000SETB01` |
51
+ | CPI-W, chained CPI-U (C-CPI-U is revised for 10 to 12 months: "Interim") | | `CWUR0000SA0`, `SUUR0000SA0` |
52
+ | CPI-U, Los Angeles area | | `CUURS49ASA0` |
53
+ | CPI-U, metro areas | | see the area table below |
54
+ | PPI final demand | `WPSFD4` | `WPUFD4` |
55
+ | Job openings (thousands) / rate | `JTS000000000000000JOL` / `JTS000000000000000JOR` | |
56
+ | Hires rate / quits rate | `JTS000000000000000HIR` / `JTS000000000000000QUR` | |
57
+ | State unemployment rate (California) | `LASST060000000000003` | `LAUST060000000000003` |
58
+ | ECI, total compensation, civilian: index / 12-month change | `CIS1010000000000I` | `CIU1010000000000A` |
59
+ | Nonfarm business labor productivity / unit labor costs | `PRS85006092` / `PRS85006112` | |
60
+ | Median usual weekly earnings, full-time (current / 1982-84 dollars) | `LES1252881500` / `LES1252881600` (the news release headline) | `LEU0252881500` / `LEU0252881600` |
61
+ | OEWS, all occupations, U.S., annual mean wage | | `OEUN000000000000000000004` (annual, latest year only) |
62
+
63
+ State codes in LA and SM IDs are FIPS codes (`06` California, `36` New York, `48` Texas ...). For other
64
+ states, change the two digits and confirm with the `request_schema` search `describe <ID>`.
65
+
66
+ ## 3. Finding an ID you do not know
67
+ 1. Build it from the structure in §1 and confirm it with the `request_schema` search `describe <ID>`, or build it
68
+ with a spec `build` entry (§4): a missing title means
69
+ the ID does not exist (not for OEWS: data.bls.gov has no catalog page for OE IDs, so the search decodes
70
+ them from their layout and says so; a wrong OEWS ID shows up as a series with no data at fetch time).
71
+ 2. Search tools for the user or the browser: https://data.bls.gov/dataQuery/find (keyword search),
72
+ https://beta.bls.gov/dataQuery/search, the survey's "Databases, Tables & Calculators" page, or the
73
+ series list behind each table in a BLS news release.
74
+ 3. Never guess an ID from memory and download it without reading its title; never report a number from a series
75
+ whose title you have not read.
76
+
77
+ ## 4. ID builders (`"build"` in the spec; the `request_schema` search `build {json}` previews the IDs)
78
+ Every
79
+ pattern below returned data from the API on 2026-10-20 for Maryland / Baltimore County / SOC 15-1252.
80
+
81
+ | Builder | Arguments | ID pattern | Example |
82
+ |---|---|---|---|
83
+ | `laus` (state) | `state` (MD, 24, Maryland), `measure`, `seasonal` S/U | `LA` + S/U + `ST` + FIPS + 11 zeros + measure | `LASST240000000000003` |
84
+ | `laus` (county) | `county` (5-digit FIPS), `measure` | `LAUCN` + FIPS + 8 zeros + measure (NSA only) | `LAUCN240050000000003` |
85
+ | `ces_state` | `state`, `industry` (8 digits), `datatype` (01 employment), `seasonal` | `SM` + S/U + FIPS + `00000` + industry + datatype | `SMS24000000000000001` |
86
+ | `state` | `state` | LAUS rate, employment, labor force (SA) + CES total nonfarm | 4 IDs |
87
+ | `oews` | `occupation` (SOC `15-1252`), `measure`, `state` (optional) | `OEU` + `N0000000` or `S`+FIPS+`00000` + `000000` + SOC + datatype | `OEUN000000000000015125213` |
88
+ | `jolts` | `industry` (code, name, comma list or `all`), `measure`, `rate` (default true), `seasonal` | `JT` + S/U + industry + `000000000` + element + `R`/`L` | `JTS720000000000000QUR` |
89
+
90
+ LAUS measures: `unemployment_rate` 03, `unemployment` 04, `employment` 05, `labor_force` 06. OEWS
91
+ measures: `employment` 01, `hourly_mean_wage` 03, `annual_mean_wage` 04, `hourly_median_wage` 08,
92
+ `annual_10th_percentile_wage` 11, `annual_median_wage` 13, `annual_90th_percentile_wage` 15.
93
+ JOLTS measures: `job_openings` JO, `hires` HI, `total_separations` TS, `quits` QU, `layoffs` LD,
94
+ `other_separations` OS. JOLTS industry codes (national; the irregular ones end in 099): 000000 total
95
+ nonfarm, 100000 total private, 110099 mining and logging, 230000 construction, 300000 manufacturing
96
+ (320000 durable, 340000 nondurable), 400000 trade, transportation and utilities (420000 wholesale, 440000
97
+ retail, 480099 transportation, warehousing and utilities), 510000 information, 510099 financial activities
98
+ (520000 finance and insurance, 530000 real estate), 540099 professional and business services, 600000
99
+ private education and health (610000 educational services, 620000 health care and social assistance),
100
+ 700000 leisure and hospitality (710000 arts, 720000 accommodation and food), 810000 other services, 900000
101
+ government (910000 federal, 920000 state and local, 923000 state and local education, 929000 state and local
102
+ excluding education). All 28 quits-rate IDs were read back from data.bls.gov on 2026-10-21. OEWS is
103
+ annual (period `A01`) and the API returns only the latest survey year (2025 on 2026-10-20: SOC 15-1252
104
+ annual median wage $135,980 U.S., $138,680 Maryland); a request for the current year adds a "No Data
105
+ Available" message, not an error. County LAUS lags the state data by a month.
106
+
107
+ Common ID mix-ups (titles checked on data.bls.gov on 2026-10-20): U-6 is `LNS13327709`;
108
+ `LNS13023621` is "(Seas) Unemployment Level - Job Losers" (thousands). `WPUFD4` is PPI final demand (not
109
+ "finished goods"); `WPUFD49104` is final demand less foods and energy (not "finished consumer foods");
110
+ `CES6562000003` covers health care and social assistance. Prefix `EI` is not the Employment Cost
111
+ Index; `EI` is import/export prices and the ECI is `CI`.
112
+
113
+ ## Union membership (CPS annual averages, `LU`)
114
+ `LUU0204899600` is the union membership rate (percent of employed wage and salary workers), United States;
115
+ the last two digits are the state FIPS code (`LUU0204899615` Hawaii, `LUU0204899646` South Dakota).
116
+ Annual only (period A01); BLS publishes no state standard errors, and 2025 values are 11-month averages
117
+ (October 2025 not collected). BLS's Union Members news release, Table 5, lists every state.
118
+
119
+ ## Metro-area CPI-U (all items, NSA; IDs checked 2026-10-22)
120
+ Only New York, Chicago and Los Angeles are priced monthly; the others every other month (odd months: Jan,
121
+ Mar ...; even months: Feb, Apr ...), so "the latest" month differs by area and the off months come back
122
+ empty (`n_missing`/`absent_periods` count them). Compare 12-month changes at each area's own latest month
123
+ (match each month to the same month a year earlier by date, not by row) and say which month each is. BLS's news release Table 4 lists them all.
124
+
125
+ | Series | Area | Priced |
126
+ |---|---|---|
127
+ | `CUURS11ASA0` | Boston-Cambridge-Newton | odd |
128
+ | `CUURS12ASA0` | New York-Newark-Jersey City | monthly |
129
+ | `CUURS12BSA0` | Philadelphia-Camden-Wilmington | even |
130
+ | `CUURS23ASA0` | Chicago-Naperville-Elgin | monthly |
131
+ | `CUURS23BSA0` | Detroit-Warren-Dearborn | even |
132
+ | `CUURS24ASA0` | Minneapolis-St. Paul-Bloomington | odd |
133
+ | `CUURS24BSA0` | St. Louis | even |
134
+ | `CUURS35ASA0` | Washington-Arlington-Alexandria | odd |
135
+ | `CUURS35BSA0` | Miami-Fort Lauderdale-West Palm Beach | even |
136
+ | `CUURS35CSA0` | Atlanta-Sandy Springs-Roswell | even |
137
+ | `CUURS35DSA0` | Tampa-St. Petersburg-Clearwater | odd |
138
+ | `CUURS35ESA0` | Baltimore-Columbia-Towson | even |
139
+ | `CUURS37ASA0` | Dallas-Fort Worth-Arlington | odd |
140
+ | `CUURS37BSA0` | Houston-The Woodlands-Sugar Land | even |
141
+ | `CUURS48ASA0` | Phoenix-Mesa-Scottsdale | even |
142
+ | `CUURS48BSA0` | Denver-Aurora-Lakewood | odd |
143
+ | `CUURS49ASA0` | Los Angeles-Long Beach-Anaheim | monthly |
144
+ | `CUURS49BSA0` | San Francisco-Oakland-Hayward | even |
145
+ | `CUURS49CSA0` | Riverside-San Bernardino-Ontario | odd |
146
+ | `CUURS49DSA0` | Seattle-Tacoma-Bellevue | even |
147
+ | `CUURS49ESA0` | San Diego-Carlsbad | odd |
148
+ | `CUURS49FSA0` | Urban Hawaii | odd |
149
+ | `CUURS49GSA0` | Urban Alaska | even |