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.
- package/README.md +262 -3
- package/dist/adapters/_acf_tidy.d.ts +18 -0
- package/dist/adapters/_acf_tidy.js +432 -0
- package/dist/adapters/_acf_tidy.js.map +1 -0
- package/dist/adapters/_actuaries_read.d.ts +38 -0
- package/dist/adapters/_actuaries_read.js +728 -0
- package/dist/adapters/_actuaries_read.js.map +1 -0
- package/dist/adapters/_census_micro.d.ts +70 -0
- package/dist/adapters/_census_micro.js +622 -0
- package/dist/adapters/_census_micro.js.map +1 -0
- package/dist/adapters/_census_util.d.ts +40 -0
- package/dist/adapters/_census_util.js +275 -0
- package/dist/adapters/_census_util.js.map +1 -0
- package/dist/adapters/_dol_states.d.ts +6 -0
- package/dist/adapters/_dol_states.js +58 -0
- package/dist/adapters/_dol_states.js.map +1 -0
- package/dist/adapters/_govinfo_entities.d.ts +4 -0
- package/dist/adapters/_govinfo_entities.js +6 -0
- package/dist/adapters/_govinfo_entities.js.map +1 -0
- package/dist/adapters/_govinfo_json.d.ts +13 -0
- package/dist/adapters/_govinfo_json.js +107 -0
- package/dist/adapters/_govinfo_json.js.map +1 -0
- package/dist/adapters/_govinfo_py.d.ts +22 -0
- package/dist/adapters/_govinfo_py.js +272 -0
- package/dist/adapters/_govinfo_py.js.map +1 -0
- package/dist/adapters/_govinfo_xml.d.ts +22 -0
- package/dist/adapters/_govinfo_xml.js +233 -0
- package/dist/adapters/_govinfo_xml.js.map +1 -0
- package/dist/adapters/_hud_excel.d.ts +2 -0
- package/dist/adapters/_hud_excel.js +166 -0
- package/dist/adapters/_hud_excel.js.map +1 -0
- package/dist/adapters/_omb_grid.d.ts +17 -0
- package/dist/adapters/_omb_grid.js +132 -0
- package/dist/adapters/_omb_grid.js.map +1 -0
- package/dist/adapters/_omb_util.d.ts +40 -0
- package/dist/adapters/_omb_util.js +192 -0
- package/dist/adapters/_omb_util.js.map +1 -0
- package/dist/adapters/_usaspending_state.d.ts +6 -0
- package/dist/adapters/_usaspending_state.js +54 -0
- package/dist/adapters/_usaspending_state.js.map +1 -0
- package/dist/adapters/_usda-fna_book.d.ts +59 -0
- package/dist/adapters/_usda-fna_book.js +869 -0
- package/dist/adapters/_usda-fna_book.js.map +1 -0
- package/dist/adapters/_usda-fna_pdf.d.ts +20 -0
- package/dist/adapters/_usda-fna_pdf.js +361 -0
- package/dist/adapters/_usda-fna_pdf.js.map +1 -0
- package/dist/adapters/_usda-outlook_read.d.ts +70 -0
- package/dist/adapters/_usda-outlook_read.js +362 -0
- package/dist/adapters/_usda-outlook_read.js.map +1 -0
- package/dist/adapters/acf.d.ts +3 -0
- package/dist/adapters/acf.js +187 -0
- package/dist/adapters/acf.js.map +1 -0
- package/dist/adapters/actuaries.d.ts +3 -0
- package/dist/adapters/actuaries.js +293 -0
- package/dist/adapters/actuaries.js.map +1 -0
- package/dist/adapters/bts.d.ts +3 -0
- package/dist/adapters/bts.js +26 -0
- package/dist/adapters/bts.js.map +1 -0
- package/dist/adapters/census-geocoder.d.ts +10 -0
- package/dist/adapters/census-geocoder.js +47 -0
- package/dist/adapters/census-geocoder.js.map +1 -0
- package/dist/adapters/census.d.ts +17 -0
- package/dist/adapters/census.js +983 -0
- package/dist/adapters/census.js.map +1 -0
- package/dist/adapters/cfpb.d.ts +7 -0
- package/dist/adapters/cfpb.js +348 -0
- package/dist/adapters/cfpb.js.map +1 -0
- package/dist/adapters/clinical-trials.d.ts +3 -0
- package/dist/adapters/clinical-trials.js +135 -0
- package/dist/adapters/clinical-trials.js.map +1 -0
- package/dist/adapters/cms.d.ts +3 -0
- package/dist/adapters/cms.js +292 -0
- package/dist/adapters/cms.js.map +1 -0
- package/dist/adapters/college-scorecard.d.ts +3 -0
- package/dist/adapters/college-scorecard.js +122 -0
- package/dist/adapters/college-scorecard.js.map +1 -0
- package/dist/adapters/congress.d.ts +33 -0
- package/dist/adapters/congress.js +589 -0
- package/dist/adapters/congress.js.map +1 -0
- package/dist/adapters/dhs-ohss.d.ts +13 -0
- package/dist/adapters/dhs-ohss.js +598 -0
- package/dist/adapters/dhs-ohss.js.map +1 -0
- package/dist/adapters/doj-news.d.ts +7 -0
- package/dist/adapters/doj-news.js +286 -0
- package/dist/adapters/doj-news.js.map +1 -0
- package/dist/adapters/dol.d.ts +4 -0
- package/dist/adapters/dol.js +634 -0
- package/dist/adapters/dol.js.map +1 -0
- package/dist/adapters/eia.d.ts +15 -0
- package/dist/adapters/eia.js +456 -0
- package/dist/adapters/eia.js.map +1 -0
- package/dist/adapters/epa-aqs.d.ts +3 -0
- package/dist/adapters/epa-aqs.js +357 -0
- package/dist/adapters/epa-aqs.js.map +1 -0
- package/dist/adapters/epa.d.ts +3 -0
- package/dist/adapters/epa.js +298 -0
- package/dist/adapters/epa.js.map +1 -0
- package/dist/adapters/fbi.d.ts +3 -0
- package/dist/adapters/fbi.js +192 -0
- package/dist/adapters/fbi.js.map +1 -0
- package/dist/adapters/fda.d.ts +5 -0
- package/dist/adapters/fda.js +184 -0
- package/dist/adapters/fda.js.map +1 -0
- package/dist/adapters/fdic.d.ts +4 -0
- package/dist/adapters/fdic.js +95 -0
- package/dist/adapters/fdic.js.map +1 -0
- package/dist/adapters/fec.d.ts +3 -0
- package/dist/adapters/fec.js +142 -0
- package/dist/adapters/fec.js.map +1 -0
- package/dist/adapters/fed-board.d.ts +12 -0
- package/dist/adapters/fed-board.js +581 -0
- package/dist/adapters/fed-board.js.map +1 -0
- package/dist/adapters/federal-register.d.ts +11 -0
- package/dist/adapters/federal-register.js +43 -0
- package/dist/adapters/federal-register.js.map +1 -0
- package/dist/adapters/fhfa.d.ts +3 -0
- package/dist/adapters/fhfa.js +253 -0
- package/dist/adapters/fhfa.js.map +1 -0
- package/dist/adapters/fsa.d.ts +9 -0
- package/dist/adapters/fsa.js +335 -0
- package/dist/adapters/fsa.js.map +1 -0
- package/dist/adapters/govinfo.d.ts +30 -0
- package/dist/adapters/govinfo.js +636 -0
- package/dist/adapters/govinfo.js.map +1 -0
- package/dist/adapters/gsa-calc.d.ts +10 -0
- package/dist/adapters/gsa-calc.js +318 -0
- package/dist/adapters/gsa-calc.js.map +1 -0
- package/dist/adapters/hud.d.ts +3 -0
- package/dist/adapters/hud.js +200 -0
- package/dist/adapters/hud.js.map +1 -0
- package/dist/adapters/index.d.ts +3 -0
- package/dist/adapters/index.js +25 -0
- package/dist/adapters/index.js.map +1 -0
- package/dist/adapters/irs-soi.d.ts +6 -0
- package/dist/adapters/irs-soi.js +576 -0
- package/dist/adapters/irs-soi.js.map +1 -0
- package/dist/adapters/naep.d.ts +15 -0
- package/dist/adapters/naep.js +341 -0
- package/dist/adapters/naep.js.map +1 -0
- package/dist/adapters/nhtsa.d.ts +10 -0
- package/dist/adapters/nhtsa.js +239 -0
- package/dist/adapters/nhtsa.js.map +1 -0
- package/dist/adapters/nih.d.ts +5 -0
- package/dist/adapters/nih.js +196 -0
- package/dist/adapters/nih.js.map +1 -0
- package/dist/adapters/noaa.d.ts +3 -0
- package/dist/adapters/noaa.js +148 -0
- package/dist/adapters/noaa.js.map +1 -0
- package/dist/adapters/nrel.d.ts +3 -0
- package/dist/adapters/nrel.js +186 -0
- package/dist/adapters/nrel.js.map +1 -0
- package/dist/adapters/nws.d.ts +3 -0
- package/dist/adapters/nws.js +119 -0
- package/dist/adapters/nws.js.map +1 -0
- package/dist/adapters/omb.d.ts +15 -0
- package/dist/adapters/omb.js +517 -0
- package/dist/adapters/omb.js.map +1 -0
- package/dist/adapters/open-payments.d.ts +5 -0
- package/dist/adapters/open-payments.js +149 -0
- package/dist/adapters/open-payments.js.map +1 -0
- package/dist/adapters/pbgc.d.ts +13 -0
- package/dist/adapters/pbgc.js +283 -0
- package/dist/adapters/pbgc.js.map +1 -0
- package/dist/adapters/philfed.d.ts +12 -0
- package/dist/adapters/philfed.js +59 -0
- package/dist/adapters/philfed.js.map +1 -0
- package/dist/adapters/regulations.d.ts +6 -0
- package/dist/adapters/regulations.js +58 -0
- package/dist/adapters/regulations.js.map +1 -0
- package/dist/adapters/sec.d.ts +13 -0
- package/dist/adapters/sec.js +504 -0
- package/dist/adapters/sec.js.map +1 -0
- package/dist/adapters/senate-lobbying.d.ts +3 -0
- package/dist/adapters/senate-lobbying.js +181 -0
- package/dist/adapters/senate-lobbying.js.map +1 -0
- package/dist/adapters/snapqc.d.ts +32 -0
- package/dist/adapters/snapqc.js +701 -0
- package/dist/adapters/snapqc.js.map +1 -0
- package/dist/adapters/treasury-yields.d.ts +3 -0
- package/dist/adapters/treasury-yields.js +170 -0
- package/dist/adapters/treasury-yields.js.map +1 -0
- package/dist/adapters/usaspending.d.ts +3 -0
- package/dist/adapters/usaspending.js +340 -0
- package/dist/adapters/usaspending.js.map +1 -0
- package/dist/adapters/usda-fna.d.ts +7 -0
- package/dist/adapters/usda-fna.js +707 -0
- package/dist/adapters/usda-fna.js.map +1 -0
- package/dist/adapters/usda-fooddata.d.ts +3 -0
- package/dist/adapters/usda-fooddata.js +101 -0
- package/dist/adapters/usda-fooddata.js.map +1 -0
- package/dist/adapters/usda-nass.d.ts +3 -0
- package/dist/adapters/usda-nass.js +108 -0
- package/dist/adapters/usda-nass.js.map +1 -0
- package/dist/adapters/usda-outlook.d.ts +12 -0
- package/dist/adapters/usda-outlook.js +696 -0
- package/dist/adapters/usda-outlook.js.map +1 -0
- package/dist/adapters/usgs.d.ts +9 -0
- package/dist/adapters/usgs.js +265 -0
- package/dist/adapters/usgs.js.map +1 -0
- package/dist/adapters/usitc.d.ts +18 -0
- package/dist/adapters/usitc.js +170 -0
- package/dist/adapters/usitc.js.map +1 -0
- package/dist/adapters/uspto.d.ts +3 -0
- package/dist/adapters/uspto.js +47 -0
- package/dist/adapters/uspto.js.map +1 -0
- package/dist/adapters/world-bank.d.ts +3 -0
- package/dist/adapters/world-bank.js +163 -0
- package/dist/adapters/world-bank.js.map +1 -0
- package/dist/analysis/cite.d.ts +31 -0
- package/dist/analysis/cite.js +229 -0
- package/dist/analysis/cite.js.map +1 -0
- package/dist/analysis/combine.d.ts +27 -0
- package/dist/analysis/combine.js +198 -0
- package/dist/analysis/combine.js.map +1 -0
- package/dist/analysis/compute.d.ts +62 -0
- package/dist/analysis/compute.js +583 -0
- package/dist/analysis/compute.js.map +1 -0
- package/dist/analysis/expr.d.ts +69 -0
- package/dist/analysis/expr.js +780 -0
- package/dist/analysis/expr.js.map +1 -0
- package/dist/analysis/factfmt.d.ts +16 -0
- package/dist/analysis/factfmt.js +187 -0
- package/dist/analysis/factfmt.js.map +1 -0
- package/dist/analysis/facts.d.ts +63 -0
- package/dist/analysis/facts.js +355 -0
- package/dist/analysis/facts.js.map +1 -0
- package/dist/analysis/handoff.d.ts +58 -0
- package/dist/analysis/handoff.js +208 -0
- package/dist/analysis/handoff.js.map +1 -0
- package/dist/analysis/pyfmt.d.ts +16 -0
- package/dist/analysis/pyfmt.js +156 -0
- package/dist/analysis/pyfmt.js.map +1 -0
- package/dist/analysis/rerun.d.ts +13 -0
- package/dist/analysis/rerun.js +125 -0
- package/dist/analysis/rerun.js.map +1 -0
- package/dist/analysis/table.d.ts +18 -0
- package/dist/analysis/table.js +109 -0
- package/dist/analysis/table.js.map +1 -0
- package/dist/analysis/tools.d.ts +67 -0
- package/dist/analysis/tools.js +217 -0
- package/dist/analysis/tools.js.map +1 -0
- package/dist/analysis/write_table.d.ts +13 -0
- package/dist/analysis/write_table.js +59 -0
- package/dist/analysis/write_table.js.map +1 -0
- package/dist/bin/cli.d.ts +10 -0
- package/dist/bin/cli.js +177 -0
- package/dist/bin/cli.js.map +1 -0
- package/dist/core/cache.d.ts +14 -0
- package/dist/core/cache.js +90 -0
- package/dist/core/cache.js.map +1 -0
- package/dist/core/context.d.ts +12 -0
- package/dist/core/context.js +15 -0
- package/dist/core/context.js.map +1 -0
- package/dist/core/env.d.ts +14 -0
- package/dist/core/env.js +52 -0
- package/dist/core/env.js.map +1 -0
- package/dist/core/generic-rest.d.ts +61 -0
- package/dist/core/generic-rest.js +639 -0
- package/dist/core/generic-rest.js.map +1 -0
- package/dist/core/http.d.ts +120 -0
- package/dist/core/http.js +514 -0
- package/dist/core/http.js.map +1 -0
- package/dist/core/keys.d.ts +43 -0
- package/dist/core/keys.js +174 -0
- package/dist/core/keys.js.map +1 -0
- package/dist/core/manual.d.ts +41 -0
- package/dist/core/manual.js +218 -0
- package/dist/core/manual.js.map +1 -0
- package/dist/core/package.d.ts +58 -0
- package/dist/core/package.js +228 -0
- package/dist/core/package.js.map +1 -0
- package/dist/core/packs.d.ts +139 -0
- package/dist/core/packs.js +173 -0
- package/dist/core/packs.js.map +1 -0
- package/dist/core/policy.d.ts +69 -0
- package/dist/core/policy.js +189 -0
- package/dist/core/policy.js.map +1 -0
- package/dist/core/py.d.ts +40 -0
- package/dist/core/py.js +171 -0
- package/dist/core/py.js.map +1 -0
- package/dist/core/routing.d.ts +10 -0
- package/dist/core/routing.js +39 -0
- package/dist/core/routing.js.map +1 -0
- package/dist/core/tabular.d.ts +21 -0
- package/dist/core/tabular.js +229 -0
- package/dist/core/tabular.js.map +1 -0
- package/dist/deep/_bea_api.d.ts +102 -0
- package/dist/deep/_bea_api.js +457 -0
- package/dist/deep/_bea_api.js.map +1 -0
- package/dist/deep/_bea_fetch.d.ts +151 -0
- package/dist/deep/_bea_fetch.js +1274 -0
- package/dist/deep/_bea_fetch.js.map +1 -0
- package/dist/deep/_bea_util.d.ts +14 -0
- package/dist/deep/_bea_util.js +156 -0
- package/dist/deep/_bea_util.js.map +1 -0
- package/dist/deep/_bls_api.d.ts +84 -0
- package/dist/deep/_bls_api.js +231 -0
- package/dist/deep/_bls_api.js.map +1 -0
- package/dist/deep/_bls_ids.d.ts +43 -0
- package/dist/deep/_bls_ids.js +188 -0
- package/dist/deep/_bls_ids.js.map +1 -0
- package/dist/deep/_bls_lib.d.ts +61 -0
- package/dist/deep/_bls_lib.js +442 -0
- package/dist/deep/_bls_lib.js.map +1 -0
- package/dist/deep/_fred_api.d.ts +148 -0
- package/dist/deep/_fred_api.js +545 -0
- package/dist/deep/_fred_api.js.map +1 -0
- package/dist/deep/_fred_pack.d.ts +162 -0
- package/dist/deep/_fred_pack.js +1027 -0
- package/dist/deep/_fred_pack.js.map +1 -0
- package/dist/deep/_fred_py.d.ts +40 -0
- package/dist/deep/_fred_py.js +199 -0
- package/dist/deep/_fred_py.js.map +1 -0
- package/dist/deep/_ipums_bundle.d.ts +29 -0
- package/dist/deep/_ipums_bundle.js +194 -0
- package/dist/deep/_ipums_bundle.js.map +1 -0
- package/dist/deep/_ipums_ddi.d.ts +23 -0
- package/dist/deep/_ipums_ddi.js +162 -0
- package/dist/deep/_ipums_ddi.js.map +1 -0
- package/dist/deep/_opm_io.d.ts +26 -0
- package/dist/deep/_opm_io.js +383 -0
- package/dist/deep/_opm_io.js.map +1 -0
- package/dist/deep/_opm_parquet.d.ts +31 -0
- package/dist/deep/_opm_parquet.js +744 -0
- package/dist/deep/_opm_parquet.js.map +1 -0
- package/dist/deep/_opm_py.d.ts +6 -0
- package/dist/deep/_opm_py.js +74 -0
- package/dist/deep/_opm_py.js.map +1 -0
- package/dist/deep/_treasury_api.d.ts +48 -0
- package/dist/deep/_treasury_api.js +221 -0
- package/dist/deep/_treasury_api.js.map +1 -0
- package/dist/deep/_treasury_context.d.ts +34 -0
- package/dist/deep/_treasury_context.js +142 -0
- package/dist/deep/_treasury_context.js.map +1 -0
- package/dist/deep/_treasury_lib.d.ts +109 -0
- package/dist/deep/_treasury_lib.js +686 -0
- package/dist/deep/_treasury_lib.js.map +1 -0
- package/dist/deep/bea.d.ts +3 -0
- package/dist/deep/bea.js +248 -0
- package/dist/deep/bea.js.map +1 -0
- package/dist/deep/bls.d.ts +3 -0
- package/dist/deep/bls.js +220 -0
- package/dist/deep/bls.js.map +1 -0
- package/dist/deep/fred.d.ts +3 -0
- package/dist/deep/fred.js +325 -0
- package/dist/deep/fred.js.map +1 -0
- package/dist/deep/ipums.d.ts +59 -0
- package/dist/deep/ipums.js +744 -0
- package/dist/deep/ipums.js.map +1 -0
- package/dist/deep/opm.d.ts +56 -0
- package/dist/deep/opm.js +1033 -0
- package/dist/deep/opm.js.map +1 -0
- package/dist/deep/treasury.d.ts +3 -0
- package/dist/deep/treasury.js +218 -0
- package/dist/deep/treasury.js.map +1 -0
- package/dist/envelope.d.ts +47 -0
- package/dist/envelope.js +88 -0
- package/dist/envelope.js.map +1 -0
- package/dist/index.d.ts +277 -0
- package/dist/index.js +106 -0
- package/dist/index.js.map +1 -0
- package/dist/remote/app.d.ts +21 -0
- package/dist/remote/app.js +218 -0
- package/dist/remote/app.js.map +1 -0
- package/dist/remote/oauth.d.ts +14 -0
- package/dist/remote/oauth.js +90 -0
- package/dist/remote/oauth.js.map +1 -0
- package/dist/remote/pages.d.ts +8 -0
- package/dist/remote/pages.js +56 -0
- package/dist/remote/pages.js.map +1 -0
- package/dist/remote/sign.d.ts +4 -0
- package/dist/remote/sign.js +40 -0
- package/dist/remote/sign.js.map +1 -0
- package/dist/remote/store.d.ts +31 -0
- package/dist/remote/store.js +129 -0
- package/dist/remote/store.js.map +1 -0
- package/dist/report/audit_answer.d.ts +94 -0
- package/dist/report/audit_answer.js +1349 -0
- package/dist/report/audit_answer.js.map +1 -0
- package/dist/report/audit_report.d.ts +23 -0
- package/dist/report/audit_report.js +637 -0
- package/dist/report/audit_report.js.map +1 -0
- package/dist/report/build_report.d.ts +27 -0
- package/dist/report/build_report.js +1168 -0
- package/dist/report/build_report.js.map +1 -0
- package/dist/report/method_audit.d.ts +47 -0
- package/dist/report/method_audit.js +710 -0
- package/dist/report/method_audit.js.map +1 -0
- package/dist/report/policyset.d.ts +50 -0
- package/dist/report/policyset.js +421 -0
- package/dist/report/policyset.js.map +1 -0
- package/dist/report/py.d.ts +58 -0
- package/dist/report/py.js +311 -0
- package/dist/report/py.js.map +1 -0
- package/dist/report/scan_secrets.d.ts +21 -0
- package/dist/report/scan_secrets.js +234 -0
- package/dist/report/scan_secrets.js.map +1 -0
- package/dist/report/style_check.d.ts +29 -0
- package/dist/report/style_check.js +173 -0
- package/dist/report/style_check.js.map +1 -0
- package/dist/report/tools.d.ts +87 -0
- package/dist/report/tools.js +167 -0
- package/dist/report/tools.js.map +1 -0
- package/dist/server.d.ts +5 -0
- package/dist/server.js +246 -0
- package/dist/server.js.map +1 -0
- package/dist/session.d.ts +47 -0
- package/dist/session.js +107 -0
- package/dist/session.js.map +1 -0
- package/dist/toolkit.d.ts +21 -0
- package/dist/toolkit.js +2 -0
- package/dist/toolkit.js.map +1 -0
- package/dist/tools.d.ts +299 -0
- package/dist/tools.js +491 -0
- package/dist/tools.js.map +1 -0
- package/guide/WORKFLOW.md +134 -0
- package/guide/assets/disclaimer.txt +1 -0
- package/guide/assets/download_data.ps1 +162 -0
- package/guide/assets/download_data.sh +143 -0
- package/guide/assets/report_template.html +597 -0
- package/guide/references/report_patterns.md +199 -0
- package/guide/references/routing.md +171 -0
- package/guide/references/style_guide.md +398 -0
- package/package.json +56 -6
- package/packs/acf/endpoints.json +114 -0
- package/packs/acf/policy.json +104 -0
- package/packs/acf/source.md +138 -0
- package/packs/actuaries/endpoints.json +82 -0
- package/packs/actuaries/policy.json +109 -0
- package/packs/actuaries/source.md +137 -0
- package/packs/bea/assets/download_bea.ps1 +182 -0
- package/packs/bea/assets/download_bea.sh +144 -0
- package/packs/bea/docs/bea_api.md +461 -0
- package/packs/bea/docs/datasets.md +157 -0
- package/packs/bea/docs/report_patterns.md +112 -0
- package/packs/bea/policy.json +170 -0
- package/packs/bea/source.md +152 -0
- package/packs/bls/assets/download_bls.ps1 +152 -0
- package/packs/bls/assets/download_bls.sh +167 -0
- package/packs/bls/docs/analysis_patterns.md +108 -0
- package/packs/bls/docs/bls_api.md +73 -0
- package/packs/bls/docs/series_ids.md +149 -0
- package/packs/bls/policy.json +238 -0
- package/packs/bls/series_ids.json +1375 -0
- package/packs/bls/source.md +156 -0
- package/packs/bts/endpoints.json +347 -0
- package/packs/bts/policy.json +94 -0
- package/packs/bts/source.md +97 -0
- package/packs/cdc/endpoints.json +197 -0
- package/packs/cdc/policy.json +83 -0
- package/packs/cdc/source.md +74 -0
- package/packs/census/endpoints.json +99 -0
- package/packs/census/policy.json +238 -0
- package/packs/census/source.md +304 -0
- package/packs/census-geocoder/endpoints.json +70 -0
- package/packs/census-geocoder/policy.json +80 -0
- package/packs/census-geocoder/source.md +53 -0
- package/packs/cfpb/endpoints.json +327 -0
- package/packs/cfpb/policy.json +119 -0
- package/packs/cfpb/source.md +96 -0
- package/packs/clinical-trials/endpoints.json +167 -0
- package/packs/clinical-trials/policy.json +84 -0
- package/packs/clinical-trials/source.md +82 -0
- package/packs/cms/endpoints.json +69 -0
- package/packs/cms/policy.json +96 -0
- package/packs/cms/source.md +112 -0
- package/packs/college-scorecard/endpoints.json +253 -0
- package/packs/college-scorecard/policy.json +106 -0
- package/packs/college-scorecard/source.md +92 -0
- package/packs/congress/endpoints.json +1701 -0
- package/packs/congress/policy.json +117 -0
- package/packs/congress/source.md +190 -0
- package/packs/dhs-ohss/endpoints.json +66 -0
- package/packs/dhs-ohss/policy.json +107 -0
- package/packs/dhs-ohss/source.md +120 -0
- package/packs/doj-news/endpoints.json +59 -0
- package/packs/doj-news/policy.json +96 -0
- package/packs/doj-news/source.md +99 -0
- package/packs/dol/endpoints.json +818 -0
- package/packs/dol/policy.json +135 -0
- package/packs/dol/source.md +181 -0
- package/packs/eia/endpoints.json +718 -0
- package/packs/eia/policy.json +112 -0
- package/packs/eia/source.md +112 -0
- package/packs/epa/endpoints.json +292 -0
- package/packs/epa/policy.json +99 -0
- package/packs/epa/source.md +99 -0
- package/packs/epa-aqs/endpoints.json +174 -0
- package/packs/epa-aqs/policy.json +96 -0
- package/packs/epa-aqs/source.md +97 -0
- package/packs/fbi/endpoints.json +1842 -0
- package/packs/fbi/policy.json +118 -0
- package/packs/fbi/source.md +108 -0
- package/packs/fda/endpoints.json +238 -0
- package/packs/fda/policy.json +121 -0
- package/packs/fda/source.md +117 -0
- package/packs/fdic/endpoints.json +417 -0
- package/packs/fdic/policy.json +83 -0
- package/packs/fdic/source.md +92 -0
- package/packs/fec/endpoints.json +708 -0
- package/packs/fec/policy.json +93 -0
- package/packs/fec/source.md +90 -0
- package/packs/fed-board/endpoints.json +89 -0
- package/packs/fed-board/policy.json +136 -0
- package/packs/fed-board/source.md +118 -0
- package/packs/federal-register/endpoints.json +143 -0
- package/packs/federal-register/policy.json +86 -0
- package/packs/federal-register/source.md +98 -0
- package/packs/fema/endpoints.json +646 -0
- package/packs/fema/policy.json +103 -0
- package/packs/fema/source.md +103 -0
- package/packs/fhfa/endpoints.json +105 -0
- package/packs/fhfa/policy.json +109 -0
- package/packs/fhfa/source.md +108 -0
- package/packs/fred/assets/download_fred.ps1 +122 -0
- package/packs/fred/assets/download_fred.sh +123 -0
- package/packs/fred/docs/analysis_patterns.md +124 -0
- package/packs/fred/docs/fred_api.md +94 -0
- package/packs/fred/docs/series.md +188 -0
- package/packs/fred/policy.json +253 -0
- package/packs/fred/source.md +142 -0
- package/packs/fsa/endpoints.json +150 -0
- package/packs/fsa/policy.json +99 -0
- package/packs/fsa/source.md +102 -0
- package/packs/govinfo/endpoints.json +520 -0
- package/packs/govinfo/policy.json +116 -0
- package/packs/govinfo/source.md +241 -0
- package/packs/gsa-calc/endpoints.json +93 -0
- package/packs/gsa-calc/policy.json +97 -0
- package/packs/gsa-calc/source.md +108 -0
- package/packs/hud/endpoints.json +147 -0
- package/packs/hud/policy.json +84 -0
- package/packs/hud/source.md +97 -0
- package/packs/ipums/assets/download_ipums.ps1 +215 -0
- package/packs/ipums/assets/download_ipums.sh +192 -0
- package/packs/ipums/docs/ipums_api.md +67 -0
- package/packs/ipums/docs/report_patterns.md +117 -0
- package/packs/ipums/docs/variables.md +284 -0
- package/packs/ipums/lib/fetch_text.json +112 -0
- package/packs/ipums/policy.json +215 -0
- package/packs/ipums/source.md +169 -0
- package/packs/irs-soi/endpoints.json +114 -0
- package/packs/irs-soi/policy.json +107 -0
- package/packs/irs-soi/source.md +124 -0
- package/packs/medicaid/endpoints.json +412 -0
- package/packs/medicaid/policy.json +108 -0
- package/packs/medicaid/source.md +136 -0
- package/packs/naep/endpoints.json +217 -0
- package/packs/naep/policy.json +100 -0
- package/packs/naep/source.md +120 -0
- package/packs/nhtsa/endpoints.json +132 -0
- package/packs/nhtsa/policy.json +93 -0
- package/packs/nhtsa/source.md +109 -0
- package/packs/nih/endpoints.json +453 -0
- package/packs/nih/policy.json +86 -0
- package/packs/nih/source.md +108 -0
- package/packs/noaa/endpoints.json +432 -0
- package/packs/noaa/policy.json +95 -0
- package/packs/noaa/source.md +88 -0
- package/packs/nrel/endpoints.json +328 -0
- package/packs/nrel/policy.json +96 -0
- package/packs/nrel/source.md +91 -0
- package/packs/nws/endpoints.json +272 -0
- package/packs/nws/policy.json +82 -0
- package/packs/nws/source.md +81 -0
- package/packs/nyfed/endpoints.json +80 -0
- package/packs/nyfed/policy.json +92 -0
- package/packs/nyfed/source.md +89 -0
- package/packs/omb/endpoints.json +460 -0
- package/packs/omb/policy.json +106 -0
- package/packs/omb/source.md +130 -0
- package/packs/open-payments/endpoints.json +298 -0
- package/packs/open-payments/policy.json +101 -0
- package/packs/open-payments/source.md +99 -0
- package/packs/opm/assets/download_opm.ps1 +125 -0
- package/packs/opm/assets/download_opm.sh +85 -0
- package/packs/opm/docs/fields.md +184 -0
- package/packs/opm/docs/opm_api.md +71 -0
- package/packs/opm/docs/report_patterns.md +83 -0
- package/packs/opm/lib/data_dictionary.csv +73 -0
- package/packs/opm/policy.json +142 -0
- package/packs/opm/source.md +137 -0
- package/packs/pbgc/endpoints.json +483 -0
- package/packs/pbgc/policy.json +94 -0
- package/packs/pbgc/source.md +95 -0
- package/packs/philfed/endpoints.json +85 -0
- package/packs/philfed/policy.json +94 -0
- package/packs/philfed/source.md +125 -0
- package/packs/port.json +287 -0
- package/packs/regulations/endpoints.json +288 -0
- package/packs/regulations/policy.json +86 -0
- package/packs/regulations/source.md +84 -0
- package/packs/sec/endpoints.json +237 -0
- package/packs/sec/policy.json +86 -0
- package/packs/sec/source.md +101 -0
- package/packs/senate-lobbying/endpoints.json +554 -0
- package/packs/senate-lobbying/policy.json +99 -0
- package/packs/senate-lobbying/source.md +100 -0
- package/packs/snapqc/endpoints.json +1426 -0
- package/packs/snapqc/policy.json +92 -0
- package/packs/snapqc/source.md +96 -0
- package/packs/treasury/catalog.json +2267 -0
- package/packs/treasury/docs/api_guide.md +245 -0
- package/packs/treasury/docs/datasets.md +56 -0
- package/packs/treasury/docs/report_patterns.md +126 -0
- package/packs/treasury/policy.json +159 -0
- package/packs/treasury/source.md +165 -0
- package/packs/treasury-yields/endpoints.json +226 -0
- package/packs/treasury-yields/policy.json +86 -0
- package/packs/treasury-yields/source.md +80 -0
- package/packs/usaspending/endpoints.json +1316 -0
- package/packs/usaspending/policy.json +109 -0
- package/packs/usaspending/source.md +103 -0
- package/packs/usda-fna/endpoints.json +427 -0
- package/packs/usda-fna/policy.json +133 -0
- package/packs/usda-fna/source.md +217 -0
- package/packs/usda-fooddata/endpoints.json +181 -0
- package/packs/usda-fooddata/policy.json +94 -0
- package/packs/usda-fooddata/source.md +105 -0
- package/packs/usda-nass/endpoints.json +324 -0
- package/packs/usda-nass/policy.json +95 -0
- package/packs/usda-nass/source.md +85 -0
- package/packs/usda-outlook/endpoints.json +86 -0
- package/packs/usda-outlook/policy.json +109 -0
- package/packs/usda-outlook/source.md +144 -0
- package/packs/usgs/endpoints.json +313 -0
- package/packs/usgs/policy.json +95 -0
- package/packs/usgs/source.md +96 -0
- package/packs/usitc/endpoints.json +74 -0
- package/packs/usitc/policy.json +111 -0
- package/packs/usitc/source.md +90 -0
- package/packs/uspto/endpoints.json +141 -0
- package/packs/uspto/policy.json +95 -0
- package/packs/uspto/source.md +101 -0
- package/packs/va/endpoints.json +414 -0
- package/packs/va/policy.json +101 -0
- package/packs/va/source.md +129 -0
- package/packs/world-bank/endpoints.json +122 -0
- package/packs/world-bank/policy.json +101 -0
- package/packs/world-bank/source.md +93 -0
|
@@ -0,0 +1,169 @@
|
|
|
1
|
+
# IPUMS microdata (USA/ACS, CPS and other collections)
|
|
2
|
+
Depth: deep. Key: required (IPUMS_API_KEY) for the API; the website builds the same extract with a free
|
|
3
|
+
account and no key. Person-level survey microdata (ACS, decennial census, CPS ASEC and monthly, IPUMS-I,
|
|
4
|
+
ATUS, NHIS, MEPS) as filtered extracts, for weighted estimates.
|
|
5
|
+
|
|
6
|
+
## When to use
|
|
7
|
+
- Custom tabulations the published tables do not give: employment, earnings, hourly wages, poverty,
|
|
8
|
+
health insurance, immigrants (nativity, citizenship, birthplace), veterans, education, by any
|
|
9
|
+
combination of groups; public vs. private pay; minimum-wage exposure (CPS outgoing rotation groups).
|
|
10
|
+
- Choose the collection (details: `docs/variables.md` section 1):
|
|
11
|
+
ACS 1-year (`usYYYYa`, ~3.3M persons) for states and small groups; ACS 5-year (`usYYYYc`) for very small
|
|
12
|
+
groups or areas (pooled period, no year-to-year change); CPS ASEC (`cpsYYYY_03s`) for annual income,
|
|
13
|
+
poverty and insurance (income refers to the previous year; series from 1962); CPS basic monthly
|
|
14
|
+
(`cpsYYYY_MMs`) for monthly labor force and hourly/weekly earnings; NHIS (`ihYYYY`) for insurance at the
|
|
15
|
+
interview, access to care, conditions and health status; MEPS (`mpYYYY`) for health care spending
|
|
16
|
+
(total, out-of-pocket, by payer) and insurance over a whole year (`docs/variables.md` sections 8-9).
|
|
17
|
+
- Recent ACS PUMS years, one CPS month or one ASEC year: the census pack serves the same Census files directly
|
|
18
|
+
(census key, seconds, public domain; replicate weights for ACS and for the ASEC from 2005). Use this pack
|
|
19
|
+
for what only IPUMS adds: codes harmonized across years (EDUC, OCC1990), CPI99, attached spouse or parent
|
|
20
|
+
traits, CPS panels (CPSIDP), ASEC standard errors before 2005, years before 2004 (ACS) or 1989 (CPS), NHIS, MEPS, ATUS,
|
|
21
|
+
historical censuses and international samples.
|
|
22
|
+
- Not here: published ACS tables by geography (census pack), official BLS rates and CPS-based series
|
|
23
|
+
(bls, fred), federal workforce administrative records (opm), published health statistics (cdc) and
|
|
24
|
+
Medicare program data (cms). Prefer a published table when it answers the question; microdata are for
|
|
25
|
+
what tables cannot do.
|
|
26
|
+
- Your estimates are your own and people may quote them: accuracy comes first.
|
|
27
|
+
|
|
28
|
+
## Endpoints and datasets
|
|
29
|
+
| Call (`https://api.ipums.org`, `?collection=<c>&version=2`) | Returns |
|
|
30
|
+
|---|---|
|
|
31
|
+
| `GET /metadata/samples` | sample IDs and descriptions (`request_schema` with `search: "usa 2023"`) |
|
|
32
|
+
| `POST /extracts` (body built from the spec) | `{number, status}` |
|
|
33
|
+
| `GET /extracts/{number}` | status queued/started/produced/completed/failed/canceled, `downloadLinks` |
|
|
34
|
+
| `GET downloadLinks.data.url`, `.ddiCodebook.url` | the gzipped CSV and the DDI XML codebook |
|
|
35
|
+
|
|
36
|
+
There is no variable-metadata endpoint for microdata: variable names and verified codes are in
|
|
37
|
+
`docs/variables.md` (sections 4-7, ready-made variable sets by topic); after a download,
|
|
38
|
+
`data/ipums/codebook.csv` is the authority. API body details, timing and errors: `docs/ipums_api.md`.
|
|
39
|
+
Collections with API extracts: usa, cps, ipumsi, atus, ahtus, mtus, nhis, meps, dhs (case selection and
|
|
40
|
+
monetary adjustment only for usa, cps, ipumsi: `fetch` refuses them elsewhere (`invalid_request`), so mark the group with a domain mask and deflate with CPI-U after download; NHIS has no data quality flags, MEPS no attached characteristics;
|
|
41
|
+
dhs needs an account approved by The DHS Program, so a 401/403 there usually means that approval is
|
|
42
|
+
missing). Codes, weights and recodes are documented for usa, cps, nhis and meps; for the others, work from
|
|
43
|
+
the collection's website and `codebook.csv`.
|
|
44
|
+
|
|
45
|
+
Tools: `request_schema` (`names: ["usa"]` etc. gives the spec format, weights and sample IDs; a search such as
|
|
46
|
+
`cps 2023` lists sample IDs, with a key), `fetch` (submits the extract, waits, downloads and packages it; it
|
|
47
|
+
reuses a finished extract and, when a wait timed out, collects the extract still running at IPUMS: its number
|
|
48
|
+
is saved in `data/ipums/extract_spec.json`, so call `fetch` again with the same spec; `force: true` submits a new
|
|
49
|
+
one), and `ingest` (the .csv.gz and .xml the user downloaded). Small CPS extracts take about a minute;
|
|
50
|
+
multi-year ACS 5-30 minutes; one `fetch` waits `max_wait_s` (default 600). A blocked fetch returns an error
|
|
51
|
+
with its fix: follow it; never invent or substitute data.
|
|
52
|
+
|
|
53
|
+
## Spec examples
|
|
54
|
+
```json
|
|
55
|
+
{"collection": "usa", "description": "Prime-age employment by nativity, ACS",
|
|
56
|
+
"samples": ["us2013a", "us2018a", "us2023a"],
|
|
57
|
+
"variables": ["AGE", "SEX", "CITIZEN", "EDUCD", "EMPSTAT", "INCWAGE", "CPI99"],
|
|
58
|
+
"case_selections": {"AGE": {"min": 25, "max": 54}}}
|
|
59
|
+
```
|
|
60
|
+
```json
|
|
61
|
+
{"collection": "cps",
|
|
62
|
+
"description": "CPS ASEC 2024: federal civilian vs private-sector wage and salary workers",
|
|
63
|
+
"samples": ["cps2024_03s"],
|
|
64
|
+
"variables": ["AGE", "SEX", "RACE", "HISPAN", "EDUC", "CLASSWLY", "INCWAGE", "WKSWORK1", "UHRSWORKLY",
|
|
65
|
+
"FULLPART", "OCCLY", "INDLY", "STATEFIP", "VETSTAT", "FIRMSIZE", "REPWTP"],
|
|
66
|
+
"case_selections": {"CLASSWLY": [22, 25]}}
|
|
67
|
+
```
|
|
68
|
+
Optional keys: `case_select_who` (`individuals` | `households`), `attached_characteristics`
|
|
69
|
+
(`{"EDUC": ["spouse"]}`), `data_quality_flags` (list or true), `adjust_monetary_values` (list),
|
|
70
|
+
`case_selections` with `{"detailed": [...]}` for detailed codes, `data_format`, `data_structure`, `max_wait_s`.
|
|
71
|
+
Keep extracts lean: only the variables used, case selections for the universe, only the needed years.
|
|
72
|
+
Name explicitly: `CPI99` (constant dollars), `REPWTP` (replicate weights), the detailed variable you
|
|
73
|
+
select on (`EDUCD`). Confirm sample IDs with a `request_schema` search before submitting.
|
|
74
|
+
|
|
75
|
+
## Data format and traps
|
|
76
|
+
`fetch` writes `data/ipums/`: `ipums_extract.csv` (uppercase mnemonics, raw IPUMS codes, one row per
|
|
77
|
+
person), `codebook.csv` (variable, value, value_label), `variables.csv`, the DDI `.xml`,
|
|
78
|
+
`extract_spec.json` (spec + exact API body + extract number), `request.json`, `README.md` (citation,
|
|
79
|
+
weights, terms).
|
|
80
|
+
- **Weights on every estimate**: PERWT / HHWT (USA; household measures on PERNUM == 1), ASECWT (CPS
|
|
81
|
+
ASEC; WTFINL is not offered for ASEC samples: the API refuses it with HTTP 400, verified 2026-10), WTFINL (CPS monthly; COMPWT for employment levels that match BLS), EARNWT (earnings questions, outgoing
|
|
82
|
+
rotation groups), SAMPWEIGHT (NHIS 2019 on: sample adults `ASTATFLG == 1` and sample children
|
|
83
|
+
`CSTATFLG == 1`, never summed across items of different universes), PERWEIGHT (MEPS; 0 = out of scope).
|
|
84
|
+
Pooling years: average yearly estimates or divide weights by the number of years.
|
|
85
|
+
- **Health surveys**: NHIS trends break at the 2019 redesign (and 2020 was collected partly by phone, with
|
|
86
|
+
`PARTWEIGHT`); NHIS EMPSTAT from 2019 is employed / not employed only. MEPS dollars are nominal for the
|
|
87
|
+
calendar year, spending is highly skewed (screen outliers, add medians), and `CHGTOT` is charges, not
|
|
88
|
+
payments. Variable names differ from USA/CPS and between NHIS and MEPS (HINOTCOVE vs. HINOTCOV): use
|
|
89
|
+
`docs/variables.md` sections 8-9.
|
|
90
|
+
- **Missing and top codes**: treat every code whose `codebook.csv` label says N/A, NIU, missing or unknown
|
|
91
|
+
as missing (`compute` `filter` or `derive`); then look at the min and max of every dollar and hours variable. USA INCWAGE 999999 = N/A, 999998 = missing; CPS INCWAGE 99999999 NIU;
|
|
92
|
+
HHINCOME 9999999 (USA); UHRSWORKLY 999 NIU. An unremoved 9999999 is the classic IPUMS mistake.
|
|
93
|
+
- **Outliers**: screen every dollar variable and derived hourly wages for extreme values. In recent ASECs each
|
|
94
|
+
income component is top-coded or swapped at about 1,099,999; INCWAGE sums two of them (INCLONGJ +
|
|
95
|
+
OINCWAGE), so it reaches 2,199,998 (ASEC 2026: 220 records at $1M or more). A few such records can
|
|
96
|
+
move a small cell's mean by 10+ percent: report a stated rule and the sensitivity.
|
|
97
|
+
- **Universe**: CPS CLASSWLY 25 (federal) includes active-duty armed forces: drop them via OCCLY/INDLY
|
|
98
|
+
military codes (see `docs/variables.md` 5). GQ in (1, 2, 5) for the household population (USA).
|
|
99
|
+
Report how many records each filter drops (a sample-flow table).
|
|
100
|
+
- **Dollar year**: CPS ASEC year t reports income for t-1. Convert with CPI99 (request it) or
|
|
101
|
+
`adjust_monetary_values`; IPUMS does not recommend the ACS ADJUST factor for analysis across years. But
|
|
102
|
+
Census's published ACS dollar tables (B19013, S1901) are in survey-year dollars computed with ADJINC: to
|
|
103
|
+
match them, multiply by ADJUST (without it, medians come out about 1.5 percent low, inside the margins of
|
|
104
|
+
error, so the benchmark check would not show the bias). State the dollar year.
|
|
105
|
+
- **Codes differ by collection**: CPS EDUC is one detailed 3-digit variable (73 high school, 111
|
|
106
|
+
bachelor's); USA uses EDUCD for degree groups. Foreign born (not a citizen at birth): CPS CITIZEN 4-5
|
|
107
|
+
(not NATIVITY 5, which adds people born in outlying areas or abroad of American parents); ACS CITIZEN 2-5
|
|
108
|
+
(USA has no NATIVITY for ACS): use the right one for the collection. CPS EMPSTAT 10/12 employed, 20-22 unemployed. Check `codebook.csv`.
|
|
109
|
+
- **Extract gotchas**: IPUMS adds detailed versions automatically (EDUC brings EDUCD); a data-quality
|
|
110
|
+
flag or case-selection code that a sample lacks returns HTTP 400 (fix the spec and fetch again);
|
|
111
|
+
ACS 2020 1-year has experimental weights.
|
|
112
|
+
- **Standard errors**: this server has no replicate-weight or design-based standard errors yet. Report
|
|
113
|
+
which weight each estimate uses and that standard errors were not computed; without them, never call a
|
|
114
|
+
difference "statistically different" (when standard errors exist, the rule is beyond 1.645 standard errors,
|
|
115
|
+
90 percent; otherwise "about the same"). The methods, for reference: ACS person estimates use REPWTP (80
|
|
116
|
+
replicates), household estimates (tenure, household income) REPWT with HHWT, Census's own method; a
|
|
117
|
+
linearized SE with STRATA and CLUSTER (added automatically) can understate a PUMS margin (half of the
|
|
118
|
+
replicate one in a 2024 tenure check), so replicates are preferred. CPS ASEC: REPWTP (160) for person
|
|
119
|
+
estimates, or REPWT (160) with ASECWTH on householders (`RELATE == 101`) for household estimates such as
|
|
120
|
+
median household income (P60 tables). NHIS and MEPS have no replicate weights: their SEs come from the
|
|
121
|
+
design variables, estimated on the whole file with a domain mask, not on filtered rows. CPS basic monthly
|
|
122
|
+
has no replicate weights and no design variables in the public files: an SE clustered by household
|
|
123
|
+
(CPSID) is approximate, and the answer says so. BLS's CPS variance parameters do not apply to union or
|
|
124
|
+
earnings estimates. Union membership (`UNION`, with `EARNWT`): IPUMS's universe starts at age 15; BLS's
|
|
125
|
+
published rates are for 16 and over (BLS also publishes the annual rate as `LUU0204899600`).
|
|
126
|
+
Thin cells (fewer than 100 records) are footnoted or suppressed.
|
|
127
|
+
- **Medians of dollar amounts**: reported income heaps on round numbers, so a plain weighted median sits
|
|
128
|
+
on a heap ($60,000) and its replicate SE can come out 0. Census publishes medians interpolated within
|
|
129
|
+
$2,500 intervals: use such a binned median to compare with Census (P60 tables); BLS weekly earnings use
|
|
130
|
+
$50 intervals centred on multiples of $50 (edges at $25, $75, ...); state which median you report. CPS earnings after March 2023: `EARNWEEK2`/`HOURWAGE2` (docs/variables.md).
|
|
131
|
+
- **Composition**: show the raw and a composition-adjusted gap (standardized to a common group mix); test
|
|
132
|
+
every threshold or definition for sensitivity; benchmark a headline number against a published figure (Census, BLS).
|
|
133
|
+
- Public IPUMS data cannot show legal status, benefits, or full administrative controls: say so.
|
|
134
|
+
|
|
135
|
+
Analysis: build tables with `compute` on `data/ipums/ipums_extract.csv`, decoding values with `codebook.csv`. This
|
|
136
|
+
server has no IPUMS recode helpers or replicate-weight standard errors yet: say which weight you used, and that
|
|
137
|
+
standard errors were not computed.
|
|
138
|
+
Typical questions, conventions (populations, definitions, benchmarks) and chart forms:
|
|
139
|
+
`docs/report_patterns.md`.
|
|
140
|
+
|
|
141
|
+
## Access
|
|
142
|
+
- Key: `IPUMS_API_KEY`, free at https://account.ipums.org/api_keys; the account must be registered
|
|
143
|
+
separately for each collection (usa.ipums.org, cps.ipums.org, ...). Found, in order, in the environment
|
|
144
|
+
variable, the file named by `IPUMS_API_KEY_FILE`, `env.IPUMS_API_KEY` in keys.json, then in Claude Code's settings.json,
|
|
145
|
+
`~/.ipums/api_key`. A 401/403 with a key set means a wrong key or an unregistered collection
|
|
146
|
+
(`key_rejected`): never point at `setup` then. No key (`key_missing`): the user runs
|
|
147
|
+
`npx -y data-analyst-mcp setup ipums` in their own terminal (never ask for the key in chat), or uses the
|
|
148
|
+
manual route below.
|
|
149
|
+
- Manual route (sandbox, hosted chat, no key, no network): `manual_bundle` cannot write an IPUMS bundle yet
|
|
150
|
+
(it returns `not_supported`). Give the user the website steps yourself: on the collection's website
|
|
151
|
+
(usa.ipums.org, cps.ipums.org, ...), with a free account and no key, build the extract with the spec's exact
|
|
152
|
+
samples, variables, case selections, CSV format and description, then download the `.csv.gz` data file and
|
|
153
|
+
the `.xml` DDI codebook. After the upload: `ingest` with the files or their folder (on a hosted server,
|
|
154
|
+
`files: ["uploads"]`). It warns when a requested variable is missing from the file (likely on the website
|
|
155
|
+
route: ask the user to add it).
|
|
156
|
+
- Record the route (API, reused, hand-downloaded; `route` in `data/ipums/request.json`) and the extract
|
|
157
|
+
number in the methods.
|
|
158
|
+
|
|
159
|
+
## Citation and terms
|
|
160
|
+
Cite IPUMS as `data/ipums/README.md` says (taken from the extract's DDI, with the versioned DOI; the
|
|
161
|
+
unversioned DOI does not resolve), e.g. "IPUMS CPS [dataset], DOI 10.18128/D030.V13.0. Minneapolis, MN:
|
|
162
|
+
IPUMS." Source line: "Analyst calculations using data from IPUMS-CPS (Current Population Survey)."
|
|
163
|
+
Redistribution: **definition_only**. The IPUMS terms forbid redistributing extracts (except a subset to
|
|
164
|
+
meet journal requirements): the extract stays in `data/ipums/` for the user's own use; never put
|
|
165
|
+
microdata in an artifact, published page, sent file or package. `extract_spec.json`, `README.md`,
|
|
166
|
+
`codebook.csv`, `variables.csv` and `request.json` may be shared, so readers request the same extract
|
|
167
|
+
under their own account. Aggregated
|
|
168
|
+
estimates and exhibit tables may be published. IPUMS deletes extract files about 72 hours after they are
|
|
169
|
+
built; the definition can be resubmitted any time.
|
|
@@ -0,0 +1,114 @@
|
|
|
1
|
+
{
|
|
2
|
+
"base_url": "https://www.irs.gov/pub/irs-soi",
|
|
3
|
+
"timeout": 120,
|
|
4
|
+
"endpoints": {
|
|
5
|
+
"zip_agi": {
|
|
6
|
+
"path": "/{yy}zpallagi.csv",
|
|
7
|
+
"method": "GET",
|
|
8
|
+
"description": "Individual income tax returns by ZIP code and AGI size class (6 classes): number of returns (N*), amounts in thousands of dollars (A*), about 160 items. One all-states file per tax year (216 MB for TY2022), streamed to a temporary file and filtered by state while reading. agi_classes=false reads {yy}zpallnoagi.csv (one row per ZIP, AGI_STUB 0). Tax years 2011-2023.",
|
|
9
|
+
"first_year": 2011,
|
|
10
|
+
"last_year_verified": 2023,
|
|
11
|
+
"stream": true,
|
|
12
|
+
"params": {
|
|
13
|
+
"tax_year": {"in": "spec", "desc": "tax year, e.g. 2022 (or start_year/end_year for several; each is one file)"},
|
|
14
|
+
"start_year": {"in": "spec", "desc": "first tax year of a range"},
|
|
15
|
+
"end_year": {"in": "spec", "desc": "last tax year of a range"},
|
|
16
|
+
"state": {"in": "spec", "desc": "state(s): USPS code, FIPS code or name, or a list (required unless zipcode is given)"},
|
|
17
|
+
"zipcode": {"in": "spec", "desc": "5-digit ZIP code(s) to keep; 00000 = state total, 99999 = small and nonresidential ZIPs combined"},
|
|
18
|
+
"agi_stub": {"in": "spec", "desc": "AGI size class(es) to keep, 1-6 (see source.md)"},
|
|
19
|
+
"agi_classes": {"in": "spec", "desc": "false: read the file without AGI classes (one row per ZIP); default true"},
|
|
20
|
+
"columns": {"in": "spec", "desc": "variables to keep, e.g. [\"N1\", \"A00100\"]; the identifier columns are always kept"}
|
|
21
|
+
},
|
|
22
|
+
"records": "$csv",
|
|
23
|
+
"paging": {"type": "none"},
|
|
24
|
+
"max_rows": 200000,
|
|
25
|
+
"flatten": false
|
|
26
|
+
},
|
|
27
|
+
"county_agi": {
|
|
28
|
+
"path": "/{yy}incyallagi.csv",
|
|
29
|
+
"method": "GET",
|
|
30
|
+
"description": "Individual income tax returns by county and AGI size class (8 classes), with each state's total as COUNTYFIPS 000: number of returns (N*), amounts in thousands of dollars (A*), about 160 items. One all-states file per tax year (36 MB). agi_classes=false reads {yy}incyallnoagi.csv (one row per county, AGI_STUB 0). Tax years 2011-2023.",
|
|
31
|
+
"first_year": 2011,
|
|
32
|
+
"last_year_verified": 2023,
|
|
33
|
+
"params": {
|
|
34
|
+
"tax_year": {"in": "spec", "desc": "tax year, e.g. 2022 (or start_year/end_year)"},
|
|
35
|
+
"start_year": {"in": "spec", "desc": "first tax year of a range"},
|
|
36
|
+
"end_year": {"in": "spec", "desc": "last tax year of a range"},
|
|
37
|
+
"state": {"in": "spec", "desc": "state(s): USPS code, FIPS code or name, or a list (default: all states)"},
|
|
38
|
+
"county": {"in": "spec", "desc": "county(ies): 3-digit county FIPS (with state), 5-digit state+county FIPS, or the county name as published (\"Montgomery County\"); 000 = the state total"},
|
|
39
|
+
"agi_stub": {"in": "spec", "desc": "AGI size class(es) to keep, 1-8 (see source.md)"},
|
|
40
|
+
"agi_classes": {"in": "spec", "desc": "false: read the file without AGI classes; default true"},
|
|
41
|
+
"columns": {"in": "spec", "desc": "variables to keep; the identifier columns are always kept"}
|
|
42
|
+
},
|
|
43
|
+
"records": "$csv",
|
|
44
|
+
"paging": {"type": "none"},
|
|
45
|
+
"max_rows": 200000,
|
|
46
|
+
"flatten": false
|
|
47
|
+
},
|
|
48
|
+
"state_agi": {
|
|
49
|
+
"path": "/{yy}in55cmcsv.csv",
|
|
50
|
+
"method": "GET",
|
|
51
|
+
"description": "Historic Table 2: individual income tax returns by state and AGI size class (AGI_STUB 0 = all returns, 1-10 = classes), for 50 states, DC, Puerto Rico (PR), other areas (OA) and the United States (US); amounts in thousands of dollars. One file per tax year (0.8 MB): tax years 2012 and 2014-2023 (2013 is published only as .xlsx). File names vary by year (12/14-17in54cmcsv.csv, 18in55cmagi.csv, 19-23in55cmcsv.csv); the adapter picks the right one.",
|
|
52
|
+
"first_year": 2012,
|
|
53
|
+
"last_year_verified": 2023,
|
|
54
|
+
"params": {
|
|
55
|
+
"tax_year": {"in": "spec", "desc": "tax year, e.g. 2022 (or start_year/end_year)"},
|
|
56
|
+
"start_year": {"in": "spec", "desc": "first tax year of a range"},
|
|
57
|
+
"end_year": {"in": "spec", "desc": "last tax year of a range"},
|
|
58
|
+
"state": {"in": "spec", "desc": "state(s): USPS code, FIPS code or name, or US / PR / OA; default all"},
|
|
59
|
+
"agi_stub": {"in": "spec", "desc": "AGI size class(es) to keep, 0-10 (0 = all returns)"},
|
|
60
|
+
"columns": {"in": "spec", "desc": "variables to keep; STATE and AGI_STUB are always kept"}
|
|
61
|
+
},
|
|
62
|
+
"records": "$csv",
|
|
63
|
+
"paging": {"type": "none"},
|
|
64
|
+
"max_rows": 200000,
|
|
65
|
+
"flatten": false
|
|
66
|
+
},
|
|
67
|
+
"migration": {
|
|
68
|
+
"path": "/{level}{direction}{y1y2}.csv",
|
|
69
|
+
"method": "GET",
|
|
70
|
+
"description": "Taxpayer migration from matched returns of two consecutive filing years: number of returns (N1, about households), individuals (N2) and AGI (thousands of dollars, year-2 return) moving between states or counties. level state|county, direction inflow (into the state/county, by origin) | outflow (out of it, by destination); y1 = first filing year (2022 = 2022-2023). Filing-year pairs 2011-2012 to 2022-2023.",
|
|
71
|
+
"first_year": 2011,
|
|
72
|
+
"last_year_verified": 2022,
|
|
73
|
+
"params": {
|
|
74
|
+
"level": {"in": "spec", "required": true, "enum": ["state", "county"], "desc": "state-to-state or county-to-county flows"},
|
|
75
|
+
"direction": {"in": "spec", "required": true, "enum": ["inflow", "outflow"], "desc": "inflow: into the state/county by origin; outflow: out of it by destination"},
|
|
76
|
+
"y1": {"in": "spec", "desc": "first filing year of the pair, e.g. 2022 for 2022-2023 (or start_y1/end_y1)"},
|
|
77
|
+
"start_y1": {"in": "spec", "desc": "first y1 of a range of pairs"},
|
|
78
|
+
"end_y1": {"in": "spec", "desc": "last y1 of a range of pairs"},
|
|
79
|
+
"state": {"in": "spec", "desc": "the state(s) whose inflow or outflow to keep (destination for inflow, origin for outflow); default all"},
|
|
80
|
+
"county": {"in": "spec", "desc": "county level: the county(ies) whose flows to keep: 3-digit county FIPS (with state) or 5-digit FIPS"}
|
|
81
|
+
},
|
|
82
|
+
"records": "$csv",
|
|
83
|
+
"paging": {"type": "none"},
|
|
84
|
+
"max_rows": 200000,
|
|
85
|
+
"flatten": false
|
|
86
|
+
}
|
|
87
|
+
},
|
|
88
|
+
"catalog": {
|
|
89
|
+
"zip": {
|
|
90
|
+
"id": "zpallagi",
|
|
91
|
+
"name": "SOI ZIP Code Data (all states, by AGI class)",
|
|
92
|
+
"endpoint": "zip_agi",
|
|
93
|
+
"description": "income tax returns, adjusted gross income AGI, wages, credits by ZIP code and income size class; zip code income"
|
|
94
|
+
},
|
|
95
|
+
"county": {
|
|
96
|
+
"id": "incyallagi",
|
|
97
|
+
"name": "SOI County Data (all states, by AGI class)",
|
|
98
|
+
"endpoint": "county_agi",
|
|
99
|
+
"description": "income tax returns, adjusted gross income AGI, wages, earned income credit by county and income size class; county income"
|
|
100
|
+
},
|
|
101
|
+
"state": {
|
|
102
|
+
"id": "in55cmcsv",
|
|
103
|
+
"name": "SOI Historic Table 2 (state data by AGI class)",
|
|
104
|
+
"endpoint": "state_agi",
|
|
105
|
+
"description": "income tax returns and AGI by state and income size class including $1 million or more; national total"
|
|
106
|
+
},
|
|
107
|
+
"migration": {
|
|
108
|
+
"id": "migration",
|
|
109
|
+
"name": "SOI Migration Data (state-to-state and county-to-county)",
|
|
110
|
+
"endpoint": "migration",
|
|
111
|
+
"description": "taxpayer migration inflow outflow between states and counties; households, people and income moving; net migration"
|
|
112
|
+
}
|
|
113
|
+
}
|
|
114
|
+
}
|
|
@@ -0,0 +1,107 @@
|
|
|
1
|
+
{
|
|
2
|
+
"id": "irs-soi",
|
|
3
|
+
"title": "IRS Statistics of Income: individual income tax data by ZIP code, county, state and migration (irs.gov)",
|
|
4
|
+
"agency": "Internal Revenue Service, Statistics of Income Division",
|
|
5
|
+
"depth": "standard",
|
|
6
|
+
"domains": [
|
|
7
|
+
"taxes",
|
|
8
|
+
"income",
|
|
9
|
+
"migration",
|
|
10
|
+
"geography"
|
|
11
|
+
],
|
|
12
|
+
"keywords": [
|
|
13
|
+
"irs",
|
|
14
|
+
"statistics of income",
|
|
15
|
+
"soi",
|
|
16
|
+
"income tax",
|
|
17
|
+
"tax returns",
|
|
18
|
+
"adjusted gross income",
|
|
19
|
+
"agi",
|
|
20
|
+
"agi by zip code",
|
|
21
|
+
"zip code income",
|
|
22
|
+
"county income",
|
|
23
|
+
"income by county",
|
|
24
|
+
"state income tax data",
|
|
25
|
+
"number of returns",
|
|
26
|
+
"salaries and wages",
|
|
27
|
+
"earned income credit",
|
|
28
|
+
"eitc",
|
|
29
|
+
"child tax credit",
|
|
30
|
+
"capital gains",
|
|
31
|
+
"itemized deductions",
|
|
32
|
+
"salt deduction",
|
|
33
|
+
"tax liability",
|
|
34
|
+
"migration",
|
|
35
|
+
"domestic migration",
|
|
36
|
+
"people moving",
|
|
37
|
+
"inflow",
|
|
38
|
+
"outflow",
|
|
39
|
+
"taxpayer migration",
|
|
40
|
+
"income moving between states"
|
|
41
|
+
],
|
|
42
|
+
"questions": [
|
|
43
|
+
"average adjusted gross income by ZIP code in Maryland",
|
|
44
|
+
"number of tax returns and total AGI by county",
|
|
45
|
+
"share of returns with income over $200,000 by state",
|
|
46
|
+
"earned income tax credit claims by county",
|
|
47
|
+
"how many taxpayers moved from New York to Florida and how much income they took",
|
|
48
|
+
"net migration of tax filers into Texas counties",
|
|
49
|
+
"state and local tax deduction by ZIP code"
|
|
50
|
+
],
|
|
51
|
+
"homepage": "https://www.irs.gov/statistics/soi-tax-stats-data-by-geographic-area",
|
|
52
|
+
"terms_url": "https://www.irs.gov/statistics/soi-tax-stats-about-soi",
|
|
53
|
+
"auth": {
|
|
54
|
+
"env": null,
|
|
55
|
+
"required": "none",
|
|
56
|
+
"placement": "none",
|
|
57
|
+
"param": null,
|
|
58
|
+
"prefix": "",
|
|
59
|
+
"home": null,
|
|
60
|
+
"signup_url": null,
|
|
61
|
+
"echoes_key": false,
|
|
62
|
+
"key_only": [],
|
|
63
|
+
"extra": {},
|
|
64
|
+
"demo_key": null
|
|
65
|
+
},
|
|
66
|
+
"limits": {
|
|
67
|
+
"rps": 1,
|
|
68
|
+
"burst": 3,
|
|
69
|
+
"daily_quota": null,
|
|
70
|
+
"errors_per_min": null,
|
|
71
|
+
"bytes_per_min": null,
|
|
72
|
+
"max_rows": 200000
|
|
73
|
+
},
|
|
74
|
+
"routes": {
|
|
75
|
+
"api": {
|
|
76
|
+
"base": "https://www.irs.gov/pub/irs-soi",
|
|
77
|
+
"probe": "https://www.irs.gov/robots.txt",
|
|
78
|
+
"hosts": [
|
|
79
|
+
"www.irs.gov"
|
|
80
|
+
]
|
|
81
|
+
},
|
|
82
|
+
"manual": {
|
|
83
|
+
"how": "Open the product's index page on irs.gov (ZIP code data: https://www.irs.gov/statistics/soi-tax-stats-individual-income-tax-statistics-zip-code-data-soi; county data: https://www.irs.gov/statistics/soi-tax-stats-county-data; state data: https://www.irs.gov/statistics/soi-tax-stats-historic-table-2; migration data: https://www.irs.gov/statistics/soi-tax-stats-migration-data), open the tax year (or filing-year pair) and download the all-states CSV named in INSTRUCTIONS.md (for example 22incyallagi.csv), then upload it unchanged; ingest filters it by the spec. The per-state Excel files are not read by ingest."
|
|
84
|
+
}
|
|
85
|
+
},
|
|
86
|
+
"cache": {
|
|
87
|
+
"mode": "run_only",
|
|
88
|
+
"ttl_hours": null,
|
|
89
|
+
"why": "Each request downloads one published all-states CSV (0.1 MB for state migration up to 216 MB for ZIP code data) and keeps only the asked rows; data/ is reused within a run only."
|
|
90
|
+
},
|
|
91
|
+
"redistribution": {
|
|
92
|
+
"mode": "allowed",
|
|
93
|
+
"why": "SOI tax statistics are U.S. government works in the public domain (17 U.S.C. 105) and are published already aggregated with disclosure protection; cite IRS SOI and the retrieval date."
|
|
94
|
+
},
|
|
95
|
+
"notices": [],
|
|
96
|
+
"retention": null,
|
|
97
|
+
"citation": "Internal Revenue Service, Statistics of Income Division, {dataset}, irs.gov/statistics, retrieved {retrieved_long}.",
|
|
98
|
+
"audit_hooks": [],
|
|
99
|
+
"clarify": [
|
|
100
|
+
"Which tax year (ZIP, county and state data) or which pair of filing years (migration: 2022-2023 compares addresses on returns filed in 2022 and 2023)? Default: the latest posted (tax year 2023; migration 2022-2023).",
|
|
101
|
+
"All returns combined, or broken out by AGI size class (agi_stub)? Averages such as AGI per return need the all-classes total (ZIP 00000 / county 000 rows or the no-AGI-class file).",
|
|
102
|
+
"Migration: people moving into the place (inflow) or out of it (outflow), between states or between counties? Net migration needs both."
|
|
103
|
+
],
|
|
104
|
+
"formats": [
|
|
105
|
+
"csv"
|
|
106
|
+
]
|
|
107
|
+
}
|
|
@@ -0,0 +1,124 @@
|
|
|
1
|
+
# IRS Statistics of Income: individual income tax data by geography (irs.gov)
|
|
2
|
+
Depth: standard. Key: none. Counts and amounts from all individual income tax returns (Forms 1040), by ZIP code,
|
|
3
|
+
county and state and by AGI size class, plus taxpayer migration between states and counties.
|
|
4
|
+
|
|
5
|
+
## When to use
|
|
6
|
+
- Number of returns, adjusted gross income (AGI), wages, dividends, capital gains, business income, deductions
|
|
7
|
+
(itemized, SALT, mortgage interest), credits (EITC, child tax credit) and tax liability for a ZIP code, county
|
|
8
|
+
or state; average AGI per return; the income mix of a place; returns with AGI of $200,000 or more (ZIP,
|
|
9
|
+
county) or $1 million or more (state).
|
|
10
|
+
- Households (returns), people and AGI moving into or out of a state or county between two filing years.
|
|
11
|
+
- Not here: person- or household-level income, poverty and median household income (census: ACS); personal
|
|
12
|
+
income and GDP by state or county (bea); national tables such as Publication 1304 / Table 1.1 (SOI publishes
|
|
13
|
+
them as .xls workbooks only: https://www.irs.gov/statistics/soi-tax-stats-individual-statistical-tables-by-size-of-adjusted-gross-income;
|
|
14
|
+
manual); business, corporate, estate and exempt-organization statistics (other SOI pages, not covered);
|
|
15
|
+
tax-return microdata: the Individual Public-Use Microdata File is not public (it was sold under license; tax
|
|
16
|
+
years 2012-2015 are no longer available, and SOI has announced a synthetic file instead), so no row-level data.
|
|
17
|
+
|
|
18
|
+
## Endpoints and datasets
|
|
19
|
+
One all-states CSV per year under `https://www.irs.gov/pub/irs-soi/` (verified 2026-10-30). The adapter
|
|
20
|
+
picks the file, downloads it, and keeps only the asked rows (and `columns`) while reading.
|
|
21
|
+
|
|
22
|
+
| Endpoint (alias) | File | Rows | Years | Size |
|
|
23
|
+
|---|---|---|---|---|
|
|
24
|
+
| `zip_agi` (`zip`) | `{yy}zpallagi.csv`; `agi_classes: false` = `{yy}zpallnoagi.csv` | state x ZIP x AGI class 1-6 | TY2011-2023 | 216 MB (TY2022) |
|
|
25
|
+
| `county_agi` (`county`) | `{yy}incyallagi.csv`; `agi_classes: false` = `{yy}incyallnoagi.csv` | state x county x AGI class 1-8 | TY2011-2023 | 36 MB |
|
|
26
|
+
| `state_agi` (`state`) | `{yy}in55cmcsv.csv` (2019-2023), `18in55cmagi.csv`, `{yy}in54cmcsv.csv` (2012, 2014-2017) | state x AGI class 0-10 | TY2012, 2014-2023 | 0.8 MB |
|
|
27
|
+
| `migration` (`migration`) | `{state,county}{inflow,outflow}{y1y2}.csv` | focus place x other place | filing years 2011-2012 to 2022-2023 | 0.1 / 4.5 MB |
|
|
28
|
+
|
|
29
|
+
Parameters: `tax_year` (or `start_year`/`end_year`, one file each), `state` (USPS, FIPS or name, or a list;
|
|
30
|
+
`state_agi` also takes `US`, `PR`, `OA`), `zipcode` (5-digit strings), `county` (3-digit code with `state`,
|
|
31
|
+
5-digit FIPS, or the published name such as "Montgomery County"), `agi_stub`, `agi_classes`, `columns` (e.g.
|
|
32
|
+
`["N1", "A00100"]`; identifier columns always kept). `zip_agi` requires `state` or `zipcode`. Migration:
|
|
33
|
+
`level` (state|county), `direction` (inflow|outflow), `y1` (or `start_y1`/`end_y1`) = the first filing year
|
|
34
|
+
(2022 = the 2022-2023 file), `state` and `county` = the place whose inflow or outflow is kept.
|
|
35
|
+
Latest posted (checked 2026-10-30): TY2023 for ZIP, county and state data; 2022-2023 for migration. A year
|
|
36
|
+
not posted yet ends with `not_found` naming the file. Variable lists and layouts: each year's users guide on
|
|
37
|
+
the index pages (ZIP `{yy}zpdoc.docx`, county `{yy}incydocguide.docx`, state `{yy}incmdocguide.doc`,
|
|
38
|
+
migration `{y1y2}inpublicmigdoc.pdf`).
|
|
39
|
+
|
|
40
|
+
## Spec examples
|
|
41
|
+
```json
|
|
42
|
+
{"description": "Maryland counties, tax year 2022: returns and AGI by AGI class",
|
|
43
|
+
"requests": [{"name": "md_county", "endpoint": "county_agi",
|
|
44
|
+
"params": {"tax_year": 2022, "state": "MD", "columns": ["N1", "N2", "A00100", "A00200"]}}]}
|
|
45
|
+
```
|
|
46
|
+
```json
|
|
47
|
+
{"description": "Two ZIP codes, all returns, 2021-2023",
|
|
48
|
+
"requests": [{"name": "zips", "endpoint": "zip_agi",
|
|
49
|
+
"params": {"start_year": 2021, "end_year": 2023, "state": "MD", "zipcode": ["20601", "20852"],
|
|
50
|
+
"agi_classes": false, "columns": ["N1", "A00100"]}}]}
|
|
51
|
+
```
|
|
52
|
+
```json
|
|
53
|
+
{"description": "Moves into and out of Florida, 2022-2023",
|
|
54
|
+
"requests": [{"name": "fl_in", "endpoint": "migration",
|
|
55
|
+
"params": {"level": "state", "direction": "inflow", "y1": 2022, "state": "FL"}},
|
|
56
|
+
{"name": "fl_out", "endpoint": "migration",
|
|
57
|
+
"params": {"level": "state", "direction": "outflow", "y1": 2022, "state": "FL"}}]}
|
|
58
|
+
```
|
|
59
|
+
|
|
60
|
+
## Data format and traps
|
|
61
|
+
- Output `data/irs-soi/<name>.csv` in the workspace. Column names are upper-cased (the files mix `agi_stub`/`AGI_STUB`,
|
|
62
|
+
`zipcode`/`ZIPCODE`, `mars1`/`MARS1`, `n1`/`N1`); `TAX_YEAR` (migration: `Y1_YEAR`, `Y2_YEAR`) comes
|
|
63
|
+
first. Numbers are written without thousands separators or trailing zero decimals (the state files print
|
|
64
|
+
`3,095,140`, the county and ZIP files `40530.0000`); nothing else is changed.
|
|
65
|
+
- Units: `N...` = number of returns with the item (N1 all returns, N2 individuals); `A...` = amount in
|
|
66
|
+
**thousands of dollars** (A00100 = AGI, A00200 = wages, A59660 = EITC, A10300 = total tax liability, A18425 /
|
|
67
|
+
A18500 = state and local income / real estate taxes). AGI per return = A00100 * 1000 / N1. Returns are
|
|
68
|
+
rounded to the nearest 10 (ZIP, county, state; ZIP and county since at least TY2016).
|
|
69
|
+
- Tax year vs filing year: TY2022 files tabulate returns processed in calendar 2023, mostly for tax year 2022,
|
|
70
|
+
with a few late prior-year returns as a proxy for returns filed later. Migration years are filing years:
|
|
71
|
+
2022-2023 compares addresses on returns filed in 2022 (TY2021) and 2023 (TY2022); N2 and AGI come from the
|
|
72
|
+
year-2 return, so AGI is TY2022 income. Not everyone files: these are filers, not the population.
|
|
73
|
+
- AGI classes (`AGI_STUB`), checked in the users guides: ZIP 1 = $1 under $25,000, 2 = $25,000-50,000, 3 =
|
|
74
|
+
50,000-75,000, 4 = 75,000-100,000, 5 = 100,000-200,000, 6 = $200,000 or more (same 2011-2023; returns with
|
|
75
|
+
negative AGI are excluded from ZIP data). County 2012-2023: 1 = under $1 (zero or negative AGI, so A00100
|
|
76
|
+
can be negative), 2 = $1-10,000, 3 = 10,000-25,000, 4 = 25,000-50,000, 5 = 50,000-75,000, 6 = 75,000-100,000,
|
|
77
|
+
7 = 100,000-200,000, 8 = $200,000 or more; county TY2011 had 7 classes (2 = $1 under $25,000). State:
|
|
78
|
+
0 = all returns, 1-7 as county, 8 = 200,000-500,000, 9 = 500,000-1,000,000, 10 = $1,000,000 or more. The
|
|
79
|
+
no-class files have AGI_STUB 0.
|
|
80
|
+
- Totals inside the files: ZIP `00000` = the state total and `99999` = ZIPs with fewer than 100 returns or a
|
|
81
|
+
single building/nonresidential ZIP combined; county `COUNTYFIPS 000` = the state total. Drop them before
|
|
82
|
+
summing places. State totals here differ from the state file (`state_agi`, the complete tabulation):
|
|
83
|
+
ZIP/county data drop returns without a ZIP or with a ZIP that does not match the state, and APO/FPO,
|
|
84
|
+
foreign and territory addresses (TY2022 Maryland N1: 3,054,110 in ZIP data vs 3,095,140 in state data).
|
|
85
|
+
- Disclosure: items with fewer than 20 returns in an AGI class are merged into another class of the same ZIP or
|
|
86
|
+
county (marked `**` in the Excel files only; the CSV gives no flag), items with fewer than 20 returns in the
|
|
87
|
+
place are dropped, and a return dominating a cell is removed from it. The CSV files have no empty cells
|
|
88
|
+
(checked in 22zpallagi.csv): a dropped item shows as 0, so a 0 in a small place or class can mean
|
|
89
|
+
"suppressed" as well as "none"; small places and classes are approximate.
|
|
90
|
+
- State file: 50 states, DC, `OA` (other areas: APO/FPO, citizens abroad) and `US` (total); `PR` (Puerto
|
|
91
|
+
Rico) from TY2018 (checked in the 2012-2023 files).
|
|
92
|
+
- Geography: STATEFIPS and COUNTYFIPS are text with leading zeros (keep them as strings; county FIPS =
|
|
93
|
+
STATEFIPS + COUNTYFIPS). COUNTYNAME is cut to 20 characters ("Prince George's Coun" in TY2022): filter and
|
|
94
|
+
join on FIPS, not names (a `county` name still matches a cut name it begins with). The address is the mailing address on the return and is assigned to a county from
|
|
95
|
+
its ZIP code; ZIP codes are USPS codes, not Census ZCTAs.
|
|
96
|
+
- Variables change by year (e.g. TY2023 added N07262/N07265 and dropped N07260); a `columns` item missing in a
|
|
97
|
+
year gives a note. Check the year's users guide before comparing an item across years.
|
|
98
|
+
- Migration rows (`ROW_TYPE`, added by the adapter): `total_us_and_foreign` (code 96), `total_us` (97),
|
|
99
|
+
`total_same_state` (97; county 97/001), `total_different_state` (county 97/003), `total_foreign` (98),
|
|
100
|
+
`non_migrants` (same place both years), `foreign` (57: overseas, Puerto Rico, APO/FPO, Virgin Islands),
|
|
101
|
+
`other_flows` (58/59: county flows under 20 returns pooled as same state, different state, or by region),
|
|
102
|
+
`flow` (one origin-destination pair), `state_summary` (state header rows in 2011-2017 county files). Sum
|
|
103
|
+
only `flow` rows, or use the totals; never sum all rows. Net migration = inflow minus outflow from the two
|
|
104
|
+
files for the same place and years.
|
|
105
|
+
- Migration suppression: cells below 10 returns (state) or 20 (county) are published as `-1`; the adapter
|
|
106
|
+
writes them empty and names them in `SUPPRESSED`. Since 2018-2019 county files have no state totals (use the
|
|
107
|
+
state files) and county flows need not add to state totals. The 2022-2023 file uses an updated return
|
|
108
|
+
matching that includes about 5 percent more returns than the prior method, and 2011-2012 started a new series
|
|
109
|
+
(primary, secondary and dependent TINs matched): mark the break when comparing across these years.
|
|
110
|
+
- Migration covers matched filers only: a filer who did not file in both years, or switched between an ITIN and
|
|
111
|
+
an SSN, is not counted; dependents in year 2 are excluded.
|
|
112
|
+
|
|
113
|
+
## Access
|
|
114
|
+
No key. `fetch` downloads when www.irs.gov answers: one GET per file; `zip_agi` streams the file (about 216 MB) to a
|
|
115
|
+
temporary folder outside the workspace, filters it and deletes it, so it needs disk space and about a minute.
|
|
116
|
+
Manual route (`manual_bundle`): INSTRUCTIONS.md lists the direct link of each file (the all-states CSV under its published name,
|
|
117
|
+
e.g. `22incyallagi.csv`); download it from the index page (ZIP: soi-tax-stats-individual-income-tax-statistics-zip-code-data-soi,
|
|
118
|
+
county: soi-tax-stats-county-data, state: soi-tax-stats-historic-table-2, migration: soi-tax-stats-migration-data,
|
|
119
|
+
all under https://www.irs.gov/statistics/), upload it unchanged, and `ingest` filters it like `fetch` does.
|
|
120
|
+
Per-state Excel files, years before the CSV files, and the national .xls tables are manual and not read here.
|
|
121
|
+
|
|
122
|
+
## Citation and terms
|
|
123
|
+
"Internal Revenue Service, Statistics of Income Division, <product, e.g. County Data, Tax Year 2022>,
|
|
124
|
+
irs.gov/statistics, retrieved <date>." Public domain (U.S. government work); redistribution allowed.
|