IRS SOI (income by ZIP)

Confirm a ZIP has SOI data and return its return and individual counts. `zip_code`: a 5-digit US ZIP. A good first call to validate a ZIP before asking for more detail. Returns the state, number of returns, number of individuals, and the SOI tax year. ZIPs with <100 returns are excluded.

Income measures for a ZIP: AGI, average AGI per return, and components. `zip_code`: a 5-digit US ZIP. Returns total adjusted gross income (AGI), average AGI per return, and the main income components — salaries and wages, taxable interest, ordinary dividends, business net income, and net capital gain. All dollar amounts in USD. Note: figures cover filed tax returns only. Average AGI is a *mean per return*, not a median per household, and AGI omits most nontaxable income — so it is not directly comparable to Census median household income.

The income distribution of a ZIP across the six IRS AGI brackets. `zip_code`: a 5-digit US ZIP. Returns, for each bracket (<$25k, $25-50k, $50-75k, $75-100k, $100-200k, $200k+), the number of returns and total AGI plus each bracket's share of the ZIP's returns and AGI. This is the income *shape* of a ZIP — what a single median can't show. Note: a bracket showing 0 may be IRS-suppressed (<20 returns in that cell) rather than truly empty, so the other brackets' shares can be slightly overstated.

Tax measures for a ZIP: income tax, total liability, and average per return. `zip_code`: a 5-digit US ZIP. Returns income tax, income tax before credits, total tax liability (broader — includes self-employment tax and other taxes), total tax payments, and the average total tax per return. Amounts in USD.

Refundable-credit take-up for a ZIP: the EITC and additional child tax credit. `zip_code`: a 5-digit US ZIP. Returns the number of returns and total amount for the Earned Income Tax Credit (overall and split by number of qualifying children: none / one / two / three or more), plus the additional (refundable) child tax credit. Amounts in USD. Note: a 0 may be IRS-suppressed (<20 returns in each AGI-bracket cell) rather than a true zero — it does not prove no one claims the credit.

Deduction measures for a ZIP: standard vs. itemized, plus SALT. `zip_code`: a 5-digit US ZIP. Returns the count and amount of standard deductions and itemized deductions, the taxes-paid (SALT) deduction, and the percent of returns that itemized. Amounts in USD. Note: a 0 may be IRS-suppressed (<20 returns in each AGI-bracket cell) rather than a true zero — it does not prove no one in the ZIP itemizes.

Filing-status mix for a ZIP: single / married-joint / head-of-household. `zip_code`: a 5-digit US ZIP. Returns the number of single, married-filing- jointly, and head-of-household returns, the number of elderly returns (age 65+), and the count and share of electronically filed returns. Note: a 0 count may be IRS-suppressed (<20 returns in each AGI-bracket cell) rather than truly absent.

Rank several ZIPs by a single metric, highest value first. `zips`: a list of 5-digit US ZIPs to compare. `metric`: one of `total_returns`, `adjusted_gross_income`, `avg_agi_per_return`, `pct_returns_200k_plus`, `total_income`, `salaries_and_wages`, `income_tax`, `total_tax_liability`, `avg_total_tax_per_return`, `eitc_amount`. Returns each ZIP's value, sorted descending; ZIPs with no SOI data are listed last. A 0 for a sparse metric (e.g. `eitc_amount`) may be IRS-suppressed, not a true zero.

State-level SOI totals and AGI distribution from the IRS state rollup. `state`: a 2-letter USPS code (e.g. 'CA') or full state name (e.g. 'California'). Returns the state's total returns, individuals, AGI, average AGI per return, income tax, total tax liability, and the income distribution across the six AGI brackets. Drawn from the IRS 00000 state-total row.

Raw value of a single SOI field for a ZIP — an escape hatch. `zip_code`: a 5-digit US ZIP. `field`: a SOI field code (e.g. `A00100` for AGI, `N1` for number of returns); case-insensitive. Returns that field summed across the ZIP's AGI brackets, with its label and unit (USD for amount fields, count for return counts). Limited to the fields held in the local store (the same ones the other tools draw on); an unknown field errors with the list. Note: a 0 may be IRS-suppressed (<20 returns in a cell) rather than a true zero, and a sum over suppressed cells slightly understates the real total.