data-analyst-mcp 0.3.0 → 0.4.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (292) hide show
  1. package/README.md +286 -262
  2. package/dist/adapters/bjs.d.ts +13 -0
  3. package/dist/adapters/bjs.js +28 -0
  4. package/dist/adapters/bjs.js.map +1 -0
  5. package/dist/adapters/cbp.d.ts +5 -0
  6. package/dist/adapters/cbp.js +64 -0
  7. package/dist/adapters/cbp.js.map +1 -0
  8. package/dist/adapters/cdc-wonder.d.ts +5 -0
  9. package/dist/adapters/cdc-wonder.js +68 -0
  10. package/dist/adapters/cdc-wonder.js.map +1 -0
  11. package/dist/adapters/cpsc.d.ts +4 -0
  12. package/dist/adapters/cpsc.js +125 -0
  13. package/dist/adapters/cpsc.js.map +1 -0
  14. package/dist/adapters/fhwa.d.ts +9 -0
  15. package/dist/adapters/fhwa.js +16 -0
  16. package/dist/adapters/fhwa.js.map +1 -0
  17. package/dist/adapters/foreign-assistance.d.ts +9 -0
  18. package/dist/adapters/foreign-assistance.js +42 -0
  19. package/dist/adapters/foreign-assistance.js.map +1 -0
  20. package/dist/adapters/hud-ahar.d.ts +3 -0
  21. package/dist/adapters/hud-ahar.js +80 -0
  22. package/dist/adapters/hud-ahar.js.map +1 -0
  23. package/dist/adapters/nces.d.ts +10 -0
  24. package/dist/adapters/nces.js +32 -0
  25. package/dist/adapters/nces.js.map +1 -0
  26. package/dist/adapters/nsf.d.ts +11 -0
  27. package/dist/adapters/nsf.js +25 -0
  28. package/dist/adapters/nsf.js.map +1 -0
  29. package/dist/adapters/onrr.d.ts +9 -0
  30. package/dist/adapters/onrr.js +35 -0
  31. package/dist/adapters/onrr.js.map +1 -0
  32. package/dist/adapters/sba.d.ts +10 -0
  33. package/dist/adapters/sba.js +134 -0
  34. package/dist/adapters/sba.js.map +1 -0
  35. package/dist/adapters/treasury-tic.d.ts +30 -0
  36. package/dist/adapters/treasury-tic.js +149 -0
  37. package/dist/adapters/treasury-tic.js.map +1 -0
  38. package/dist/adapters/uscourts.d.ts +8 -0
  39. package/dist/adapters/uscourts.js +8 -0
  40. package/dist/adapters/uscourts.js.map +1 -0
  41. package/dist/analysis/cite.d.ts +9 -1
  42. package/dist/analysis/cite.js +9 -2
  43. package/dist/analysis/cite.js.map +1 -1
  44. package/dist/bin/cli.d.ts +2 -0
  45. package/dist/bin/cli.js +17 -0
  46. package/dist/bin/cli.js.map +1 -1
  47. package/dist/core/generic-rest.js +42 -17
  48. package/dist/core/generic-rest.js.map +1 -1
  49. package/dist/core/guard.d.ts +32 -0
  50. package/dist/core/guard.js +176 -0
  51. package/dist/core/guard.js.map +1 -0
  52. package/dist/core/http.d.ts +10 -0
  53. package/dist/core/http.js +36 -7
  54. package/dist/core/http.js.map +1 -1
  55. package/dist/core/keys.d.ts +13 -3
  56. package/dist/core/keys.js +67 -7
  57. package/dist/core/keys.js.map +1 -1
  58. package/dist/core/package.d.ts +12 -3
  59. package/dist/core/package.js +56 -12
  60. package/dist/core/package.js.map +1 -1
  61. package/dist/core/secret_patterns.d.ts +6 -0
  62. package/dist/core/secret_patterns.js +20 -0
  63. package/dist/core/secret_patterns.js.map +1 -0
  64. package/dist/core/tabular.d.ts +43 -1
  65. package/dist/core/tabular.js +149 -6
  66. package/dist/core/tabular.js.map +1 -1
  67. package/dist/envelope.js +3 -1
  68. package/dist/envelope.js.map +1 -1
  69. package/dist/index.d.ts +29 -22
  70. package/dist/index.js +45 -46
  71. package/dist/index.js.map +1 -1
  72. package/dist/remote/app.js +87 -31
  73. package/dist/remote/app.js.map +1 -1
  74. package/dist/remote/oauth.js +8 -1
  75. package/dist/remote/oauth.js.map +1 -1
  76. package/dist/remote/pages.d.ts +3 -7
  77. package/dist/remote/pages.js +49 -19
  78. package/dist/remote/pages.js.map +1 -1
  79. package/dist/remote/sign.d.ts +7 -1
  80. package/dist/remote/sign.js +33 -7
  81. package/dist/remote/sign.js.map +1 -1
  82. package/dist/remote/store.js +14 -5
  83. package/dist/remote/store.js.map +1 -1
  84. package/dist/report/audit_report.js +29 -7
  85. package/dist/report/audit_report.js.map +1 -1
  86. package/dist/report/build_report.js +34 -4
  87. package/dist/report/build_report.js.map +1 -1
  88. package/dist/report/method_audit.js +10 -1
  89. package/dist/report/method_audit.js.map +1 -1
  90. package/dist/report/scan_secrets.d.ts +4 -1
  91. package/dist/report/scan_secrets.js +38 -18
  92. package/dist/report/scan_secrets.js.map +1 -1
  93. package/dist/server.d.ts +3 -1
  94. package/dist/server.js +46 -13
  95. package/dist/server.js.map +1 -1
  96. package/dist/tools.js +27 -6
  97. package/dist/tools.js.map +1 -1
  98. package/guide/WORKFLOW.md +134 -134
  99. package/guide/assets/disclaimer.txt +1 -1
  100. package/guide/assets/download_data.ps1 +164 -162
  101. package/guide/assets/download_data.sh +8 -2
  102. package/guide/assets/report_template.html +597 -597
  103. package/guide/references/routing.md +198 -171
  104. package/guide/references/style_guide.md +398 -398
  105. package/package.json +56 -56
  106. package/packs/acf/endpoints.json +114 -114
  107. package/packs/acf/policy.json +104 -104
  108. package/packs/actuaries/endpoints.json +82 -82
  109. package/packs/actuaries/policy.json +109 -109
  110. package/packs/bea/assets/download_bea.ps1 +182 -182
  111. package/packs/bea/docs/bea_api.md +461 -461
  112. package/packs/bea/docs/datasets.md +157 -157
  113. package/packs/bea/docs/report_patterns.md +112 -112
  114. package/packs/bea/policy.json +170 -170
  115. package/packs/bea/source.md +152 -152
  116. package/packs/bjs/endpoints.json +150 -0
  117. package/packs/bjs/policy.json +114 -0
  118. package/packs/bjs/source.md +98 -0
  119. package/packs/bls/assets/download_bls.ps1 +152 -152
  120. package/packs/bls/docs/analysis_patterns.md +108 -108
  121. package/packs/bls/docs/bls_api.md +73 -73
  122. package/packs/bls/docs/series_ids.md +149 -149
  123. package/packs/bls/policy.json +238 -238
  124. package/packs/bts/endpoints.json +346 -346
  125. package/packs/bts/policy.json +94 -94
  126. package/packs/cbp/endpoints.json +31 -0
  127. package/packs/cbp/policy.json +85 -0
  128. package/packs/cbp/source.md +57 -0
  129. package/packs/cdc/endpoints.json +197 -197
  130. package/packs/cdc/policy.json +83 -83
  131. package/packs/cdc/source.md +1 -1
  132. package/packs/cdc-wonder/endpoints.json +26 -0
  133. package/packs/cdc-wonder/policy.json +84 -0
  134. package/packs/cdc-wonder/source.md +53 -0
  135. package/packs/census/endpoints.json +99 -99
  136. package/packs/cfpb/endpoints.json +326 -326
  137. package/packs/cfpb/policy.json +119 -119
  138. package/packs/clinical-trials/endpoints.json +166 -166
  139. package/packs/clinical-trials/policy.json +84 -84
  140. package/packs/cms/endpoints.json +69 -69
  141. package/packs/cms/policy.json +96 -96
  142. package/packs/college-scorecard/endpoints.json +252 -252
  143. package/packs/college-scorecard/policy.json +106 -106
  144. package/packs/college-scorecard/source.md +1 -1
  145. package/packs/congress/endpoints.json +1701 -1701
  146. package/packs/congress/policy.json +117 -117
  147. package/packs/cpsc/endpoints.json +91 -0
  148. package/packs/cpsc/policy.json +91 -0
  149. package/packs/cpsc/source.md +76 -0
  150. package/packs/dhs-ohss/endpoints.json +66 -66
  151. package/packs/dhs-ohss/policy.json +107 -107
  152. package/packs/dhs-ohss/source.md +1 -1
  153. package/packs/doj-news/endpoints.json +59 -59
  154. package/packs/doj-news/policy.json +96 -96
  155. package/packs/doj-news/source.md +1 -1
  156. package/packs/dol/endpoints.json +817 -817
  157. package/packs/dol/policy.json +135 -135
  158. package/packs/eia/endpoints.json +717 -717
  159. package/packs/eia/policy.json +112 -112
  160. package/packs/epa/endpoints.json +291 -291
  161. package/packs/epa/policy.json +99 -99
  162. package/packs/epa-aqs/endpoints.json +173 -173
  163. package/packs/epa-aqs/policy.json +96 -96
  164. package/packs/fbi/endpoints.json +1841 -1841
  165. package/packs/fbi/policy.json +118 -118
  166. package/packs/fbi/source.md +3 -3
  167. package/packs/fda/endpoints.json +237 -237
  168. package/packs/fda/policy.json +121 -121
  169. package/packs/fdic/endpoints.json +416 -416
  170. package/packs/fdic/policy.json +83 -83
  171. package/packs/fec/endpoints.json +707 -707
  172. package/packs/fec/policy.json +93 -93
  173. package/packs/fed-board/endpoints.json +89 -89
  174. package/packs/fed-board/policy.json +136 -136
  175. package/packs/federal-register/endpoints.json +143 -143
  176. package/packs/federal-register/policy.json +86 -86
  177. package/packs/fema/endpoints.json +645 -645
  178. package/packs/fema/policy.json +103 -103
  179. package/packs/fhfa/endpoints.json +105 -105
  180. package/packs/fhfa/policy.json +109 -109
  181. package/packs/fhwa/endpoints.json +48 -0
  182. package/packs/fhwa/policy.json +91 -0
  183. package/packs/fhwa/source.md +59 -0
  184. package/packs/foreign-assistance/endpoints.json +166 -0
  185. package/packs/foreign-assistance/policy.json +80 -0
  186. package/packs/foreign-assistance/source.md +76 -0
  187. package/packs/fred/assets/download_fred.ps1 +122 -122
  188. package/packs/fred/docs/analysis_patterns.md +124 -124
  189. package/packs/fred/docs/fred_api.md +94 -94
  190. package/packs/fred/docs/series.md +188 -188
  191. package/packs/fred/policy.json +253 -253
  192. package/packs/fsa/endpoints.json +150 -150
  193. package/packs/fsa/policy.json +99 -99
  194. package/packs/fsa/source.md +1 -1
  195. package/packs/govinfo/endpoints.json +519 -519
  196. package/packs/gsa-calc/endpoints.json +93 -93
  197. package/packs/gsa-calc/policy.json +97 -97
  198. package/packs/hud/endpoints.json +146 -146
  199. package/packs/hud/policy.json +84 -84
  200. package/packs/hud/source.md +1 -1
  201. package/packs/hud-ahar/endpoints.json +92 -0
  202. package/packs/hud-ahar/policy.json +88 -0
  203. package/packs/hud-ahar/source.md +72 -0
  204. package/packs/ipums/docs/report_patterns.md +117 -117
  205. package/packs/irs-soi/endpoints.json +114 -114
  206. package/packs/irs-soi/policy.json +107 -107
  207. package/packs/medicaid/endpoints.json +412 -412
  208. package/packs/medicaid/policy.json +108 -108
  209. package/packs/naep/endpoints.json +217 -217
  210. package/packs/naep/policy.json +100 -100
  211. package/packs/naep/source.md +1 -1
  212. package/packs/nces/endpoints.json +101 -0
  213. package/packs/nces/policy.json +99 -0
  214. package/packs/nces/source.md +75 -0
  215. package/packs/nhtsa/endpoints.json +132 -132
  216. package/packs/nhtsa/policy.json +93 -93
  217. package/packs/nhtsa/source.md +1 -1
  218. package/packs/nih/endpoints.json +452 -452
  219. package/packs/nih/policy.json +86 -86
  220. package/packs/noaa/endpoints.json +431 -431
  221. package/packs/noaa/policy.json +95 -95
  222. package/packs/nrel/endpoints.json +327 -327
  223. package/packs/nrel/policy.json +96 -96
  224. package/packs/nsf/endpoints.json +33 -0
  225. package/packs/nsf/policy.json +83 -0
  226. package/packs/nsf/source.md +59 -0
  227. package/packs/nws/endpoints.json +271 -271
  228. package/packs/nws/policy.json +82 -82
  229. package/packs/nyfed/endpoints.json +80 -80
  230. package/packs/nyfed/policy.json +92 -92
  231. package/packs/omb/endpoints.json +460 -460
  232. package/packs/omb/policy.json +106 -106
  233. package/packs/onrr/endpoints.json +198 -0
  234. package/packs/onrr/policy.json +91 -0
  235. package/packs/onrr/source.md +55 -0
  236. package/packs/open-payments/endpoints.json +297 -297
  237. package/packs/open-payments/policy.json +101 -101
  238. package/packs/opm/assets/download_opm.ps1 +125 -125
  239. package/packs/opm/docs/fields.md +184 -184
  240. package/packs/opm/docs/opm_api.md +71 -71
  241. package/packs/opm/docs/report_patterns.md +83 -83
  242. package/packs/opm/lib/data_dictionary.csv +73 -73
  243. package/packs/pbgc/endpoints.json +483 -483
  244. package/packs/pbgc/policy.json +94 -94
  245. package/packs/philfed/endpoints.json +85 -85
  246. package/packs/philfed/policy.json +94 -94
  247. package/packs/port.json +65 -0
  248. package/packs/regulations/endpoints.json +287 -287
  249. package/packs/regulations/policy.json +86 -86
  250. package/packs/sba/endpoints.json +34 -0
  251. package/packs/sba/policy.json +86 -0
  252. package/packs/sba/source.md +60 -0
  253. package/packs/sec/endpoints.json +236 -236
  254. package/packs/sec/policy.json +86 -86
  255. package/packs/senate-lobbying/endpoints.json +553 -553
  256. package/packs/senate-lobbying/policy.json +99 -99
  257. package/packs/snapqc/endpoints.json +1426 -1426
  258. package/packs/snapqc/policy.json +92 -92
  259. package/packs/treasury/catalog.json +2267 -2267
  260. package/packs/treasury/docs/api_guide.md +245 -245
  261. package/packs/treasury/docs/datasets.md +56 -56
  262. package/packs/treasury/docs/report_patterns.md +126 -126
  263. package/packs/treasury/policy.json +159 -159
  264. package/packs/treasury/source.md +170 -165
  265. package/packs/treasury-tic/endpoints.json +77 -0
  266. package/packs/treasury-tic/policy.json +89 -0
  267. package/packs/treasury-tic/source.md +80 -0
  268. package/packs/treasury-yields/endpoints.json +226 -226
  269. package/packs/treasury-yields/policy.json +86 -86
  270. package/packs/usaspending/endpoints.json +1315 -1315
  271. package/packs/usaspending/policy.json +109 -109
  272. package/packs/uscourts/endpoints.json +22 -0
  273. package/packs/uscourts/policy.json +87 -0
  274. package/packs/uscourts/source.md +56 -0
  275. package/packs/usda-fna/policy.json +133 -133
  276. package/packs/usda-fooddata/endpoints.json +180 -180
  277. package/packs/usda-fooddata/policy.json +94 -94
  278. package/packs/usda-nass/endpoints.json +323 -323
  279. package/packs/usda-nass/policy.json +95 -95
  280. package/packs/usda-outlook/endpoints.json +86 -86
  281. package/packs/usda-outlook/policy.json +109 -109
  282. package/packs/usgs/endpoints.json +313 -313
  283. package/packs/usgs/policy.json +95 -95
  284. package/packs/usitc/endpoints.json +74 -74
  285. package/packs/usitc/policy.json +111 -111
  286. package/packs/uspto/endpoints.json +141 -141
  287. package/packs/uspto/policy.json +95 -95
  288. package/packs/uspto/source.md +1 -1
  289. package/packs/va/endpoints.json +414 -414
  290. package/packs/va/policy.json +101 -101
  291. package/packs/world-bank/endpoints.json +122 -122
  292. package/packs/world-bank/policy.json +101 -101
