data-analyst-mcp 0.0.0-stage → 0.3.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 (640) hide show
  1. package/README.md +262 -3
  2. package/dist/adapters/_acf_tidy.d.ts +18 -0
  3. package/dist/adapters/_acf_tidy.js +432 -0
  4. package/dist/adapters/_acf_tidy.js.map +1 -0
  5. package/dist/adapters/_actuaries_read.d.ts +38 -0
  6. package/dist/adapters/_actuaries_read.js +728 -0
  7. package/dist/adapters/_actuaries_read.js.map +1 -0
  8. package/dist/adapters/_census_micro.d.ts +70 -0
  9. package/dist/adapters/_census_micro.js +622 -0
  10. package/dist/adapters/_census_micro.js.map +1 -0
  11. package/dist/adapters/_census_util.d.ts +40 -0
  12. package/dist/adapters/_census_util.js +275 -0
  13. package/dist/adapters/_census_util.js.map +1 -0
  14. package/dist/adapters/_dol_states.d.ts +6 -0
  15. package/dist/adapters/_dol_states.js +58 -0
  16. package/dist/adapters/_dol_states.js.map +1 -0
  17. package/dist/adapters/_govinfo_entities.d.ts +4 -0
  18. package/dist/adapters/_govinfo_entities.js +6 -0
  19. package/dist/adapters/_govinfo_entities.js.map +1 -0
  20. package/dist/adapters/_govinfo_json.d.ts +13 -0
  21. package/dist/adapters/_govinfo_json.js +107 -0
  22. package/dist/adapters/_govinfo_json.js.map +1 -0
  23. package/dist/adapters/_govinfo_py.d.ts +22 -0
  24. package/dist/adapters/_govinfo_py.js +272 -0
  25. package/dist/adapters/_govinfo_py.js.map +1 -0
  26. package/dist/adapters/_govinfo_xml.d.ts +22 -0
  27. package/dist/adapters/_govinfo_xml.js +233 -0
  28. package/dist/adapters/_govinfo_xml.js.map +1 -0
  29. package/dist/adapters/_hud_excel.d.ts +2 -0
  30. package/dist/adapters/_hud_excel.js +166 -0
  31. package/dist/adapters/_hud_excel.js.map +1 -0
  32. package/dist/adapters/_omb_grid.d.ts +17 -0
  33. package/dist/adapters/_omb_grid.js +132 -0
  34. package/dist/adapters/_omb_grid.js.map +1 -0
  35. package/dist/adapters/_omb_util.d.ts +40 -0
  36. package/dist/adapters/_omb_util.js +192 -0
  37. package/dist/adapters/_omb_util.js.map +1 -0
  38. package/dist/adapters/_usaspending_state.d.ts +6 -0
  39. package/dist/adapters/_usaspending_state.js +54 -0
  40. package/dist/adapters/_usaspending_state.js.map +1 -0
  41. package/dist/adapters/_usda-fna_book.d.ts +59 -0
  42. package/dist/adapters/_usda-fna_book.js +869 -0
  43. package/dist/adapters/_usda-fna_book.js.map +1 -0
  44. package/dist/adapters/_usda-fna_pdf.d.ts +20 -0
  45. package/dist/adapters/_usda-fna_pdf.js +361 -0
  46. package/dist/adapters/_usda-fna_pdf.js.map +1 -0
  47. package/dist/adapters/_usda-outlook_read.d.ts +70 -0
  48. package/dist/adapters/_usda-outlook_read.js +362 -0
  49. package/dist/adapters/_usda-outlook_read.js.map +1 -0
  50. package/dist/adapters/acf.d.ts +3 -0
  51. package/dist/adapters/acf.js +187 -0
  52. package/dist/adapters/acf.js.map +1 -0
  53. package/dist/adapters/actuaries.d.ts +3 -0
  54. package/dist/adapters/actuaries.js +293 -0
  55. package/dist/adapters/actuaries.js.map +1 -0
  56. package/dist/adapters/bts.d.ts +3 -0
  57. package/dist/adapters/bts.js +26 -0
  58. package/dist/adapters/bts.js.map +1 -0
  59. package/dist/adapters/census-geocoder.d.ts +10 -0
  60. package/dist/adapters/census-geocoder.js +47 -0
  61. package/dist/adapters/census-geocoder.js.map +1 -0
  62. package/dist/adapters/census.d.ts +17 -0
  63. package/dist/adapters/census.js +983 -0
  64. package/dist/adapters/census.js.map +1 -0
  65. package/dist/adapters/cfpb.d.ts +7 -0
  66. package/dist/adapters/cfpb.js +348 -0
  67. package/dist/adapters/cfpb.js.map +1 -0
  68. package/dist/adapters/clinical-trials.d.ts +3 -0
  69. package/dist/adapters/clinical-trials.js +135 -0
  70. package/dist/adapters/clinical-trials.js.map +1 -0
  71. package/dist/adapters/cms.d.ts +3 -0
  72. package/dist/adapters/cms.js +292 -0
  73. package/dist/adapters/cms.js.map +1 -0
  74. package/dist/adapters/college-scorecard.d.ts +3 -0
  75. package/dist/adapters/college-scorecard.js +122 -0
  76. package/dist/adapters/college-scorecard.js.map +1 -0
  77. package/dist/adapters/congress.d.ts +33 -0
  78. package/dist/adapters/congress.js +589 -0
  79. package/dist/adapters/congress.js.map +1 -0
  80. package/dist/adapters/dhs-ohss.d.ts +13 -0
  81. package/dist/adapters/dhs-ohss.js +598 -0
  82. package/dist/adapters/dhs-ohss.js.map +1 -0
  83. package/dist/adapters/doj-news.d.ts +7 -0
  84. package/dist/adapters/doj-news.js +286 -0
  85. package/dist/adapters/doj-news.js.map +1 -0
  86. package/dist/adapters/dol.d.ts +4 -0
  87. package/dist/adapters/dol.js +634 -0
  88. package/dist/adapters/dol.js.map +1 -0
  89. package/dist/adapters/eia.d.ts +15 -0
  90. package/dist/adapters/eia.js +456 -0
  91. package/dist/adapters/eia.js.map +1 -0
  92. package/dist/adapters/epa-aqs.d.ts +3 -0
  93. package/dist/adapters/epa-aqs.js +357 -0
  94. package/dist/adapters/epa-aqs.js.map +1 -0
  95. package/dist/adapters/epa.d.ts +3 -0
  96. package/dist/adapters/epa.js +298 -0
  97. package/dist/adapters/epa.js.map +1 -0
  98. package/dist/adapters/fbi.d.ts +3 -0
  99. package/dist/adapters/fbi.js +192 -0
  100. package/dist/adapters/fbi.js.map +1 -0
  101. package/dist/adapters/fda.d.ts +5 -0
  102. package/dist/adapters/fda.js +184 -0
  103. package/dist/adapters/fda.js.map +1 -0
  104. package/dist/adapters/fdic.d.ts +4 -0
  105. package/dist/adapters/fdic.js +95 -0
  106. package/dist/adapters/fdic.js.map +1 -0
  107. package/dist/adapters/fec.d.ts +3 -0
  108. package/dist/adapters/fec.js +142 -0
  109. package/dist/adapters/fec.js.map +1 -0
  110. package/dist/adapters/fed-board.d.ts +12 -0
  111. package/dist/adapters/fed-board.js +581 -0
  112. package/dist/adapters/fed-board.js.map +1 -0
  113. package/dist/adapters/federal-register.d.ts +11 -0
  114. package/dist/adapters/federal-register.js +43 -0
  115. package/dist/adapters/federal-register.js.map +1 -0
  116. package/dist/adapters/fhfa.d.ts +3 -0
  117. package/dist/adapters/fhfa.js +253 -0
  118. package/dist/adapters/fhfa.js.map +1 -0
  119. package/dist/adapters/fsa.d.ts +9 -0
  120. package/dist/adapters/fsa.js +335 -0
  121. package/dist/adapters/fsa.js.map +1 -0
  122. package/dist/adapters/govinfo.d.ts +30 -0
  123. package/dist/adapters/govinfo.js +636 -0
  124. package/dist/adapters/govinfo.js.map +1 -0
  125. package/dist/adapters/gsa-calc.d.ts +10 -0
  126. package/dist/adapters/gsa-calc.js +318 -0
  127. package/dist/adapters/gsa-calc.js.map +1 -0
  128. package/dist/adapters/hud.d.ts +3 -0
  129. package/dist/adapters/hud.js +200 -0
  130. package/dist/adapters/hud.js.map +1 -0
  131. package/dist/adapters/index.d.ts +3 -0
  132. package/dist/adapters/index.js +25 -0
  133. package/dist/adapters/index.js.map +1 -0
  134. package/dist/adapters/irs-soi.d.ts +6 -0
  135. package/dist/adapters/irs-soi.js +576 -0
  136. package/dist/adapters/irs-soi.js.map +1 -0
  137. package/dist/adapters/naep.d.ts +15 -0
  138. package/dist/adapters/naep.js +341 -0
  139. package/dist/adapters/naep.js.map +1 -0
  140. package/dist/adapters/nhtsa.d.ts +10 -0
  141. package/dist/adapters/nhtsa.js +239 -0
  142. package/dist/adapters/nhtsa.js.map +1 -0
  143. package/dist/adapters/nih.d.ts +5 -0
  144. package/dist/adapters/nih.js +196 -0
  145. package/dist/adapters/nih.js.map +1 -0
  146. package/dist/adapters/noaa.d.ts +3 -0
  147. package/dist/adapters/noaa.js +148 -0
  148. package/dist/adapters/noaa.js.map +1 -0
  149. package/dist/adapters/nrel.d.ts +3 -0
  150. package/dist/adapters/nrel.js +186 -0
  151. package/dist/adapters/nrel.js.map +1 -0
  152. package/dist/adapters/nws.d.ts +3 -0
  153. package/dist/adapters/nws.js +119 -0
  154. package/dist/adapters/nws.js.map +1 -0
  155. package/dist/adapters/omb.d.ts +15 -0
  156. package/dist/adapters/omb.js +517 -0
  157. package/dist/adapters/omb.js.map +1 -0
  158. package/dist/adapters/open-payments.d.ts +5 -0
  159. package/dist/adapters/open-payments.js +149 -0
  160. package/dist/adapters/open-payments.js.map +1 -0
  161. package/dist/adapters/pbgc.d.ts +13 -0
  162. package/dist/adapters/pbgc.js +283 -0
  163. package/dist/adapters/pbgc.js.map +1 -0
  164. package/dist/adapters/philfed.d.ts +12 -0
  165. package/dist/adapters/philfed.js +59 -0
  166. package/dist/adapters/philfed.js.map +1 -0
  167. package/dist/adapters/regulations.d.ts +6 -0
  168. package/dist/adapters/regulations.js +58 -0
  169. package/dist/adapters/regulations.js.map +1 -0
  170. package/dist/adapters/sec.d.ts +13 -0
  171. package/dist/adapters/sec.js +504 -0
  172. package/dist/adapters/sec.js.map +1 -0
  173. package/dist/adapters/senate-lobbying.d.ts +3 -0
  174. package/dist/adapters/senate-lobbying.js +181 -0
  175. package/dist/adapters/senate-lobbying.js.map +1 -0
  176. package/dist/adapters/snapqc.d.ts +32 -0
  177. package/dist/adapters/snapqc.js +701 -0
  178. package/dist/adapters/snapqc.js.map +1 -0
  179. package/dist/adapters/treasury-yields.d.ts +3 -0
  180. package/dist/adapters/treasury-yields.js +170 -0
  181. package/dist/adapters/treasury-yields.js.map +1 -0
  182. package/dist/adapters/usaspending.d.ts +3 -0
  183. package/dist/adapters/usaspending.js +340 -0
  184. package/dist/adapters/usaspending.js.map +1 -0
  185. package/dist/adapters/usda-fna.d.ts +7 -0
  186. package/dist/adapters/usda-fna.js +707 -0
  187. package/dist/adapters/usda-fna.js.map +1 -0
  188. package/dist/adapters/usda-fooddata.d.ts +3 -0
  189. package/dist/adapters/usda-fooddata.js +101 -0
  190. package/dist/adapters/usda-fooddata.js.map +1 -0
  191. package/dist/adapters/usda-nass.d.ts +3 -0
  192. package/dist/adapters/usda-nass.js +108 -0
  193. package/dist/adapters/usda-nass.js.map +1 -0
  194. package/dist/adapters/usda-outlook.d.ts +12 -0
  195. package/dist/adapters/usda-outlook.js +696 -0
  196. package/dist/adapters/usda-outlook.js.map +1 -0
  197. package/dist/adapters/usgs.d.ts +9 -0
  198. package/dist/adapters/usgs.js +265 -0
  199. package/dist/adapters/usgs.js.map +1 -0
  200. package/dist/adapters/usitc.d.ts +18 -0
  201. package/dist/adapters/usitc.js +170 -0
  202. package/dist/adapters/usitc.js.map +1 -0
  203. package/dist/adapters/uspto.d.ts +3 -0
  204. package/dist/adapters/uspto.js +47 -0
  205. package/dist/adapters/uspto.js.map +1 -0
  206. package/dist/adapters/world-bank.d.ts +3 -0
  207. package/dist/adapters/world-bank.js +163 -0
  208. package/dist/adapters/world-bank.js.map +1 -0
  209. package/dist/analysis/cite.d.ts +31 -0
  210. package/dist/analysis/cite.js +229 -0
  211. package/dist/analysis/cite.js.map +1 -0
  212. package/dist/analysis/combine.d.ts +27 -0
  213. package/dist/analysis/combine.js +198 -0
  214. package/dist/analysis/combine.js.map +1 -0
  215. package/dist/analysis/compute.d.ts +62 -0
  216. package/dist/analysis/compute.js +583 -0
  217. package/dist/analysis/compute.js.map +1 -0
  218. package/dist/analysis/expr.d.ts +69 -0
  219. package/dist/analysis/expr.js +780 -0
  220. package/dist/analysis/expr.js.map +1 -0
  221. package/dist/analysis/factfmt.d.ts +16 -0
  222. package/dist/analysis/factfmt.js +187 -0
  223. package/dist/analysis/factfmt.js.map +1 -0
  224. package/dist/analysis/facts.d.ts +63 -0
  225. package/dist/analysis/facts.js +355 -0
  226. package/dist/analysis/facts.js.map +1 -0
  227. package/dist/analysis/handoff.d.ts +58 -0
  228. package/dist/analysis/handoff.js +208 -0
  229. package/dist/analysis/handoff.js.map +1 -0
  230. package/dist/analysis/pyfmt.d.ts +16 -0
  231. package/dist/analysis/pyfmt.js +156 -0
  232. package/dist/analysis/pyfmt.js.map +1 -0
  233. package/dist/analysis/rerun.d.ts +13 -0
  234. package/dist/analysis/rerun.js +125 -0
  235. package/dist/analysis/rerun.js.map +1 -0
  236. package/dist/analysis/table.d.ts +18 -0
  237. package/dist/analysis/table.js +109 -0
  238. package/dist/analysis/table.js.map +1 -0
  239. package/dist/analysis/tools.d.ts +67 -0
  240. package/dist/analysis/tools.js +217 -0
  241. package/dist/analysis/tools.js.map +1 -0
  242. package/dist/analysis/write_table.d.ts +13 -0
  243. package/dist/analysis/write_table.js +59 -0
  244. package/dist/analysis/write_table.js.map +1 -0
  245. package/dist/bin/cli.d.ts +10 -0
  246. package/dist/bin/cli.js +177 -0
  247. package/dist/bin/cli.js.map +1 -0
  248. package/dist/core/cache.d.ts +14 -0
  249. package/dist/core/cache.js +90 -0
  250. package/dist/core/cache.js.map +1 -0
  251. package/dist/core/context.d.ts +12 -0
  252. package/dist/core/context.js +15 -0
  253. package/dist/core/context.js.map +1 -0
  254. package/dist/core/env.d.ts +14 -0
  255. package/dist/core/env.js +52 -0
  256. package/dist/core/env.js.map +1 -0
  257. package/dist/core/generic-rest.d.ts +61 -0
  258. package/dist/core/generic-rest.js +639 -0
  259. package/dist/core/generic-rest.js.map +1 -0
  260. package/dist/core/http.d.ts +120 -0
  261. package/dist/core/http.js +514 -0
  262. package/dist/core/http.js.map +1 -0
  263. package/dist/core/keys.d.ts +43 -0
  264. package/dist/core/keys.js +174 -0
  265. package/dist/core/keys.js.map +1 -0
  266. package/dist/core/manual.d.ts +41 -0
  267. package/dist/core/manual.js +218 -0
  268. package/dist/core/manual.js.map +1 -0
  269. package/dist/core/package.d.ts +58 -0
  270. package/dist/core/package.js +228 -0
  271. package/dist/core/package.js.map +1 -0
  272. package/dist/core/packs.d.ts +139 -0
  273. package/dist/core/packs.js +173 -0
  274. package/dist/core/packs.js.map +1 -0
  275. package/dist/core/policy.d.ts +69 -0
  276. package/dist/core/policy.js +189 -0
  277. package/dist/core/policy.js.map +1 -0
  278. package/dist/core/py.d.ts +40 -0
  279. package/dist/core/py.js +171 -0
  280. package/dist/core/py.js.map +1 -0
  281. package/dist/core/routing.d.ts +10 -0
  282. package/dist/core/routing.js +39 -0
  283. package/dist/core/routing.js.map +1 -0
  284. package/dist/core/tabular.d.ts +21 -0
  285. package/dist/core/tabular.js +229 -0
  286. package/dist/core/tabular.js.map +1 -0
  287. package/dist/deep/_bea_api.d.ts +102 -0
  288. package/dist/deep/_bea_api.js +457 -0
  289. package/dist/deep/_bea_api.js.map +1 -0
  290. package/dist/deep/_bea_fetch.d.ts +151 -0
  291. package/dist/deep/_bea_fetch.js +1274 -0
  292. package/dist/deep/_bea_fetch.js.map +1 -0
  293. package/dist/deep/_bea_util.d.ts +14 -0
  294. package/dist/deep/_bea_util.js +156 -0
  295. package/dist/deep/_bea_util.js.map +1 -0
  296. package/dist/deep/_bls_api.d.ts +84 -0
  297. package/dist/deep/_bls_api.js +231 -0
  298. package/dist/deep/_bls_api.js.map +1 -0
  299. package/dist/deep/_bls_ids.d.ts +43 -0
  300. package/dist/deep/_bls_ids.js +188 -0
  301. package/dist/deep/_bls_ids.js.map +1 -0
  302. package/dist/deep/_bls_lib.d.ts +61 -0
  303. package/dist/deep/_bls_lib.js +442 -0
  304. package/dist/deep/_bls_lib.js.map +1 -0
  305. package/dist/deep/_fred_api.d.ts +148 -0
  306. package/dist/deep/_fred_api.js +545 -0
  307. package/dist/deep/_fred_api.js.map +1 -0
  308. package/dist/deep/_fred_pack.d.ts +162 -0
  309. package/dist/deep/_fred_pack.js +1027 -0
  310. package/dist/deep/_fred_pack.js.map +1 -0
  311. package/dist/deep/_fred_py.d.ts +40 -0
  312. package/dist/deep/_fred_py.js +199 -0
  313. package/dist/deep/_fred_py.js.map +1 -0
  314. package/dist/deep/_ipums_bundle.d.ts +29 -0
  315. package/dist/deep/_ipums_bundle.js +194 -0
  316. package/dist/deep/_ipums_bundle.js.map +1 -0
  317. package/dist/deep/_ipums_ddi.d.ts +23 -0
  318. package/dist/deep/_ipums_ddi.js +162 -0
  319. package/dist/deep/_ipums_ddi.js.map +1 -0
  320. package/dist/deep/_opm_io.d.ts +26 -0
  321. package/dist/deep/_opm_io.js +383 -0
  322. package/dist/deep/_opm_io.js.map +1 -0
  323. package/dist/deep/_opm_parquet.d.ts +31 -0
  324. package/dist/deep/_opm_parquet.js +744 -0
  325. package/dist/deep/_opm_parquet.js.map +1 -0
  326. package/dist/deep/_opm_py.d.ts +6 -0
  327. package/dist/deep/_opm_py.js +74 -0
  328. package/dist/deep/_opm_py.js.map +1 -0
  329. package/dist/deep/_treasury_api.d.ts +48 -0
  330. package/dist/deep/_treasury_api.js +221 -0
  331. package/dist/deep/_treasury_api.js.map +1 -0
  332. package/dist/deep/_treasury_context.d.ts +34 -0
  333. package/dist/deep/_treasury_context.js +142 -0
  334. package/dist/deep/_treasury_context.js.map +1 -0
  335. package/dist/deep/_treasury_lib.d.ts +109 -0
  336. package/dist/deep/_treasury_lib.js +686 -0
  337. package/dist/deep/_treasury_lib.js.map +1 -0
  338. package/dist/deep/bea.d.ts +3 -0
  339. package/dist/deep/bea.js +248 -0
  340. package/dist/deep/bea.js.map +1 -0
  341. package/dist/deep/bls.d.ts +3 -0
  342. package/dist/deep/bls.js +220 -0
  343. package/dist/deep/bls.js.map +1 -0
  344. package/dist/deep/fred.d.ts +3 -0
  345. package/dist/deep/fred.js +325 -0
  346. package/dist/deep/fred.js.map +1 -0
  347. package/dist/deep/ipums.d.ts +59 -0
  348. package/dist/deep/ipums.js +744 -0
  349. package/dist/deep/ipums.js.map +1 -0
  350. package/dist/deep/opm.d.ts +56 -0
  351. package/dist/deep/opm.js +1033 -0
  352. package/dist/deep/opm.js.map +1 -0
  353. package/dist/deep/treasury.d.ts +3 -0
  354. package/dist/deep/treasury.js +218 -0
  355. package/dist/deep/treasury.js.map +1 -0
  356. package/dist/envelope.d.ts +47 -0
  357. package/dist/envelope.js +88 -0
  358. package/dist/envelope.js.map +1 -0
  359. package/dist/index.d.ts +277 -0
  360. package/dist/index.js +106 -0
  361. package/dist/index.js.map +1 -0
  362. package/dist/remote/app.d.ts +21 -0
  363. package/dist/remote/app.js +218 -0
  364. package/dist/remote/app.js.map +1 -0
  365. package/dist/remote/oauth.d.ts +14 -0
  366. package/dist/remote/oauth.js +90 -0
  367. package/dist/remote/oauth.js.map +1 -0
  368. package/dist/remote/pages.d.ts +8 -0
  369. package/dist/remote/pages.js +56 -0
  370. package/dist/remote/pages.js.map +1 -0
  371. package/dist/remote/sign.d.ts +4 -0
  372. package/dist/remote/sign.js +40 -0
  373. package/dist/remote/sign.js.map +1 -0
  374. package/dist/remote/store.d.ts +31 -0
  375. package/dist/remote/store.js +129 -0
  376. package/dist/remote/store.js.map +1 -0
  377. package/dist/report/audit_answer.d.ts +94 -0
  378. package/dist/report/audit_answer.js +1349 -0
  379. package/dist/report/audit_answer.js.map +1 -0
  380. package/dist/report/audit_report.d.ts +23 -0
  381. package/dist/report/audit_report.js +637 -0
  382. package/dist/report/audit_report.js.map +1 -0
  383. package/dist/report/build_report.d.ts +27 -0
  384. package/dist/report/build_report.js +1168 -0
  385. package/dist/report/build_report.js.map +1 -0
  386. package/dist/report/method_audit.d.ts +47 -0
  387. package/dist/report/method_audit.js +710 -0
  388. package/dist/report/method_audit.js.map +1 -0
  389. package/dist/report/policyset.d.ts +50 -0
  390. package/dist/report/policyset.js +421 -0
  391. package/dist/report/policyset.js.map +1 -0
  392. package/dist/report/py.d.ts +58 -0
  393. package/dist/report/py.js +311 -0
  394. package/dist/report/py.js.map +1 -0
  395. package/dist/report/scan_secrets.d.ts +21 -0
  396. package/dist/report/scan_secrets.js +234 -0
  397. package/dist/report/scan_secrets.js.map +1 -0
  398. package/dist/report/style_check.d.ts +29 -0
  399. package/dist/report/style_check.js +173 -0
  400. package/dist/report/style_check.js.map +1 -0
  401. package/dist/report/tools.d.ts +87 -0
  402. package/dist/report/tools.js +167 -0
  403. package/dist/report/tools.js.map +1 -0
  404. package/dist/server.d.ts +5 -0
  405. package/dist/server.js +246 -0
  406. package/dist/server.js.map +1 -0
  407. package/dist/session.d.ts +47 -0
  408. package/dist/session.js +107 -0
  409. package/dist/session.js.map +1 -0
  410. package/dist/toolkit.d.ts +21 -0
  411. package/dist/toolkit.js +2 -0
  412. package/dist/toolkit.js.map +1 -0
  413. package/dist/tools.d.ts +299 -0
  414. package/dist/tools.js +491 -0
  415. package/dist/tools.js.map +1 -0
  416. package/guide/WORKFLOW.md +134 -0
  417. package/guide/assets/disclaimer.txt +1 -0
  418. package/guide/assets/download_data.ps1 +162 -0
  419. package/guide/assets/download_data.sh +143 -0
  420. package/guide/assets/report_template.html +597 -0
  421. package/guide/references/report_patterns.md +199 -0
  422. package/guide/references/routing.md +171 -0
  423. package/guide/references/style_guide.md +398 -0
  424. package/package.json +56 -6
  425. package/packs/acf/endpoints.json +114 -0
  426. package/packs/acf/policy.json +104 -0
  427. package/packs/acf/source.md +138 -0
  428. package/packs/actuaries/endpoints.json +82 -0
  429. package/packs/actuaries/policy.json +109 -0
  430. package/packs/actuaries/source.md +137 -0
  431. package/packs/bea/assets/download_bea.ps1 +182 -0
  432. package/packs/bea/assets/download_bea.sh +144 -0
  433. package/packs/bea/docs/bea_api.md +461 -0
  434. package/packs/bea/docs/datasets.md +157 -0
  435. package/packs/bea/docs/report_patterns.md +112 -0
  436. package/packs/bea/policy.json +170 -0
  437. package/packs/bea/source.md +152 -0
  438. package/packs/bls/assets/download_bls.ps1 +152 -0
  439. package/packs/bls/assets/download_bls.sh +167 -0
  440. package/packs/bls/docs/analysis_patterns.md +108 -0
  441. package/packs/bls/docs/bls_api.md +73 -0
  442. package/packs/bls/docs/series_ids.md +149 -0
  443. package/packs/bls/policy.json +238 -0
  444. package/packs/bls/series_ids.json +1375 -0
  445. package/packs/bls/source.md +156 -0
  446. package/packs/bts/endpoints.json +347 -0
  447. package/packs/bts/policy.json +94 -0
  448. package/packs/bts/source.md +97 -0
  449. package/packs/cdc/endpoints.json +197 -0
  450. package/packs/cdc/policy.json +83 -0
  451. package/packs/cdc/source.md +74 -0
  452. package/packs/census/endpoints.json +99 -0
  453. package/packs/census/policy.json +238 -0
  454. package/packs/census/source.md +304 -0
  455. package/packs/census-geocoder/endpoints.json +70 -0
  456. package/packs/census-geocoder/policy.json +80 -0
  457. package/packs/census-geocoder/source.md +53 -0
  458. package/packs/cfpb/endpoints.json +327 -0
  459. package/packs/cfpb/policy.json +119 -0
  460. package/packs/cfpb/source.md +96 -0
  461. package/packs/clinical-trials/endpoints.json +167 -0
  462. package/packs/clinical-trials/policy.json +84 -0
  463. package/packs/clinical-trials/source.md +82 -0
  464. package/packs/cms/endpoints.json +69 -0
  465. package/packs/cms/policy.json +96 -0
  466. package/packs/cms/source.md +112 -0
  467. package/packs/college-scorecard/endpoints.json +253 -0
  468. package/packs/college-scorecard/policy.json +106 -0
  469. package/packs/college-scorecard/source.md +92 -0
  470. package/packs/congress/endpoints.json +1701 -0
  471. package/packs/congress/policy.json +117 -0
  472. package/packs/congress/source.md +190 -0
  473. package/packs/dhs-ohss/endpoints.json +66 -0
  474. package/packs/dhs-ohss/policy.json +107 -0
  475. package/packs/dhs-ohss/source.md +120 -0
  476. package/packs/doj-news/endpoints.json +59 -0
  477. package/packs/doj-news/policy.json +96 -0
  478. package/packs/doj-news/source.md +99 -0
  479. package/packs/dol/endpoints.json +818 -0
  480. package/packs/dol/policy.json +135 -0
  481. package/packs/dol/source.md +181 -0
  482. package/packs/eia/endpoints.json +718 -0
  483. package/packs/eia/policy.json +112 -0
  484. package/packs/eia/source.md +112 -0
  485. package/packs/epa/endpoints.json +292 -0
  486. package/packs/epa/policy.json +99 -0
  487. package/packs/epa/source.md +99 -0
  488. package/packs/epa-aqs/endpoints.json +174 -0
  489. package/packs/epa-aqs/policy.json +96 -0
  490. package/packs/epa-aqs/source.md +97 -0
  491. package/packs/fbi/endpoints.json +1842 -0
  492. package/packs/fbi/policy.json +118 -0
  493. package/packs/fbi/source.md +108 -0
  494. package/packs/fda/endpoints.json +238 -0
  495. package/packs/fda/policy.json +121 -0
  496. package/packs/fda/source.md +117 -0
  497. package/packs/fdic/endpoints.json +417 -0
  498. package/packs/fdic/policy.json +83 -0
  499. package/packs/fdic/source.md +92 -0
  500. package/packs/fec/endpoints.json +708 -0
  501. package/packs/fec/policy.json +93 -0
  502. package/packs/fec/source.md +90 -0
  503. package/packs/fed-board/endpoints.json +89 -0
  504. package/packs/fed-board/policy.json +136 -0
  505. package/packs/fed-board/source.md +118 -0
  506. package/packs/federal-register/endpoints.json +143 -0
  507. package/packs/federal-register/policy.json +86 -0
  508. package/packs/federal-register/source.md +98 -0
  509. package/packs/fema/endpoints.json +646 -0
  510. package/packs/fema/policy.json +103 -0
  511. package/packs/fema/source.md +103 -0
  512. package/packs/fhfa/endpoints.json +105 -0
  513. package/packs/fhfa/policy.json +109 -0
  514. package/packs/fhfa/source.md +108 -0
  515. package/packs/fred/assets/download_fred.ps1 +122 -0
  516. package/packs/fred/assets/download_fred.sh +123 -0
  517. package/packs/fred/docs/analysis_patterns.md +124 -0
  518. package/packs/fred/docs/fred_api.md +94 -0
  519. package/packs/fred/docs/series.md +188 -0
  520. package/packs/fred/policy.json +253 -0
  521. package/packs/fred/source.md +142 -0
  522. package/packs/fsa/endpoints.json +150 -0
  523. package/packs/fsa/policy.json +99 -0
  524. package/packs/fsa/source.md +102 -0
  525. package/packs/govinfo/endpoints.json +520 -0
  526. package/packs/govinfo/policy.json +116 -0
  527. package/packs/govinfo/source.md +241 -0
  528. package/packs/gsa-calc/endpoints.json +93 -0
  529. package/packs/gsa-calc/policy.json +97 -0
  530. package/packs/gsa-calc/source.md +108 -0
  531. package/packs/hud/endpoints.json +147 -0
  532. package/packs/hud/policy.json +84 -0
  533. package/packs/hud/source.md +97 -0
  534. package/packs/ipums/assets/download_ipums.ps1 +215 -0
  535. package/packs/ipums/assets/download_ipums.sh +192 -0
  536. package/packs/ipums/docs/ipums_api.md +67 -0
  537. package/packs/ipums/docs/report_patterns.md +117 -0
  538. package/packs/ipums/docs/variables.md +284 -0
  539. package/packs/ipums/lib/fetch_text.json +112 -0
  540. package/packs/ipums/policy.json +215 -0
  541. package/packs/ipums/source.md +169 -0
  542. package/packs/irs-soi/endpoints.json +114 -0
  543. package/packs/irs-soi/policy.json +107 -0
  544. package/packs/irs-soi/source.md +124 -0
  545. package/packs/medicaid/endpoints.json +412 -0
  546. package/packs/medicaid/policy.json +108 -0
  547. package/packs/medicaid/source.md +136 -0
  548. package/packs/naep/endpoints.json +217 -0
  549. package/packs/naep/policy.json +100 -0
  550. package/packs/naep/source.md +120 -0
  551. package/packs/nhtsa/endpoints.json +132 -0
  552. package/packs/nhtsa/policy.json +93 -0
  553. package/packs/nhtsa/source.md +109 -0
  554. package/packs/nih/endpoints.json +453 -0
  555. package/packs/nih/policy.json +86 -0
  556. package/packs/nih/source.md +108 -0
  557. package/packs/noaa/endpoints.json +432 -0
  558. package/packs/noaa/policy.json +95 -0
  559. package/packs/noaa/source.md +88 -0
  560. package/packs/nrel/endpoints.json +328 -0
  561. package/packs/nrel/policy.json +96 -0
  562. package/packs/nrel/source.md +91 -0
  563. package/packs/nws/endpoints.json +272 -0
  564. package/packs/nws/policy.json +82 -0
  565. package/packs/nws/source.md +81 -0
  566. package/packs/nyfed/endpoints.json +80 -0
  567. package/packs/nyfed/policy.json +92 -0
  568. package/packs/nyfed/source.md +89 -0
  569. package/packs/omb/endpoints.json +460 -0
  570. package/packs/omb/policy.json +106 -0
  571. package/packs/omb/source.md +130 -0
  572. package/packs/open-payments/endpoints.json +298 -0
  573. package/packs/open-payments/policy.json +101 -0
  574. package/packs/open-payments/source.md +99 -0
  575. package/packs/opm/assets/download_opm.ps1 +125 -0
  576. package/packs/opm/assets/download_opm.sh +85 -0
  577. package/packs/opm/docs/fields.md +184 -0
  578. package/packs/opm/docs/opm_api.md +71 -0
  579. package/packs/opm/docs/report_patterns.md +83 -0
  580. package/packs/opm/lib/data_dictionary.csv +73 -0
  581. package/packs/opm/policy.json +142 -0
  582. package/packs/opm/source.md +137 -0
  583. package/packs/pbgc/endpoints.json +483 -0
  584. package/packs/pbgc/policy.json +94 -0
  585. package/packs/pbgc/source.md +95 -0
  586. package/packs/philfed/endpoints.json +85 -0
  587. package/packs/philfed/policy.json +94 -0
  588. package/packs/philfed/source.md +125 -0
  589. package/packs/port.json +287 -0
  590. package/packs/regulations/endpoints.json +288 -0
  591. package/packs/regulations/policy.json +86 -0
  592. package/packs/regulations/source.md +84 -0
  593. package/packs/sec/endpoints.json +237 -0
  594. package/packs/sec/policy.json +86 -0
  595. package/packs/sec/source.md +101 -0
  596. package/packs/senate-lobbying/endpoints.json +554 -0
  597. package/packs/senate-lobbying/policy.json +99 -0
  598. package/packs/senate-lobbying/source.md +100 -0
  599. package/packs/snapqc/endpoints.json +1426 -0
  600. package/packs/snapqc/policy.json +92 -0
  601. package/packs/snapqc/source.md +96 -0
  602. package/packs/treasury/catalog.json +2267 -0
  603. package/packs/treasury/docs/api_guide.md +245 -0
  604. package/packs/treasury/docs/datasets.md +56 -0
  605. package/packs/treasury/docs/report_patterns.md +126 -0
  606. package/packs/treasury/policy.json +159 -0
  607. package/packs/treasury/source.md +165 -0
  608. package/packs/treasury-yields/endpoints.json +226 -0
  609. package/packs/treasury-yields/policy.json +86 -0
  610. package/packs/treasury-yields/source.md +80 -0
  611. package/packs/usaspending/endpoints.json +1316 -0
  612. package/packs/usaspending/policy.json +109 -0
  613. package/packs/usaspending/source.md +103 -0
  614. package/packs/usda-fna/endpoints.json +427 -0
  615. package/packs/usda-fna/policy.json +133 -0
  616. package/packs/usda-fna/source.md +217 -0
  617. package/packs/usda-fooddata/endpoints.json +181 -0
  618. package/packs/usda-fooddata/policy.json +94 -0
  619. package/packs/usda-fooddata/source.md +105 -0
  620. package/packs/usda-nass/endpoints.json +324 -0
  621. package/packs/usda-nass/policy.json +95 -0
  622. package/packs/usda-nass/source.md +85 -0
  623. package/packs/usda-outlook/endpoints.json +86 -0
  624. package/packs/usda-outlook/policy.json +109 -0
  625. package/packs/usda-outlook/source.md +144 -0
  626. package/packs/usgs/endpoints.json +313 -0
  627. package/packs/usgs/policy.json +95 -0
  628. package/packs/usgs/source.md +96 -0
  629. package/packs/usitc/endpoints.json +74 -0
  630. package/packs/usitc/policy.json +111 -0
  631. package/packs/usitc/source.md +90 -0
  632. package/packs/uspto/endpoints.json +141 -0
  633. package/packs/uspto/policy.json +95 -0
  634. package/packs/uspto/source.md +101 -0
  635. package/packs/va/endpoints.json +414 -0
  636. package/packs/va/policy.json +101 -0
  637. package/packs/va/source.md +129 -0
  638. package/packs/world-bank/endpoints.json +122 -0
  639. package/packs/world-bank/policy.json +101 -0
  640. package/packs/world-bank/source.md +93 -0
