% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/individuals.R
\name{ato_individuals_postcode}
\alias{ato_individuals_postcode}
\title{Individual tax data by postcode}
\source{
Australian Taxation Office Taxation Statistics
postcode release. Licensed CC BY 2.5 AU.
}
\usage{
ato_individuals_postcode(year = "latest", state = NULL, postcode = NULL)
}
\arguments{
\item{year}{\code{"YYYY-YY"} or \code{"latest"}. Pass a vector of years
(e.g. \code{c("2020-21", "2021-22", "2022-23")} or \code{2018:2022})
to stack multiple years with a \code{year} column added to the
output. Useful for time-series analysis.}

\item{state}{Optional character vector of state codes (e.g.
\code{"NSW"}, \code{c("VIC", "QLD")}).}

\item{postcode}{Optional character vector of 4-digit postcodes.}
}
\value{
An \code{ato_tbl} with one row per postcode (or per postcode
per year for multi-year queries), including state, return
count, total income, taxable income, and tax payable. Schema
drifts year to year (SA3/SA4 columns present from 2017
onwards).
}
\description{
Returns the Individuals Table 6 (or standalone postcode
dataset): taxable income, tax payable, and return counts by
4-digit postcode. Headline dataset for income-distribution
journalism.
}
\details{
\strong{Privacy suppression.} The ATO suppresses postcodes with
fewer than 50 returns; those cells are returned as \code{NA} after
parsing (the package maps \code{"np"}, \code{"*"}, and similar tokens
to \code{NA} so numeric columns stay numeric). Small or remote
postcodes will be silently missing from the output.

Monetary values are nominal AUD of the reporting year. Use
\code{inflateR::inflate()} for real-term series.
}
\examples{
\donttest{
op <- options(ato.cache_dir = tempdir())
try({
  # Single year
  p <- ato_individuals_postcode(year = "2022-23", state = "NSW")
  head(p)
  # Multi-year stack with year column
  panel <- ato_individuals_postcode(year = c("2020-21", "2021-22"),
                                    state = "NSW")
})
options(op)
}
}
\references{
Atkinson, A.B. and Leigh, A. (2007). "The Distribution of Top
Incomes in Australia." \emph{Economic Record}, 83(262),
247-261. \doi{10.1111/j.1475-4932.2007.00412.x}

Burkhauser, R.V., Hahn, M.H. and Wilkins, R. (2015). "Measuring
top incomes using tax record data: a cautionary tale from
Australia." \emph{Journal of Economic Inequality}, 13(2),
181-205. \doi{10.1007/s10888-014-9281-z}
}
\seealso{
Other individuals: 
\code{\link{ato_individuals}()},
\code{\link{ato_individuals_age}()},
\code{\link{ato_individuals_occupation}()},
\code{\link{ato_individuals_sex}()},
\code{\link{ato_individuals_state}()}
}
\concept{individuals}
