Get a raw SOI field
get_soi_fieldRead-only
Get any single IRS SOI statistic for a U.S. ZIP code: provide a field code (e.g., A00100 for AGI) to receive the summed value, label, and unit across income brackets.
Instructions
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.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| field | Yes | ||
| zip_code | Yes |
Output Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| unit | Yes | 'USD' for amount fields, 'count' for return counts | |
| field | Yes | SOI field code, e.g. 'A00100' or 'N1' | |
| label | Yes | Human-readable description of the field | |
| state | No | 2-letter USPS state code | |
| value | No | The field's value for this ZIP (summed over brackets) | |
| zipcode | Yes | 5-digit ZIP code | |
| tax_year | Yes | SOI tax year of the data |