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}