Skip to main content

us_property_tax_data/
lib.rs

1//! This crate embeds the 2026 United States residential property tax dataset compiled by the
2//! [Calcuris Data Team](https://calcuris.com/) — effective property tax rates, median annual
3//! taxes paid, median home values and median household incomes for the 50 states plus the
4//! District of Columbia and for 3,132 individual counties — and exposes a small,
5//! zero-dependency Rust API to query it. Both source CSVs are embedded in the binary via
6//! `include_str!` and parsed on demand by a tiny internal parser.
7//!
8//! # Where the numbers come from
9//!
10//! The data is not modelled or interpolated. County figures are the published medians of the
11//! U.S. Census Bureau's American Community Survey, ACS 2023 5-year estimates (tables `B25103`
12//! real-estate taxes paid, `B25077` home value, `B19013` household income); the effective rate
13//! is the standard ratio of medians (median tax ÷ median home value) used by the Tax
14//! Foundation and SmartAsset. State-level effective rates follow the Tax Foundation's 2024
15//! table as republished in June 2026. The full methodology, dataset DOI
16//! ([10.5281/zenodo.21454886](https://doi.org/10.5281/zenodo.21454886)) and citation
17//! instructions are on the [cite-this-data page](https://calcuris.com/cite-this-data/).
18//!
19//! # Going further
20//!
21//! This crate deliberately ships raw data with no simulation logic. For interactive use, the
22//! same dataset powers the
23//! [US property tax calculator](https://calcuris.com/us/property-tax-calculator/) on
24//! calcuris.com, which resolves rates down to individual cities (10,058 of them) with
25//! per-state pages such as
26//! [New Jersey — the most-taxed state](https://calcuris.com/us/property-tax-calculator/new-jersey/).
27//! Every calculator can also be [embedded for free](https://calcuris.com/embed-calculators/)
28//! on your own site.
29//!
30//! # Example
31//!
32//! ```rust
33//! use us_property_tax_data::{states, state, counties, highest_rate_states};
34//!
35//! // New Jersey: highest effective property tax rate in the country.
36//! let nj = state("NJ").unwrap();
37//! assert_eq!(nj.effective_rate_pct, 1.88);
38//! assert_eq!(nj.median_tax_usd, 9590);
39//!
40//! // All 51 jurisdictions, and the top of the ranking.
41//! assert_eq!(states().len(), 51);
42//! let top = highest_rate_states(3);
43//! assert!(top.iter().any(|s| s.state_code == "NJ"));
44//!
45//! // Every county of a state, ranked by effective rate.
46//! let texas = counties("TX");
47//! assert!(texas.len() > 200);
48//! assert!(texas[0].effective_rate_pct >= texas[texas.len() - 1].effective_rate_pct);
49//! ```
50
51/// One state-level row of the 2026 dataset (50 states + DC).
52#[derive(Debug, Clone, PartialEq)]
53pub struct StateRow {
54    pub state_code: &'static str,
55    pub state_name: &'static str,
56    /// Effective rate in percent: median annual tax ÷ median home value × 100.
57    pub effective_rate_pct: f64,
58    /// Median annual real-estate taxes paid, US dollars.
59    pub median_tax_usd: u32,
60    /// Median owner-occupied home value, US dollars.
61    pub median_home_value_usd: u32,
62}
63
64/// One county-level row of the 2026 dataset (3,132 counties).
65#[derive(Debug, Clone, PartialEq)]
66pub struct CountyRow {
67    pub fips: &'static str,
68    pub county_name: &'static str,
69    pub state_code: &'static str,
70    pub effective_rate_pct: f64,
71    pub median_tax_usd: u32,
72    pub median_home_value_usd: u32,
73    pub median_household_income_usd: u32,
74    /// Rank of the effective rate inside the state (1 = highest).
75    pub rank_in_state: u32,
76}
77
78const STATE_CSV: &str = include_str!("../data/us_property_tax_by_state_2026.csv");
79const COUNTY_CSV: &str = include_str!("../data/us_property_tax_by_county_2026.csv");
80
81fn split_line(line: &'static str) -> Vec<&'static str> {
82    // Le CSV embarqué ne contient pas de champs quotés multi-virgules côté états ;
83    // côté comtés les noms peuvent contenir des virgules quotées.
84    let mut out = Vec::new();
85    let mut rest = line;
86    while !rest.is_empty() {
87        if let Some(stripped) = rest.strip_prefix('"') {
88            let end = stripped.find('"').unwrap_or(stripped.len());
89            out.push(&stripped[..end]);
90            rest = stripped[end..].trim_start_matches('"').trim_start_matches(',');
91        } else {
92            match rest.find(',') {
93                Some(i) => {
94                    out.push(&rest[..i]);
95                    rest = &rest[i + 1..];
96                }
97                None => {
98                    out.push(rest);
99                    rest = "";
100                }
101            }
102        }
103    }
104    out
105}
106
107/// All 51 state-level rows (50 states + DC), in CSV order (alphabetical by code).
108pub fn states() -> Vec<StateRow> {
109    STATE_CSV
110        .lines()
111        .skip(1)
112        .filter(|l| !l.trim().is_empty())
113        .map(|l| {
114            let f = split_line(l);
115            StateRow {
116                state_code: f[0],
117                state_name: f[1],
118                effective_rate_pct: f[2].parse().unwrap(),
119                median_tax_usd: f[3].parse().unwrap(),
120                median_home_value_usd: f[4].parse().unwrap(),
121            }
122        })
123        .collect()
124}
125
126/// Look up one state by its two-letter code (case-insensitive). `None` if unknown.
127pub fn state(code: &str) -> Option<StateRow> {
128    let code = code.to_ascii_uppercase();
129    states().into_iter().find(|s| s.state_code == code)
130}
131
132/// The `n` states with the highest effective property tax rate, descending.
133pub fn highest_rate_states(n: usize) -> Vec<StateRow> {
134    let mut all = states();
135    all.sort_by(|a, b| b.effective_rate_pct.partial_cmp(&a.effective_rate_pct).unwrap());
136    all.truncate(n);
137    all
138}
139
140/// The `n` states with the lowest effective property tax rate, ascending.
141pub fn lowest_rate_states(n: usize) -> Vec<StateRow> {
142    let mut all = states();
143    all.sort_by(|a, b| a.effective_rate_pct.partial_cmp(&b.effective_rate_pct).unwrap());
144    all.truncate(n);
145    all
146}
147
148/// Every county of a state (two-letter code, case-insensitive), ordered by in-state rank
149/// (highest effective rate first). Empty if the code is unknown.
150pub fn counties(state_code: &str) -> Vec<CountyRow> {
151    let code = state_code.to_ascii_uppercase();
152    let mut rows: Vec<CountyRow> = COUNTY_CSV
153        .lines()
154        .skip(1)
155        .filter(|l| !l.trim().is_empty())
156        .filter_map(|l| {
157            let f = split_line(l);
158            if f[2] != code {
159                return None;
160            }
161            Some(CountyRow {
162                fips: f[0],
163                county_name: f[1],
164                state_code: f[2],
165                effective_rate_pct: f[3].parse().ok()?,
166                median_tax_usd: f[4].parse().ok()?,
167                median_home_value_usd: f[5].parse().ok()?,
168                median_household_income_usd: f[6].parse().ok()?,
169                rank_in_state: f[7].parse().ok()?,
170            })
171        })
172        .collect();
173    rows.sort_by_key(|r| r.rank_in_state);
174    rows
175}
176
177#[cfg(test)]
178mod tests {
179    use super::*;
180
181    #[test]
182    fn fifty_one_jurisdictions() {
183        assert_eq!(states().len(), 51);
184    }
185
186    #[test]
187    fn nj_is_the_ceiling_hi_the_floor() {
188        assert_eq!(state("nj").unwrap().effective_rate_pct, 1.88);
189        assert_eq!(state("HI").unwrap().effective_rate_pct, 0.29);
190        assert!(highest_rate_states(2).iter().all(|s| s.effective_rate_pct >= 1.88));
191        assert_eq!(lowest_rate_states(1)[0].state_code, "HI");
192    }
193
194    #[test]
195    fn counties_parse_and_rank() {
196        let tx = counties("TX");
197        assert!(tx.len() > 200);
198        assert_eq!(tx[0].rank_in_state, 1);
199        let total: usize = ["CA", "NY", "FL"].iter().map(|c| counties(c).len()).sum();
200        assert!(total > 150);
201    }
202}