@@ -0,0 +1,117 @@
1
+ {
2
+ "id": "congress",
3
+ "title": "Congress.gov API (Library of Congress) with House and Senate roll-call votes",
4
+ "agency": "Library of Congress (Congress.gov); Clerk of the House; Secretary of the Senate",
5
+ "depth": "standard",
6
+ "domains": [
7
+ "legislation",
8
+ "congress",
9
+ "votes"
10
+ ],
11
+ "keywords": [
12
+ "veto",
13
+ "vetoes",
14
+ "veto override",
15
+ "congress",
16
+ "bill",
17
+ "bills",
18
+ "legislation",
19
+ "sponsor",
20
+ "cosponsor",
21
+ "cosponsors",
22
+ "bill status",
23
+ "actions",
24
+ "roll call",
25
+ "roll-call vote",
26
+ "vote",
27
+ "votes",
28
+ "house vote",
29
+ "senate vote",
30
+ "party line",
31
+ "member of congress",
32
+ "senator",
33
+ "representative",
34
+ "committee",
35
+ "committee report",
36
+ "hearing",
37
+ "nomination",
38
+ "confirmation",
39
+ "treaty",
40
+ "crs report",
41
+ "public law",
42
+ "enacted",
43
+ "laws passed",
44
+ "congressional review act",
45
+ "cra resolution",
46
+ "disapproval resolution",
47
+ "committee meetings",
48
+ "committee hearings held",
49
+ "markups"
50
+ ],
51
+ "questions": [
52
+ "how did each party vote on a bill",
53
+ "how many bills became law in each Congress",
54
+ "cosponsors of a bill by party",
55
+ "bills a member sponsored",
56
+ "status and actions of a bill",
57
+ "CRS reports on a topic",
58
+ "nominations confirmed by the Senate"
59
+ ],
60
+ "homepage": "https://www.congress.gov/",
61
+ "terms_url": "https://www.loc.gov/legal/",
62
+ "auth": {
63
+ "env": "DATA_GOV_API_KEY",
64
+ "required": "optional",
65
+ "placement": "query",
66
+ "param": "api_key",
67
+ "home": "data-gov",
68
+ "signup_url": "https://api.data.gov/signup/",
69
+ "echoes_key": false,
70
+ "demo_key": "DEMO_KEY",
71
+ "key_only": [
72
+ "more than about 10 Congress.gov requests an hour (DEMO_KEY limit); roll-call XML needs no key"
73
+ ]
74
+ },
75
+ "limits": {
76
+ "rps": 2,
77
+ "burst": 6,
78
+ "daily_quota": null,
79
+ "max_rows": 50000
80
+ },
81
+ "routes": {
82
+ "api": {
83
+ "base": "https://api.congress.gov/v3",
84
+ "probe": "https://api.congress.gov/v3/congress/119?format=json",
85
+ "hosts": [
86
+ "api.congress.gov",
87
+ "clerk.house.gov",
88
+ "www.senate.gov"
89
+ ]
90
+ },
91
+ "manual": {
92
+ "how": "Open each link in INSTRUCTIONS.md in a browser and save the file under the given name: Congress.gov links carry the public DEMO_KEY (about 10 requests an hour; put your own api.data.gov key in its place for more), roll-call links are the official XML files at clerk.house.gov/evs/<year>/roll<NNN>.xml and www.senate.gov/legislative/LIS/roll_call_votes/. On congress.gov, a bill's page (Actions, Cosponsors tabs) and search results can also be downloaded; upload the files."
93
+ }
94
+ },
95
+ "cache": {
96
+ "mode": "run_only",
97
+ "ttl_hours": null,
98
+ "why": "Bill status, actions and cosponsors change daily while Congress sits; data/ is reused within a run."
99
+ },
100
+ "redistribution": {
101
+ "mode": "allowed",
102
+ "why": "Legislative data from Congress.gov, the House Clerk and the Senate are U.S. government works without copyright (17 U.S.C. 105); the Library of Congress asks for attribution. CRS report texts are public; Congress.gov's terms allow reuse of its data."
103
+ },
104
+ "notices": [],
105
+ "retention": null,
106
+ "citation": "Library of Congress, Congress.gov API, {dataset}, api.congress.gov (roll-call votes: Clerk of the U.S. House of Representatives and U.S. Senate), retrieved {retrieved_long}.",
107
+ "audit_hooks": [],
108
+ "clarify": [
109
+ "Which Congress (two-year term) or session? Default: the current Congress.",
110
+ "Which vote on a bill: final passage, cloture, a motion or an amendment? A bill often has several recorded votes; default: final passage in each chamber.",
111
+ "Bills only (hr, s) or resolutions too? Joint resolutions can become law; simple and concurrent resolutions cannot."
112
+ ],
113
+ "formats": [
114
+ "json",
115
+ "xml"
116
+ ]
117
+ }
@@ -0,0 +1,190 @@
1
+ # Congress.gov API (Library of Congress) with House and Senate roll-call votes
2
+ Depth: standard. Key: optional (DATA_GOV_API_KEY; the public DEMO_KEY works at about 10 requests an
3
+ hour; roll-call XML needs no key). Bills, actions, cosponsors, CRS summaries, laws, members, committees,
4
+ committee reports, hearings, nominations, treaties and CRS reports from Congress.gov, and member-level
5
+ roll-call votes from the House Clerk (1990 on) and the Senate (1989 on).
6
+
7
+ ## When to use
8
+ - Status, actions and sponsors of a bill; cosponsors by party; bills a member sponsored; laws enacted per
9
+ Congress; how each party and member voted; committee referrals and reports; nominations and
10
+ confirmations; CRS reports and summaries.
11
+ - Not here: full text search of bills and the text itself (govinfo `search`, `text`); rules and
12
+ executive orders (federal-register); lobbying on a bill (senate-lobbying); campaign money (fec).
13
+
14
+ ## Endpoints and datasets
15
+ | Endpoint | Returns (one row per) | Key parameters |
16
+ |---|---|---|
17
+ | `bills`, `bills_congress` | bill (number, title, `introducedDate`, latest action) | `congress`, `billType`, `fromDateTime`, `toDateTime`, `sort` (`updateDate+desc` default, `updateDate+asc`, `introducedDate+desc`, `introducedDate+asc`), `title_contains` |
18
+ | `bill` | one bill (sponsor, policy area, laws, counts) | `congress`, `billType`, `billNumber` |
19
+ | `bill_actions`, `bill_cosponsors`, `bill_committees`, `bill_subjects`, `bill_summaries`, `bill_text`, `bill_titles`, `bill_related`, `bill_amendments` | action, cosponsor, committee, subject, summary, text version, title, related bill, amendment | same three |
20
+ | `bill_cbo_estimates` | cost estimate listed for the bill: title, date, cbo.gov link | same three |
21
+ | `bill_votes` | recorded vote on the bill with totals by party (`members: true`: member x vote) | same three, `chamber`, `members` |
22
+ | `roll_call` | member's vote on one roll call | `chamber` (house, senate), `roll`; House `year` or `congress`+`session`; Senate `congress`+`session` |
23
+ | `senate_votes` | Senate vote in a session (date, issue, question, result, yeas, nays; `en_bloc` = nominations voted together, their issues joined by "; ") | `congress`, `session` |
24
+ | `house_votes`, `house_vote` | House vote (115th Congress, 2017, on); party totals for one vote | `congress`, `session`, `voteNumber` |
25
+ | `laws`, `laws_congress` | law (public or private) | `laws`: `congress`, `lawType` (pub, priv; path /law/{congress}/{lawType}); `laws_congress`: `congress` only, public and private together (a `lawType` param there is ignored by the API) |
26
+ | `summaries` | CRS summary updated in a period | `congress`, `billType`, `fromDateTime` |
27
+ | `members`, `members_congress`, `members_state`, `members_district`, `member` | member (bioguideId, party, state, terms) | `congress`, `stateCode`, `district`, `currentMember`, `bioguideId`. `members_congress` lists everyone who served at any time in that Congress (later entrants too); `partyName` is the current party; `terms` merges continuous service in a chamber into one start/end-year item (no swearing-in dates). Membership on a date (e.g. the opening day) comes from that day's roll calls; the Senate may hold none on the opening day (2025: first on Jan 9), and the House's quorum call and first vote can differ by a member. A current member's `terms` item has no `endYear`. Members seated in the lame duck before a Congress (Kim, Schiff in Dec 2024) have `startYear` the year before: "first elected in November" counts them. Join Senate XML to Congress.gov names without accents ("Lujan"/"Luján") |
28
+ | `member_sponsored`, `member_cosponsored` | bill a member sponsored or cosponsored | `bioguideId` |
29
+ | `committees`, `committee`, `committee_bills`, `committee_bills_congress`, `committee_reports`, `hearings` | committee, bill, report, hearing | `congress`, `chamber`, `committeeCode` (hsba00), `reportType` (hrpt, srpt, erpt). `committee_bills` spans every Congress (`fromDateTime` filters on update date); `committee_bills_congress` takes `congress` and returns that Congress only and gives one row per bill with only its **latest** committee activity and that date: count referrals as all rows of the bills of that Congress except "Reported Original Measure" and "Bills of Interest", never only "Referred To" rows, and take referral dates from `bill_committees` |
30
+ | `hearing` | one printed hearing: title, dates held, committees, citation | `congress`, `chamber`, `jacketNumber` (from `hearings`) |
31
+ | `nominations`, `nomination`, `nomination_actions` | nomination (PN), its actions | `congress`, `nominationNumber` |
32
+ | `treaties`, `amendments`, `congress_info` | treaty, amendment, session dates | `congress` |
33
+ | `committee_meetings`, `committee_meeting` | meetings of a chamber's committees (hearings, markups, business meetings); one meeting: date, type ("Open Hearing", "Markup"), title, committees, status | `congress`, `chamber` (house, senate, nochamber), `eventId`. The list has only eventIds: `for_each` over it for dates and committees (about one call per meeting; check the count). `hearings` is printed hearings only. A meeting's `committees` can lack `name` and can repeat a systemCode: deduplicate by code and take names and parents from `committees`. Status: count Scheduled and Rescheduled (the record carries the new date), not Canceled or Postponed. A reconvened markup is its own event; Rules Committee sessions are all typed "Meeting" |
34
+ | `amendments_type`, `amendment` | amendments of one type; one amendment (submittedDate, purpose, amended bill) | `congress`, `amendmentType` (samdt, hamdt, suamdt), `amendmentNumber`. Lists carry no submitted date (most rows have no latestAction either); amendment numbers run in submission order, so a count by a date is the highest number submitted by then: read the boundary amendments' `submittedDate` with `amendment` (or `for_each`) |
35
+ | `crs_reports`, `crs_report` | CRS report (id, title, date, status); one report with authors, summary, links | `fromDateTime`, `toDateTime`, `title_contains`, `reportNumber` |
36
+
37
+ `congress` may be `"current"`. Bill types: hr, s, hjres, sjres, hconres, sconres, hres, sres.
38
+ `title_contains` keeps rows whose title holds the phrase as given: its words in that order, each matching
39
+ at the start of a word, any case ("water rights" never matches "Rights of ... Water Users"; "port" never
40
+ matches "support", but "veteran" finds "Veterans"); a list keeps titles holding any of its phrases (forms
41
+ that do not start the same: `["levy", "levies"]`). To match words in any order or apart, list each form
42
+ as its own phrase (`["water rights", "rights to water"]`) or filter on one distinctive word and read the
43
+ titles in the CSV: this matters most for `crs_reports`, where `title_contains` is the only text filter; a
44
+ multi-word phrase that keeps nothing says so in the error or note. It filters after download, so combine
45
+ it with `max_rows` or a date range. It reads the list's display `title` only: a bill whose official title alone has
46
+ the word is missed (often more bills than the display titles hold), and the fetch notes this every time.
47
+ **For "X in the title", the route is GovInfo's title search, never a full-text phrase search** (`phrase`
48
+ searches the whole text and misses many bills): source govinfo, endpoint `search`, params
49
+ `{"collection": "BILLS", "congress": 118, "title": "<phrase>"}` (one per word form, or
50
+ `query: "title:tariff OR title:tariffs"`), strip the version suffix from `packageId` and deduplicate, then
51
+ confirm each bill with `bill_titles` (`for_each` on congress, billType, billNumber); say which title the count uses. `request_schema` with `search: "votes"` lists catalog aliases (committee codes, bill types).
52
+
53
+ ## Spec examples
54
+ ```json
55
+ {"description": "Laken Riley Act (119th S. 5): bill, cosponsors and every recorded vote by party",
56
+ "requests": [
57
+ {"name": "s5_bill", "endpoint": "bill", "params": {"congress": 119, "billType": "s", "billNumber": 5}},
58
+ {"name": "s5_cosponsors", "endpoint": "bill_cosponsors", "params": {"congress": 119, "billType": "s", "billNumber": 5}},
59
+ {"name": "s5_votes", "endpoint": "bill_votes", "params": {"congress": 119, "billType": "s", "billNumber": 5}}]}
60
+ ```
61
+ ```json
62
+ {"description": "How each member voted on final passage of H.R. 5376 (117th) in both chambers",
63
+ "requests": [
64
+ {"name": "senate_325", "endpoint": "roll_call", "params": {"chamber": "senate", "congress": 117, "session": 2, "roll": 325}},
65
+ {"name": "house_420", "endpoint": "roll_call", "params": {"chamber": "house", "year": 2022, "roll": 420}}]}
66
+ ```
67
+ ```json
68
+ {"description": "Public laws of the 118th Congress and CRS reports updated since September 2026",
69
+ "requests": [
70
+ {"name": "laws_118", "endpoint": "laws", "params": {"congress": 118, "lawType": "pub"}},
71
+ {"name": "crs_fall", "endpoint": "crs_reports", "params": {"fromDateTime": "2026-09-01T00:00:00Z"}}]}
72
+ ```
73
+
74
+ ## Data format and traps
75
+ - Congress numbers: the n-th Congress runs two years from January 3 of 1789 + 2(n-1) (March 4 before
76
+ 1935): 119th = 2025-2026, 118th = 2023-2024. January 1-2 of an odd year still belong to the previous
77
+ Congress. Session 1 is the odd year, session 2 the even year (a session can run into early January).
78
+ - Bill numbers restart every Congress: always carry `congress` and `billType` with the number.
79
+ - Counting bills: the `bills` list includes numbers "Reserved for the Speaker" / "Minority Leader" (no
80
+ `latestAction`, no bill): drop them (11 in the 119th) to match the Résumé of Congressional Activity.
81
+ "Passed the House": a House passage action in `bill_actions` (actionCode 8000, "Passed/agreed to in
82
+ House"), or any later Senate or presidential action; never infer it from `latestAction` text ("Motion to
83
+ reconsider laid on the table" follows failed votes too). No call count is shown before a fetch: for paged
84
+ lists count about one call per 250 rows.
85
+ - Congressional Review Act disapprovals: joint resolutions whose titles read "Disapproving the rule
86
+ submitted by ..." (older) or "Providing for congressional disapproval under chapter 8 of title 5" (newer):
87
+ match "disapprov", then drop D.C. Council disapprovals (Home Rule Act, e.g. H.J.Res. 142 of the 119th).
88
+ - Becoming law: `bill.laws` (and `latestAction.text` "Became Public Law No: 119-1.") marks enacted
89
+ bills; `laws` lists them. `latestAction` is not always the enactment (a committee report filed after
90
+ signing replaces it: H.R. 1043, PL 119-68): count laws from `laws`, and take the signing date from
91
+ `bill_actions` ("Became Public Law"), never from `latestAction.actionDate`. The `bills` lists carry
92
+ `introducedDate` (and sort by it) but no `policyArea`; the `laws` lists carry neither and ignore `sort`
93
+ (verified 2026-10-22): those need one `bill` call per law, a second spec with
94
+ `"for_each": {"csv": "data/congress/<laws>.csv", "map": {"billType": "type", "billNumber": "number"},
95
+ "lower": true}` (bill numbers repeat across types; one call per row of the laws CSV). Counting "bills passed" needs a chamber action, not `latestAction` alone.
96
+ - Votes: a bill usually has several recorded votes (cloture, motions to proceed, amendments, passage,
97
+ conference). `bill_votes` lists every one with the action text. Final passage is each chamber's LAST
98
+ recorded vote that cleared the bill ("On Passage", "On Passage of the Bill", "On Motion to Concur ...",
99
+ "On Agreeing to the Conference Report"): take the latest date, not the first "On Passage". A bill used
100
+ as a vehicle for other text (CHIPS and Science moved as H.R. 4346, first passed as a legislative-branch
101
+ appropriation) has an early "On Passage" vote on the old text; the Clerk's `description` can keep the
102
+ old title. Voice votes and unanimous consent leave no roll call and no row.
103
+ - Zero rows can be the right answer (no private laws in the 118th Congress, no votes on a bill): mark
104
+ such requests `"allow_empty": true`, or the fetch stops and names them.
105
+ - Party totals: House rows take the Clerk's totals by party; Senate rows are counted from the member
106
+ list (`yea_D`, `nay_R`, ...; independents as I). `not_voting` counts absent members; vacant seats are
107
+ not counted anywhere, so totals can be under 435 or 100. The Vice President's tie-breaking vote is in
108
+ `tie_breaker`, not in the member rows.
109
+ - Member ids differ by source: House rows and Congress.gov use bioguide ids (A000370); Senate XML uses
110
+ LIS ids (S354). Join Senate votes to members by name and state, or a crosswalk, not by id.
111
+ - `vote` keeps the published word (Yea, Aye, Nay, No, Present, Not Voting, Guilty); `position` maps it
112
+ to yea, nay, present, not_voting or other. House "Aye"/"No" are recorded votes, same meaning.
113
+ - Cosponsors: `sponsorshipWithdrawnDate` marks withdrawals (still listed);
114
+ `cosponsors.countIncludingWithdrawnCosponsors` in `bill` counts them. Count by `party` for a party split.
115
+ - Cost estimates: `bill_cbo_estimates` gives only what Congress.gov lists: title, publication date,
116
+ description and a cbo.gov link for each estimate. No dollar figures are in the API; the estimate
117
+ itself is a PDF or web page (committee reports in govinfo CRPT often reprint it as text).
118
+ - CRS: `crs_reports` lists reports Congress.gov publishes (newest first, about 14,000 in Oct 2026);
119
+ there is no keyword search: use a date range and `title_contains`, then `crs_report` for the summary.
120
+ `fromDateTime`/`toDateTime` filter on the UPDATE date (one September window returned 1,244 products
121
+ published 2004-2026): for "published in a month" filter the rows on `publishDate` afterwards. `publishDate`
122
+ is the current version's date, so a product first issued in the month and revised later drops out (a
123
+ floor, say so). The list's `version` is not the product version: `crs_report` gives `currentVersion`.
124
+ `bill_summaries` are CRS summaries of each bill version (HTML in `text`, plain in `text_plain`); some fields
125
+ are over 131,072 characters: when reading the CSV with your own code, raise the reader's field size limit first.
126
+ - Nominations (traps seen in Oct 2026 data; the Senate Résumé's "Civilian nominees" table is the benchmark):
127
+ military and "Other Civilian" lists (Foreign Service, PHS, NOAA officers) are list nominations without a
128
+ description; `nominationType` (`isCivilian`, `isMilitary`) is missing on some rows of older Congresses
129
+ (every row of the 119th has one); a PN split into parts
130
+ (PN12-41) counts once per part; en bloc votes confirm many nominees at once. `latestAction` is the last
131
+ step, which can be a later procedural motion ("motion to reconsider tabled") or, for a nomination held over,
132
+ its confirmation in the next session: count outcomes by date from `nomination_actions`, within the
133
+ session's dates. A split PN's actions need `nominationNumber` "1255-17": `"for_each": {"csv":
134
+ "data/congress/<noms>.csv", "column": "citation", "param": "nominationNumber", "strip": "PN"}` (`number` alone
135
+ returns nothing for a split PN). The naive count (civilian flag + `latestAction` "Confirmed") gave 60 percent for 2023
136
+ against the Résumé's 47.
137
+ - Paging: 250 per request (`limit`/`offset`). Lists default to the newest update first.
138
+ - Vetoes: a vetoed bill's `latestAction` often is a later procedural step, and no endpoint filters bills by
139
+ action. Read `bill_actions` (for_each over candidate bills that passed both chambers and are not law) for
140
+ the action "Vetoed by President" (actionCode 31000 in 2026 data) and override votes ("...objections of the
141
+ President to the contrary notwithstanding"). The Senate's veto page (senate.gov/legislative/vetoes, regular
142
+ and pocket vetoes per President) is the benchmark. Reserved bill numbers (H.R. 1-10, S. 1-10 for leaders)
143
+ have no actions: allow_empty or drop them first.
144
+ - Whole-session vote counts and party splits: no endpoint returns party totals in bulk, so a session takes
145
+ one `roll_call` per vote (about 1,000 a year, several minutes). For the House's questions and results
146
+ (`house_votes` has no question column; `house_vote` keeps only party totals), `for_each` over the
147
+ `house_votes` list's `rollCallNumber` with `roll_call` `"summary": "true"` and the year: one row per vote with
148
+ question ("On Motion to Suspend the Rules and Pass"), vote type ("2/3 YEA-AND-NAY"), result and totals. `house_votes` lists quorum calls too (vote
149
+ type "Quorum"): the Résumé counts them apart from yea-and-nay and recorded votes. The Speaker election's
150
+ member rows have position `other` (votes are names). Say how independents are counted in a party split.
151
+ - `house_votes`/`house_vote` (Congress.gov) start with the 115th Congress (2017; the 114th lists 0 votes,
152
+ verified 2026-10-22); `roll_call` reads the Clerk
153
+ XML for 1990 on (and falls back to the Congress.gov member list for the 115th on if the Clerk file
154
+ cannot be read). Senate XML covers the 101st Congress (1989) on.
155
+ - Dates: Congress.gov timestamps are UTC (`2025-01-22T...Z`); vote `date` is the vote's own calendar
156
+ date (ISO), `date_published` keeps the source text.
157
+
158
+ ## Access
159
+ Key optional: DATA_GOV_API_KEY (https://api.data.gov/signup/), sent as `api_key` to api.congress.gov
160
+ only (Congress.gov documents 5,000 requests an hour for a key; DEMO_KEY about 10 an hour per IP, observed
161
+ limit 10). Without a key, a spec needing more than a few Congress.gov calls makes `fetch` stop with
162
+ `key_missing` (the message gives the call count). House Clerk and Senate XML need no key. Manual route
163
+ (`manual_bundle`): INSTRUCTIONS.md lists Congress.gov JSON links with
164
+ `api_key=DEMO_KEY` and the vote XML links (clerk.house.gov/evs/<year>/roll<NNN>.xml;
165
+ www.senate.gov/legislative/LIS/roll_call_votes/vote<congress><session>/vote_<c>_<s>_<NNNNN>.xml);
166
+ for `bill_votes` the bill's actions JSON lists each vote's XML link. Upload the files, then `ingest`.
167
+ senate.gov sometimes refuses scripts (HTTP 403, seen from some networks in Oct 2026): a fetch of Senate votes
168
+ then stops with `agency_unavailable`, and `manual_bundle` gives the XML links. Without a user to save the XML, the
169
+ Congressional Record prints each Senate roll call's names. The reliable path is the page: the vote's
170
+ `bill_actions` text cites it ("Record Vote Number: 7 ... (CR S250-251)"); list that day's issue with govinfo
171
+ `granules` (`packageId` CREC-<date>), take the Senate granule whose id holds the page (`...-PgS250`, or the
172
+ last one starting before it), and read it with govinfo `text` (`packageId` + `granuleId`); check the
173
+ `[Rollcall Vote No. 7 Leg.]` line in it. A `search` (collection CREC, `phrase: "Rollcall Vote No. 7 Leg"`)
174
+ can find it too but missed 2 of 4 votes in Jan 2025 tests: never treat an empty search as "no vote". The
175
+ Record lists names only (YEAS / NAYS / NOT VOTING): take party and state from `members_congress`, and say the
176
+ split came from the Record. Votes print under the legislative day, which can be an earlier date (the Senate's
177
+ July 1, 2025 votes are in `CREC-2025-06-30`). Request House votes alone (`"chamber": "house"`) so a Senate
178
+ block does not stop them. A whole session of Senate votes (counts, shares by question) comes from the Daily
179
+ Digest: govinfo `published` CREC for the session's dates, `granules` for_each, keep the Daily Digest Senate
180
+ granules, `text` for_each, then parse "(Vote No. N)" and the running "(Total--N)". Traps seen in 2025: a few
181
+ votes are not numbered in the Digest (take them from the Record's Senate pages), the form "(Vote 569)" and page
182
+ markers inside a reference, a misprinted number (the running total proves the right one), and Digests that
183
+ reprint earlier votes (deduplicate by number). "Ex."/"Leg." marks the session the vote was taken in, not its
184
+ subject: classify nominations by the question text. Benchmark the count with the Résumé of Congressional
185
+ Activity (Daily Digest, early January: 659 Senate yea-and-nay votes in 2025).
186
+
187
+ ## Citation and terms
188
+ "Library of Congress, Congress.gov API, <query>, api.congress.gov, retrieved <date>"; for votes add
189
+ "roll-call votes from the Clerk of the U.S. House of Representatives (clerk.house.gov) and the U.S.
190
+ Senate (senate.gov)". Public domain legislative data; attribute the source. Redistribution allowed.
@@ -0,0 +1,66 @@
1
+ {
2
+ "base_url": "https://ohss.dhs.gov",
3
+ "timeout": 60,
4
+ "endpoints": {
5
+ "yearbook_table": {
6
+ "path": "/topics/immigration/yearbook/{fiscal_year}",
7
+ "description": "One table (one sheet) of the Yearbook of Immigration Statistics workbook for a topic and fiscal year. The pack reads the year page, finds the topic's published .xlsx (FY2022 on) or .zip of one .xlsx per table (FY2015-2021), and returns the sheet as published: the header row is detected (a two-row header is joined), section label rows (REGION, COUNTRY, NEW ARRIVALS ...) become a `section` column, and the footnote, Notes and Source lines go into the fetch notes.",
8
+ "params": {
9
+ "topic": {"in": "spec", "required": true,
10
+ "enum": ["lpr", "lpr_supplementary", "lpr_expanded", "refugees", "asylees", "refugees_asylees",
11
+ "naturalizations", "naturalizations_supplementary", "nonimmigrant",
12
+ "nonimmigrant_supplementary", "enforcement"],
13
+ "desc": "which workbook of the year: lpr (Tables 1-12, plus the LPR supplemental tables from FY2022), lpr_expanded (Tables 8-11 split into adjustments of status and new arrivals), refugees, asylees (refugees_asylees: the combined workbook up to FY2022), naturalizations, nonimmigrant, enforcement; *_supplementary = the separate supplementary zip of FY2015-2021"},
14
+ "fiscal_year": {"in": "path", "desc": "fiscal year of the yearbook (Oct-Sep), e.g. 2024; default: the newest year page that has the topic's file"},
15
+ "table": {"in": "spec", "desc": "sheet name as published, e.g. \"Table 6\", \"LPRSuppTable 1\", \"NISuppTable1\" (also \"6\" or \"table6\"); a wrong or missing name fails with the workbook's sheets and their titles"},
16
+ "header_row": {"in": "spec", "desc": "optional: 1-based row (among the rows the workbook stores) that holds the column names; default: detected"}
17
+ },
18
+ "records": "$xlsx",
19
+ "paging": {"type": "none"}
20
+ },
21
+ "lir_table": {
22
+ "path": "/topics/immigration/legal-immigration-and-adjustment-status-report",
23
+ "description": "One table of the quarterly Legal Immigration and Adjustment of Status Report workbook (preliminary quarterly LPR, refugee, naturalization and nonimmigrant counts for the fiscal year so far, FY2016 on). Read the same way as yearbook_table.",
24
+ "params": {
25
+ "fiscal_year": {"in": "spec", "desc": "fiscal year of the report, e.g. 2025; default: the newest posted"},
26
+ "table": {"in": "spec", "desc": "sheet name, e.g. \"Table 1A\" (LPR by nationality and quarter), \"Table 1B\" (LPR by class of admission), \"Table 2\" (refugee arrivals), \"Table 3\" (naturalizations), \"Table 4A\"/\"Table 4B\" (nonimmigrant admissions)"},
27
+ "header_row": {"in": "spec", "desc": "optional: 1-based header row; default: detected"}
28
+ },
29
+ "records": "$xlsx",
30
+ "paging": {"type": "none"}
31
+ },
32
+ "yearbook_files": {
33
+ "path": "/topics/immigration/yearbook/{fiscal_year}",
34
+ "description": "The data files posted on a yearbook year page (one row per file: fiscal_year, topic, title, url, format), scraped from the page because the file names carry upload dates. Use it to see what a year has before asking for a table.",
35
+ "params": {
36
+ "fiscal_year": {"in": "path", "desc": "one year (2015 on has data files), a list of years, or omit for the newest year page"},
37
+ "topic": {"in": "spec", "desc": "optional: keep only this topic's files (same names as yearbook_table)"}
38
+ },
39
+ "paging": {"type": "none"}
40
+ },
41
+ "lir_files": {
42
+ "path": "/topics/immigration/legal-immigration-and-adjustment-status-report",
43
+ "description": "The Legal Immigration and Adjustment of Status Report workbooks posted (one row per fiscal year: fiscal_year, through_quarter, title, url).",
44
+ "params": {},
45
+ "paging": {"type": "none"}
46
+ }
47
+ },
48
+ "catalog": {
49
+ "lpr": {"id": "lpr", "endpoint": "yearbook_table", "name": "Lawful permanent residents (green cards), Yearbook Tables 1-12",
50
+ "description": "persons obtaining lawful permanent resident status (green card holders) by year, country of birth, last residence, state, metro area, class of admission (family, employment, diversity, refugee, asylee), adjustments of status vs new arrivals, sex, age, occupation"},
51
+ "lpr_expanded": {"id": "lpr_expanded", "endpoint": "yearbook_table", "name": "Expanded Tables 8-11 (adjustments of status and new arrivals)",
52
+ "description": "LPR demographic and country tables split by adjustment of status and new arrival"},
53
+ "refugees": {"id": "refugees", "endpoint": "yearbook_table", "name": "Refugee arrivals, Yearbook Tables 13-15",
54
+ "description": "refugee arrivals by year, country of nationality, relationship, sex, age"},
55
+ "asylees": {"id": "asylees", "endpoint": "yearbook_table", "name": "Individuals granted asylum, Yearbook Tables 16-20",
56
+ "description": "asylum granted affirmatively (USCIS) or defensively (immigration courts) by country of nationality"},
57
+ "naturalizations": {"id": "naturalizations", "endpoint": "yearbook_table", "name": "Naturalizations, Yearbook Tables 21-25",
58
+ "description": "persons naturalized (new U.S. citizens), applications filed and denied, by country of birth, state, metro area"},
59
+ "nonimmigrant": {"id": "nonimmigrant", "endpoint": "yearbook_table", "name": "Nonimmigrant admissions, Yearbook Tables 26-33",
60
+ "description": "temporary visitor admissions (I-94) by class of admission (tourist, student F-1, H-1B worker), country of citizenship, state of destination, month"},
61
+ "enforcement": {"id": "enforcement", "endpoint": "yearbook_table", "name": "Immigration enforcement actions, Yearbook Tables 33-42",
62
+ "description": "apprehensions, encounters, inadmissibility determinations, removals (deportations), returns, expulsions by country of nationality and criminal status"},
63
+ "lir": {"id": "lir", "endpoint": "lir_table", "name": "Legal Immigration and Adjustment of Status Report (quarterly)",
64
+ "description": "preliminary quarterly green card, refugee, naturalization and nonimmigrant admission counts for the current fiscal year"}
65
+ }
66
+ }
@@ -0,0 +1,107 @@
1
+ {
2
+ "id": "dhs-ohss",
3
+ "title": "DHS Office of Homeland Security Statistics: Yearbook of Immigration Statistics",
4
+ "agency": "U.S. Department of Homeland Security, Office of Homeland Security Statistics",
5
+ "depth": "standard",
6
+ "domains": [
7
+ "immigration",
8
+ "demographics"
9
+ ],
10
+ "keywords": [
11
+ "immigration statistics",
12
+ "green card",
13
+ "green cards",
14
+ "lawful permanent resident",
15
+ "lawful permanent residents",
16
+ "permanent residency",
17
+ "immigrants",
18
+ "adjustment of status",
19
+ "naturalization",
20
+ "naturalizations",
21
+ "new citizens",
22
+ "refugees",
23
+ "refugee arrivals",
24
+ "asylum",
25
+ "asylees",
26
+ "nonimmigrant admissions",
27
+ "temporary visitors",
28
+ "i-94",
29
+ "h-1b",
30
+ "student visas",
31
+ "deportations",
32
+ "removals",
33
+ "apprehensions",
34
+ "immigration enforcement",
35
+ "yearbook of immigration statistics",
36
+ "dhs",
37
+ "uscis"
38
+ ],
39
+ "questions": [
40
+ "how many green cards were issued in fiscal year 2024",
41
+ "lawful permanent residents by country of birth over the last decade",
42
+ "family-sponsored vs employment-based green cards",
43
+ "naturalizations by state",
44
+ "refugee arrivals by country of nationality",
45
+ "asylum grants by country",
46
+ "H-1B and student nonimmigrant admissions",
47
+ "removals and returns by country of nationality",
48
+ "green cards so far this fiscal year by quarter"
49
+ ],
50
+ "homepage": "https://ohss.dhs.gov/topics/immigration/yearbook",
51
+ "terms_url": "https://ohss.dhs.gov/about-our-data",
52
+ "auth": {
53
+ "env": null,
54
+ "required": "none",
55
+ "placement": "none",
56
+ "param": null,
57
+ "prefix": "",
58
+ "home": null,
59
+ "signup_url": null,
60
+ "echoes_key": false,
61
+ "key_only": [],
62
+ "extra": {},
63
+ "demo_key": null
64
+ },
65
+ "limits": {
66
+ "rps": 1,
67
+ "burst": 3,
68
+ "daily_quota": null,
69
+ "errors_per_min": null,
70
+ "bytes_per_min": null,
71
+ "max_rows": 50000
72
+ },
73
+ "routes": {
74
+ "api": {
75
+ "base": "https://ohss.dhs.gov",
76
+ "probe": "https://ohss.dhs.gov/topics/immigration/yearbook",
77
+ "hosts": [
78
+ "ohss.dhs.gov"
79
+ ]
80
+ },
81
+ "manual": {
82
+ "how": "Open https://ohss.dhs.gov/topics/immigration/yearbook, choose the fiscal year, and download the topic's data tables workbook (e.g. \"Lawful Permanent Residents 2024 Data Tables (xlsx)\"; FY2015-2021 are .zip files); for the quarterly report open https://ohss.dhs.gov/topics/immigration/legal-immigration-and-adjustment-status-report and download the fiscal year's .xlsx. Upload the file unchanged under the name shown in INSTRUCTIONS.md: the pack reads the requested sheet from it."
83
+ }
84
+ },
85
+ "cache": {
86
+ "mode": "run_only",
87
+ "ttl_hours": null,
88
+ "why": "Small published workbooks that are revised and re-posted under new names; data/ is reused only within a run."
89
+ },
90
+ "redistribution": {
91
+ "mode": "allowed",
92
+ "why": "Statistics published by a U.S. federal agency are U.S. government works in the public domain (17 U.S.C. 105)."
93
+ },
94
+ "notices": [],
95
+ "retention": null,
96
+ "citation": "U.S. Department of Homeland Security, Office of Homeland Security Statistics, {dataset}, ohss.dhs.gov, retrieved {retrieved_long}.",
97
+ "audit_hooks": [],
98
+ "clarify": [
99
+ "Which fiscal year? DHS counts by federal fiscal year (October to September), not calendar year; the newest yearbook is the default, and the quarterly report covers the current year with preliminary figures.",
100
+ "All persons obtaining LPR status, or only new arrivals from abroad (or only adjustments of status inside the U.S.)? The yearbook total counts both.",
101
+ "By country of birth, country of last residence, or (for refugees, asylees and the quarterly report) country of nationality? They are different tables with different counts."
102
+ ],
103
+ "formats": [
104
+ "xlsx",
105
+ "zip"
106
+ ]
107
+ }
@@ -0,0 +1,120 @@
1
+ # DHS Office of Homeland Security Statistics (Yearbook of Immigration Statistics)
2
+ Depth: standard. Key: none. The DHS Yearbook of Immigration Statistics tables (green cards / lawful permanent
3
+ residents, refugees, asylees, naturalizations, nonimmigrant admissions, enforcement actions) by fiscal year, read
4
+ from the workbooks posted on ohss.dhs.gov, plus the quarterly Legal Immigration and Adjustment of Status Report.
5
+
6
+ ## When to use
7
+ - Official annual counts of people obtaining green cards (LPR status) by class of admission (family, employment,
8
+ diversity, refugee/asylee adjustments), country of birth or last residence, state, metro area, age, sex,
9
+ occupation; refugee arrivals; asylum grants (affirmative and defensive); naturalizations; nonimmigrant (I-94)
10
+ admissions by class (tourists, students, H-1B and other workers), country, state; apprehensions, encounters,
11
+ removals, returns and Title 42 expulsions.
12
+ - The current fiscal year so far, by quarter: `lir_table` (preliminary).
13
+ - Not here: the foreign-born population or immigrants' characteristics from surveys (census ACS); visa issuance
14
+ (State Department, not covered); immigration court cases (EOIR, not covered); monthly enforcement statistics: the
15
+ OHSS "Immigration Enforcement and Legal Processes Monthly Tables" stop at November 2024 and the page says the
16
+ report "is delayed while it is under review" (verified 2026-10-30); this pack does not read them.
17
+
18
+ ## Endpoints and datasets
19
+ | Endpoint | Returns | Key parameters |
20
+ |---|---|---|
21
+ | `yearbook_table` | one sheet of a yearbook workbook, as published | `topic`, `fiscal_year`, `table`, `header_row` |
22
+ | `lir_table` | one sheet of the quarterly report workbook (FY2016 on) | `fiscal_year`, `table`, `header_row` |
23
+ | `yearbook_files` | the data files posted for a year: `fiscal_year, topic, title, url, format` | `fiscal_year` (one, a list, or newest), `topic` |
24
+ | `lir_files` | the quarterly report workbooks: `fiscal_year, through_quarter, title, url` | none |
25
+
26
+ Topics (FY2024 table numbers; earlier years number them differently, e.g. FY2023 refugees 13-15, asylees 16-19,
27
+ naturalizations 20-24, nonimmigrants 25-32, enforcement 33-42):
28
+ | `topic` | Tables | Notes |
29
+ |---|---|---|
30
+ | `lpr` | 1-12 and LPRSuppTable 1-4 | Table 6: type and major class, 10 years; Table 7: detailed class (IR1, CR6 ...), one year; Table 3: country of birth; Table 2: last residence; Table 4: state; Table 5: metro (CBSA) |
31
+ | `lpr_expanded` | Tables 8-11 split by adjustments of status / new arrivals | separate workbook |
32
+ | `refugees` / `asylees` | 13-15 / 16-20 | up to FY2022 one combined workbook (`refugees_asylees`; `refugees` and `asylees` both find it) |
33
+ | `naturalizations` | 21-25 and 3 supplemental tables | |
34
+ | `nonimmigrant` | 26-33, NISuppTable1-3 | |
35
+ | `enforcement` | 33-42 (FY2023) | FY2024 is "coming soon" on its page (2026-10-30): ask for FY2023 |
36
+ | `*_supplementary` | the separate supplementary zip of FY2015-2021 | from FY2022 the same tables are in the main workbook (the pack uses it and says so) |
37
+
38
+ Coverage: data workbooks for FY2015 on (.xlsx from FY2022, a .zip of one .xlsx per table for FY2015-2021); older
39
+ years are PDF only. Without `fiscal_year` the pack takes the newest year page that posts the topic's file and says
40
+ which. `table` is the sheet name (`"Table 6"`, `"LPRSuppTable 1"`, `"NISuppTable1"`, FY2015-2021 `"Table 7D"`), or a
41
+ number (`"6"`); a missing or wrong name fails with every sheet and its title, so a first request can be used to see
42
+ them. `yearbook_files` shows what a year has. `request_schema` with `search` finds topics by words (green card, deportation, H-1B).
43
+
44
+ ## Spec examples
45
+ ```json
46
+ {"description": "Persons obtaining LPR status by type and major class of admission, FY2015-2024",
47
+ "requests": [{"name": "lpr_class", "endpoint": "yearbook_table",
48
+ "params": {"topic": "lpr", "fiscal_year": 2024, "table": "Table 6"}}]}
49
+ ```
50
+ ```json
51
+ {"description": "Green cards by country of birth (newest yearbook) and removals by nationality (FY2023)",
52
+ "requests": [{"name": "lpr_birth", "endpoint": "yearbook_table", "params": {"topic": "lpr", "table": "Table 3"}},
53
+ {"name": "removals", "endpoint": "yearbook_table",
54
+ "params": {"topic": "enforcement", "fiscal_year": 2023, "table": "Table 42"}}]}
55
+ ```
56
+ ```json
57
+ {"description": "This fiscal year's green cards by class and quarter, and what the FY2024 yearbook page posts",
58
+ "requests": [{"name": "lir_class", "endpoint": "lir_table", "params": {"table": "Table 1B"}},
59
+ {"name": "files", "endpoint": "yearbook_files", "params": {"fiscal_year": 2024}}]}
60
+ ```
61
+
62
+ ## Data format and traps
63
+ - **Layout kept as published.** Columns are the sheet's header (the first row with two or more filled cells, or
64
+ `header_row`; the note says which row). Two header rows are joined: "Adjustments of status Quarter 1", "2014
65
+ Criminal". Upper-case label rows (TOTAL, ADJUSTMENTS OF STATUS, NEW ARRIVALS, REGION, COUNTRY, AGE) are not rows:
66
+ they fill a first column `section`, so `Total` appears once per section (Table 6: TOTAL / ADJUSTMENTS OF STATUS /
67
+ NEW ARRIVALS; Table 3: REGION and COUNTRY). Filter on `section` before summing, and never add a region to its
68
+ countries. Year tables such as Table 1 and Table 33 are printed in side-by-side panels (`Year`, `Number`,
69
+ `Year_col3`, `Number_col4` ...): stack them yourself. Values are text; labels keep footnote markers
70
+ ("Children1", "All other countries1"); the footnotes, Notes and Source lines are in the fetch notes.
71
+ - **Codes are not numbers**: `D` = data withheld to limit disclosure, `-` = zero (in some older tables "zero or not
72
+ available"), `X` = not applicable, `NA` = not available. The note counts each code found. Treat them as missing,
73
+ never as 0 unless the footnote says zero.
74
+ - **Rounding and revisions.** The FY2024 LPR and nonimmigrant workbooks, the FY2023 enforcement workbook and the
75
+ FY2025 quarterly report round every cell to the nearest 10 ("Totals may not sum due to rounding"); the FY2019
76
+ workbooks give exact counts with `D` cells (verified on those files; other years unchecked). Each yearbook
77
+ re-publishes 10 years of history from the current system of record, so earlier years change between editions
78
+ (FY2019 LPR total 1,031,765 in the FY2019 file, 1,031,770 in the FY2024 file). Take a series from one edition.
79
+ - **Fiscal years**: October 1 to September 30 (FY2024 = Oct 2023-Sep 2024). FY1976 includes 15 months (July 1975 to
80
+ September 1976).
81
+ - **LPR counts**: "persons obtaining lawful permanent resident status" = adjustments of status (already in the
82
+ U.S.) plus new arrivals (immigrant visas from abroad). FY2024: 1,364,090 total = 782,800 adjustments + 581,290
83
+ new arrivals (Table 6/7). Refugees and asylees appear when they adjust to LPR status (possible after a year in the
84
+ U.S.), not when they arrive or are granted asylum: refugee *arrivals* (Tables 13-15) and LPR *refugee adjustments* (Table 6) are different counts.
85
+ Classes: immediate relatives of U.S. citizens (no numerical cap), family-sponsored preferences, employment-based
86
+ preferences, diversity, refugees, asylees, other; Table 7 gives the detailed class codes.
87
+ - **Country**: LPR and naturalization tables use country of birth (and LPR Tables 2/11 last residence); refugee,
88
+ asylee, enforcement tables and the quarterly report use country of nationality; nonimmigrant tables use country
89
+ of citizenship or residence. They are not interchangeable.
90
+ - **Events, not people**: nonimmigrant admissions count arrival events ("not unique individuals"; repeat visits
91
+ count again; most short-term land admissions from Canada and Mexico are excluded); Table 26's "Total all
92
+ admissions" is an estimate rounded to the nearest 100,000, while the I-94 rows are counts. Apprehensions,
93
+ encounters, removals and returns are events: one person can be counted more than once in a year. Removals are
94
+ based on an order of removal; returns are not; Title 42 expulsions (COVID-19 public health grounds) are a separate column.
95
+ - **Quarterly report (`lir_table`)**: preliminary (data available one month after the quarter), revised in later
96
+ editions; final annual counts come in the yearbook (FY2025 report: 1,320,080 LPRs through quarter 4).
97
+ - New classes appear over time (E1S/E1Y, L2S/L2Y from January 2022): a class absent in early years may be folded
98
+ into another (see the footnotes).
99
+
100
+ ## Access
101
+ No key, no API: the pack reads public pages and workbooks on ohss.dhs.gov (1 request a second). File names carry
102
+ upload dates and are re-posted with new names after revisions, so the pack scrapes the year page each run and the
103
+ manual item names the file found. The site sits behind Akamai, which refused this pack's scripted requests with
104
+ HTTP 403 from one machine on 2026-10-30 while a browser read the same pages: a 403 ends the fetch with
105
+ `agency_unavailable`, and `manual_bundle` then gives the manual route. The bundle links the workbook a fetch in the
106
+ same server process found on the page within the last hour; otherwise it links the year page and the link text to
107
+ look for.
108
+
109
+ Manual download: open https://ohss.dhs.gov/topics/immigration/yearbook, choose the fiscal year ("About the 2024
110
+ Yearbook"), and download the topic's data tables file (e.g. "Lawful Permanent Residents 2024 Data Tables (xlsx)";
111
+ FY2015-2021 offer a .zip; "Expanded ... Tables 8-11" is in the Download Data list at the bottom). For the quarterly
112
+ report open https://ohss.dhs.gov/topics/immigration/legal-immigration-and-adjustment-status-report and download the
113
+ fiscal year's .xlsx. Upload the file unchanged under the name in INSTRUCTIONS.md; `ingest` reads the requested
114
+ sheet the same way as `fetch`.
115
+
116
+ ## Citation and terms
117
+ U.S. Department of Homeland Security, Office of Homeland Security Statistics, <Yearbook of Immigration Statistics
118
+ FY2024, Table 6 | Legal Immigration and Adjustment of Status Report FY2025>, ohss.dhs.gov, retrieved <date>.
119
+ Name the edition (fiscal year of the yearbook) and the table. Public domain (U.S. government work, 17 U.S.C. 105):
120
+ tables and data may be redistributed. No required notice.