@@ -1,94 +1,94 @@
1
- {
2
- "id": "bts",
3
- "title": "Bureau of Transportation Statistics Open Data (data.bts.gov)",
4
- "agency": "U.S. Department of Transportation, Bureau of Transportation Statistics",
5
- "depth": "standard",
6
- "domains": [
7
- "transportation",
8
- "freight",
9
- "travel"
10
- ],
11
- "keywords": [
12
- "transportation",
13
- "airline",
14
- "air traffic",
15
- "passengers",
16
- "on-time",
17
- "transit ridership",
18
- "freight rail",
19
- "rail",
20
- "truck tonnage",
21
- "vehicle miles traveled",
22
- "vmt",
23
- "gasoline price",
24
- "diesel",
25
- "auto sales",
26
- "fatalities",
27
- "transportation services index",
28
- "tsi",
29
- "border crossing",
30
- "port of entry",
31
- "trucks",
32
- "pedestrians",
33
- "air fare",
34
- "airfare",
35
- "bikeshare",
36
- "container port",
37
- "teu",
38
- "motor fuel"
39
- ],
40
- "questions": [
41
- "monthly airline passenger traffic trend",
42
- "Transportation Services Index freight since 2019",
43
- "truck crossings at the Texas-Mexico border by port",
44
- "average domestic air fare by quarter",
45
- "transit ridership recovery after 2020"
46
- ],
47
- "homepage": "https://data.bts.gov/",
48
- "terms_url": "https://www.bts.gov/policies-and-notices",
49
- "auth": {
50
- "env": null,
51
- "required": "none",
52
- "placement": "none",
53
- "signup_url": null,
54
- "echoes_key": false
55
- },
56
- "limits": {
57
- "rps": 2,
58
- "burst": 5,
59
- "max_rows": 200000
60
- },
61
- "routes": {
62
- "api": {
63
- "base": "https://data.bts.gov/resource",
64
- "probe": "https://data.bts.gov/resource/crem-w557.json?$limit=1",
65
- "hosts": [
66
- "data.bts.gov"
67
- ]
68
- },
69
- "manual": {
70
- "how": "Open the dataset page (https://data.bts.gov/d/<id>, e.g. https://data.bts.gov/d/crem-w557), choose Export > CSV, and upload the file; or open the CSV links in INSTRUCTIONS.md."
71
- }
72
- },
73
- "cache": {
74
- "mode": "run_only",
75
- "ttl_hours": null,
76
- "why": "Queries are small and the monthly series are revised each release; data/ is reused within a run."
77
- },
78
- "redistribution": {
79
- "mode": "allowed",
80
- "why": "BTS statistics are U.S. government works in the public domain (17 U.S.C. 105); BTS asks for source attribution."
81
- },
82
- "notices": [],
83
- "retention": null,
84
- "citation": "Bureau of Transportation Statistics, {dataset}, data.bts.gov (Socrata API), retrieved {retrieved_long}.",
85
- "audit_hooks": [],
86
- "clarify": [
87
- "Seasonally adjusted or not? Monthly Transportation Statistics carries both versions of airline traffic and transit ridership in different columns.",
88
- "Border crossings: which measure (Trucks, Personal Vehicles, Personal Vehicle Passengers, Pedestrians, ...) and which border? Counts are inbound only."
89
- ],
90
- "formats": [
91
- "json",
92
- "csv"
93
- ]
94
- }
1
+ {
2
+ "id": "bts",
3
+ "title": "Bureau of Transportation Statistics Open Data (data.bts.gov)",
4
+ "agency": "U.S. Department of Transportation, Bureau of Transportation Statistics",
5
+ "depth": "standard",
6
+ "domains": [
7
+ "transportation",
8
+ "freight",
9
+ "travel"
10
+ ],
11
+ "keywords": [
12
+ "transportation",
13
+ "airline",
14
+ "air traffic",
15
+ "passengers",
16
+ "on-time",
17
+ "transit ridership",
18
+ "freight rail",
19
+ "rail",
20
+ "truck tonnage",
21
+ "vehicle miles traveled",
22
+ "vmt",
23
+ "gasoline price",
24
+ "diesel",
25
+ "auto sales",
26
+ "fatalities",
27
+ "transportation services index",
28
+ "tsi",
29
+ "border crossing",
30
+ "port of entry",
31
+ "trucks",
32
+ "pedestrians",
33
+ "air fare",
34
+ "airfare",
35
+ "bikeshare",
36
+ "container port",
37
+ "teu",
38
+ "motor fuel"
39
+ ],
40
+ "questions": [
41
+ "monthly airline passenger traffic trend",
42
+ "Transportation Services Index freight since 2019",
43
+ "truck crossings at the Texas-Mexico border by port",
44
+ "average domestic air fare by quarter",
45
+ "transit ridership recovery after 2020"
46
+ ],
47
+ "homepage": "https://data.bts.gov/",
48
+ "terms_url": "https://www.bts.gov/policies-and-notices",
49
+ "auth": {
50
+ "env": null,
51
+ "required": "none",
52
+ "placement": "none",
53
+ "signup_url": null,
54
+ "echoes_key": false
55
+ },
56
+ "limits": {
57
+ "rps": 2,
58
+ "burst": 5,
59
+ "max_rows": 200000
60
+ },
61
+ "routes": {
62
+ "api": {
63
+ "base": "https://data.bts.gov/resource",
64
+ "probe": "https://data.bts.gov/resource/crem-w557.json?$limit=1",
65
+ "hosts": [
66
+ "data.bts.gov"
67
+ ]
68
+ },
69
+ "manual": {
70
+ "how": "Open the dataset page (https://data.bts.gov/d/<id>, e.g. https://data.bts.gov/d/crem-w557), choose Export > CSV, and upload the file; or open the CSV links in INSTRUCTIONS.md."
71
+ }
72
+ },
73
+ "cache": {
74
+ "mode": "run_only",
75
+ "ttl_hours": null,
76
+ "why": "Queries are small and the monthly series are revised each release; data/ is reused within a run."
77
+ },
78
+ "redistribution": {
79
+ "mode": "allowed",
80
+ "why": "BTS statistics are U.S. government works in the public domain (17 U.S.C. 105); BTS asks for source attribution."
81
+ },
82
+ "notices": [],
83
+ "retention": null,
84
+ "citation": "Bureau of Transportation Statistics, {dataset}, data.bts.gov (Socrata API), retrieved {retrieved_long}.",
85
+ "audit_hooks": [],
86
+ "clarify": [
87
+ "Seasonally adjusted or not? Monthly Transportation Statistics carries both versions of airline traffic and transit ridership in different columns.",
88
+ "Border crossings: which measure (Trucks, Personal Vehicles, Personal Vehicle Passengers, Pedestrians, ...) and which border? Counts are inbound only."
89
+ ],
90
+ "formats": [
91
+ "json",
92
+ "csv"
93
+ ]
94
+ }
@@ -0,0 +1,31 @@
1
+ {
2
+ "base_url": "https://www.cbp.gov",
3
+ "timeout": 120,
4
+ "document_page": "/document/stats/nationwide-encounters",
5
+ "endpoints": {
6
+ "list_files": {
7
+ "path": "/document/stats/nationwide-encounters",
8
+ "method": "GET",
9
+ "description": "The encounter data files CBP currently publishes (read from its Nationwide Encounters document page): one row per CSV with its path for the encounters request. The files are replaced every month.",
10
+ "params": {},
11
+ "records": "",
12
+ "paging": {"type": "none"},
13
+ "max_rows": 1000
14
+ },
15
+ "encounters": {
16
+ "path": "/sites/default/files/{file}.csv",
17
+ "method": "GET",
18
+ "description": "Nationwide encounters (OFO inadmissibles and Border Patrol apprehensions under Title 8) by fiscal year and month, component, land border region, area of responsibility or state, demographic and citizenship. Use list_files for the current file paths.",
19
+ "params": {
20
+ "file": {"in": "path", "raw": true, "required": true, "desc": "the file's path under /sites/default/files without .csv, from list_files, e.g. 2026-11/nationwide-encounters-fy24-fy27-oct-aor"},
21
+ "region": {"in": "spec", "desc": "keep these Land Border Region values: Southwest Land Border, Northern Land Border, Other"},
22
+ "component": {"in": "spec", "desc": "keep Office of Field Operations or U.S. Border Patrol"},
23
+ "fiscal_year": {"in": "spec", "desc": "keep these fiscal years as published (2025; the current year is '2027 (FYTD)')"},
24
+ "citizenship": {"in": "spec", "desc": "keep these citizenships as published (MEXICO, VENEZUELA ...)"}
25
+ },
26
+ "records": "$csv",
27
+ "paging": {"type": "none"},
28
+ "max_rows": 500000
29
+ }
30
+ }
31
+ }
@@ -0,0 +1,85 @@
1
+ {
2
+ "id": "cbp",
3
+ "title": "CBP nationwide encounters: border apprehensions and inadmissibles by month, region, demographic and citizenship",
4
+ "agency": "U.S. Department of Homeland Security, Customs and Border Protection",
5
+ "depth": "standard",
6
+ "domains": [
7
+ "immigration",
8
+ "border security"
9
+ ],
10
+ "keywords": [
11
+ "cbp",
12
+ "customs and border protection",
13
+ "border encounters",
14
+ "southwest border",
15
+ "border crossings",
16
+ "border apprehensions",
17
+ "border patrol",
18
+ "inadmissibles",
19
+ "migrant encounters",
20
+ "unaccompanied children",
21
+ "uac",
22
+ "family units",
23
+ "northern border",
24
+ "office of field operations"
25
+ ],
26
+ "questions": [
27
+ "southwest border encounters by month",
28
+ "border apprehensions this year vs last year",
29
+ "encounters by citizenship (e.g. Venezuela, Mexico)",
30
+ "unaccompanied children encountered at the border",
31
+ "encounters by state or Border Patrol sector"
32
+ ],
33
+ "homepage": "https://www.cbp.gov/newsroom/stats/nationwide-encounters",
34
+ "terms_url": "https://www.cbp.gov/document/stats/nationwide-encounters",
35
+ "auth": {
36
+ "env": null,
37
+ "required": "none",
38
+ "placement": "none",
39
+ "signup_url": null,
40
+ "echoes_key": false
41
+ },
42
+ "limits": {
43
+ "rps": 1,
44
+ "burst": 2,
45
+ "max_rows": 500000
46
+ },
47
+ "routes": {
48
+ "api": {
49
+ "base": "https://www.cbp.gov",
50
+ "probe": "https://www.cbp.gov/document/stats/nationwide-encounters",
51
+ "hosts": [
52
+ "www.cbp.gov"
53
+ ]
54
+ },
55
+ "manual": {
56
+ "how": "Open https://www.cbp.gov/document/stats/nationwide-encounters, download the newest 'Nationwide Encounters' CSV (by AOR or by state), and upload it with ingest."
57
+ }
58
+ },
59
+ "cache": {
60
+ "mode": "run_only",
61
+ "ttl_hours": null,
62
+ "why": "Files are replaced monthly, with revisions to earlier months."
63
+ },
64
+ "redistribution": {
65
+ "mode": "allowed",
66
+ "why": "CBP statistics are U.S. government works in the public domain (17 U.S.C. 105)."
67
+ },
68
+ "notices": [],
69
+ "retention": null,
70
+ "citation": "U.S. Customs and Border Protection, Nationwide Encounters ({dataset}), cbp.gov, retrieved {retrieved_long}.",
71
+ "audit_hooks": [],
72
+ "clarify": [
73
+ "Which encounters? Southwest Land Border, Northern Land Border, or nationwide (including Other: airports and seaports); Border Patrol apprehensions between ports or OFO inadmissibles at ports, or both. Default: Southwest Land Border, both components, said as such.",
74
+ "Which months? Federal fiscal years (October-September); the current year is partial (FYTD). Default: the latest month and the same month a year earlier."
75
+ ],
76
+ "formats": [
77
+ "csv",
78
+ "html"
79
+ ],
80
+ "aliases": [
81
+ "CBP",
82
+ "Customs and Border Protection",
83
+ "Border Patrol"
84
+ ]
85
+ }
@@ -0,0 +1,57 @@
1
+ # CBP nationwide encounters: border apprehensions and inadmissibles by month, region, demographic and citizenship
2
+ Depth: standard. Key: none. U.S. Customs and Border Protection's monthly Nationwide Encounters data files (the CSVs
3
+ behind CBP's encounters dashboard). They count Border Patrol apprehensions (between ports of entry) and Office of
4
+ Field Operations inadmissibles (at ports of entry), under Title 8. Breakdowns: fiscal year and month, land border
5
+ region, area of responsibility (Border Patrol sector or field office) or state, demographic and citizenship.
6
+
7
+ ## When to use
8
+ - Southwest border encounters by month; year-over-year change; encounters by citizenship, demographic (single
9
+ adults, family units, unaccompanied children, accompanied minors), component, sector or field office, or state.
10
+ - Not here: annual immigration statistics (green cards, refugees, naturalizations, removals: dhs-ohss); asylum
11
+ and immigration court cases (not covered); trade and customs duties (census, usitc, treasury).
12
+
13
+ ## Endpoints
14
+ | Endpoint | Returns | Parameters |
15
+ |---|---|---|
16
+ | `list_files` | the encounter CSVs on CBP's document page, newest first: `file`, `by` (area of responsibility or state), `fiscal_years`, `url` | none |
17
+ | `encounters` | one file's rows as published | `file` (from `list_files`), filters `region`, `component`, `fiscal_year`, `citizenship` |
18
+
19
+ Columns:
20
+ - By area of responsibility (`-aor`): Fiscal Year, Month Grouping, Month (abbv), Component, Land Border Region,
21
+ Area of Responsibility, AOR (Abbv), Demographic, Citizenship, Title of Authority, Encounter Type, Encounter
22
+ Count.
23
+ - By state (`-state`): Fiscal Year, Month Grouping, Month (abbv), Land Border Region, State, Demographic,
24
+ Citizenship, Title of Authority, Encounter Count.
25
+
26
+ ## Spec example
27
+ ```json
28
+ {"description": "Southwest border encounters by month, FY2024 to date (file of November 2026)",
29
+ "requests": [{"name": "files", "endpoint": "list_files"},
30
+ {"name": "swb", "endpoint": "encounters",
31
+ "params": {"file": "2026-11/nationwide-encounters-fy24-fy27-oct-aor", "region": "Southwest Land Border"}}]}
32
+ ```
33
+ Run `list_files` first: the newest file is replaced every month (paths verified 2026-11-07).
34
+
35
+ ## Data format and traps
36
+ - Each file covers about four fiscal years, the last one partial (`2027 (FYTD)`). Earlier months are revised in
37
+ later files: use the newest file, and do not mix files.
38
+ - `Month Grouping` is `FYTD` for the months that fall in the current fiscal year-to-date period, marked in every
39
+ year for comparison (only OCT in the November 2026 file), and `Remaining` for the others. Months are abbreviations (`OCT` ... `SEP`), and the fiscal year starts in October. Build a
40
+ date before plotting (FY2025 OCT = October 2024).
41
+ - Encounters are events, not people: one person can be encountered more than once.
42
+ - OFO inadmissibles and Border Patrol apprehensions are different events. Add them only for "total
43
+ encounters", and say so.
44
+ - `Land Border Region` `Other` holds encounters away from land borders (airports, seaports, coastal).
45
+ - `Citizenship` lists the main countries and groups the rest as `OTHER`: a country absent from the list is
46
+ inside OTHER, not zero. Demographic codes: `FMUA` is individuals in family units, `UAC` unaccompanied children,
47
+ plus Single Adults and Accompanied Minors.
48
+ - Counts are text; sum with `Number()`. Every row of the November 2026 files is Title 8: older files also have
49
+ Title 42 expulsions (March 2020 to May 2023), which are encounters too.
50
+
51
+ ## Access
52
+ No key. `fetch` reads www.cbp.gov (verified 2026-11-07; the files are 2-5 MB). Manual: the document page's CSV
53
+ links, then `ingest`.
54
+
55
+ ## Citation and terms
56
+ "U.S. Customs and Border Protection, Nationwide Encounters, <file name>, cbp.gov, retrieved <date>." Public
57
+ domain (17 U.S.C. 105).