DataAppend · ZIP Reference

Using the API

Every file is static and public. No key, no rate limit beyond GitHub Pages.

Path	Returns
`zip/{ZIP}.json`	One ZIP's record. A 404 means the ZIP isn't in any of the source files.
`zips.csv`	All ZIPs in one flat file, for batch joins.
`meta.json`	Build date, data vintages and source URLs.

fetch("zip/58645.json").then(r => r.json())

curl -s https://append.labs.trlibrary.com/zip/58645.json

Fields

Field	Meaning
`mail_city, state`	Post office name for the ZIP (the mailing city).
`place, county`	Incorporated city (or Census place) and county with the most land overlap.
`zip_type`	`area` for residential ZIPs; `po_box_or_unique` for PO-box and large-organization ZIPs, which carry no Census or IRS figures.
`ruca, urban_rural`	USDA Rural-Urban Commuting Area code (1–10) and its class: metro, micro, small town or rural.
`miles_to_library, distance_band`	Straight-line miles from Medora to the ZIP's center, grouped as local, regional drive, long drive, fly-in. For PO-box ZIPs the point is borrowed from the same town's residential ZIP, named in `point_from_zip`.
`acs.*`	Census American Community Survey 5-year estimates: population, median age, median household income (with a reliability grade from its margin of error), per-capita income, share of households earning $200K+, median home value, owner-occupancy, bachelor's and graduate degree shares, and shares of residents 65 and older, of adults who are veterans, and of households with children.
`acs.top_coded`	Medians the Census caps: 250,001 means $250,000 or more; 2,000,001 means $2 million or more.
`irs.*`	IRS Statistics of Income: returns filed, average adjusted gross income, share of returns over $200K, with dividends, with capital gains, and itemizing charitable gifts, plus the average itemized charitable deduction; shares of returns with pension income, IRA distributions, business (Schedule C) income, and partnership or S-corporation income; and average real-estate taxes among itemizers.
`index.affluence_percentile, tier`	National percentile (1–100) of a composite of five measures; tiers A (90+), B (75–89), C (50–74), D (25–49), E (under 25).

How to read it

These figures describe a neighborhood, not a person. A Tier A ZIP is a reason to look closer at a contact, never evidence of that contact's wealth. Use them for segmentation, regional planning and prioritizing research, and never in copy addressed to an individual.

Small places are noisy. Records flag small_population (under 500 people) and small_sample (under 250 tax returns). The IRS rounds counts and suppresses small cells, so a small ZIP can show 0% where the true figure is low but not zero.
Itemized figures undercount. Since 2018 most households take the standard deduction, so pct_returns_itemizing_charity and avg_itemized_real_estate_taxes mostly reflect higher-income itemizers. Compare ZIPs with it; don't read it as a giving rate.
ZIP and ZCTA differ slightly. Census data is by ZIP Code Tabulation Area, IRS data by postal ZIP. They match for most residential ZIPs.
The index averages national percentile ranks of median household income, share of households at $200K+, median home value, share with a bachelor's degree, and IRS average AGI (skipped for small samples), then ranks that average again. ZIPs under 200 people, or with fewer than three usable measures, get no index.

Sources

Loading…