Data dictionary

This dictionary describes the core public place-record contract defined in the current repository schemas. Individual data families may add fields. Consumers must tolerate additive fields and must not assume optional modules are present on every geographic tier.

Foundation identifiers

Field	Type	Meaning	Notes
geo_type / geo_type_id	string enum	Geographic family	Includes county, nation, region, division, state, congressional district, state-legislative district, CBSA, CSA, DMA, Census place/city, custom shape, and American Nation
geo_id	string	Stable geography identifier	County records use five-digit FIPS; other tiers may use Census GEOIDs, postal abbreviations, district codes, or family-specific keys
name	string	Display name	Do not use name alone as a unique key
state / state_abbr	string or null	State context	May be absent or multi-state for national, regional, metro, market, or custom geographies
source / provenance fields	object or string	Source and data-vintage metadata	Shape varies by family; retain it with any extracted figure

Election result object

Field	Type	Unit	Meaning and constraints
year	integer	calendar year	Schema accepts 1876 onward; the complete public presidential record claim is 1892–2024
dem	integer or null	votes	Democratic subtotal; null means unavailable, not zero
rep	integer or null	votes	Republican subtotal
other	integer or null	votes	All other candidates/lines not included in the two major-party subtotals
total	integer or null	votes	Certified or reconciled total represented by the record
margin	number or null	proportion from -1 to 1	Democratic share minus Republican share. Multiply by 100 for percentage points. A stored 0.084 is displayed as D+8.4, not D+0.084
winner	D, R, O, or N	category	Democratic, Republican, other, or no winner/no result
perot, nader	integer or null	votes	Optional named historical third-party counts retained for compatibility
third	object or null	candidate record	Leading named third-party/independent finisher; estimated: true means attribution was inferred from a surviving aggregate rather than itemized local candidate rows
candidates	array	candidate records	Present only where itemized rows reconcile to the aggregate contract
candidates_complete	boolean	flag	True when candidate-grain rows are complete and reconciled
candidates_source	string	source label	Source for candidate-grain rows
resolution	enum	method	For custom shapes: county_exact, bg_reconciled, legacy bg, county, or county_period

Margin gotcha

The stored election margin is a proportion, while much of the interface displays percentage points. Convert once:

display_margin_points = stored_margin * 100

Do not multiply a display value by 100 again.

Named candidate object

Field	Type	Meaning
name	string	Candidate name
party	string	Reported party or ballot label
votes	nonnegative integer	Candidate votes
party_key	optional D, R, or O	Normalized grouping for display/aggregation
write_in	optional boolean	Candidate was reported as write-in
estimated	optional boolean on third	Candidate identity/count assignment was inferred from incomplete candidate-grain data

Demographics

Field	Type	Unit / universe	Meaning
totalPopulation	integer	people	Total population for the documented ACS/Census vintage
cvap	integer, null, or absent	US citizens age 18+	Citizen voting-age population; optional because not every tier/bake has the same source path
medianAge	number	years	Median age
populationPeak.year	integer	year	Year of the maximum population in the available series
populationPeak.value	integer	people	Peak population value
populationChange50yrPct	number	percent	Change across the documented 50-year comparison window
races	array	percent of total population	Race/ethnicity groups; rows include key, label, percentOfTotal, and nested ancestry detail
age	array	percent	Age-band rows with male and female shares
income.medianHouseholdIncome	number	inflation-adjusted dollars for source vintage	Median household income
income.stateMedian	number	dollars	State comparison value
income.usMedian	number	dollars	National comparison value
income.countyRankNational	optional integer	rank	County-only national rank; absence on another tier is expected
income.pct200kPlusHouseholds	optional number	percent of households	Households with income at least $200,000
poverty.overallRate	number	percent	Overall poverty rate
poverty.childrenRate	number	percent	Child poverty rate
poverty.workingAgeRate	number	percent	Working-age poverty rate
poverty.seniorsRate	number	percent	Senior poverty rate
language.englishOnlyPct	number	percent of documented language universe	English-only share
language.topNonEnglish	array	percent	Named non-English language rows
education.baOrHigherPct	number	percent of population age 25+	Bachelor's degree or higher
education.highSchoolOrHigherPct	optional number	percent of population age 25+	High school graduate or higher
education.graduateOrProfessionalPct	optional number	percent of population age 25+	Graduate or professional degree
religion.adherents	optional array	percent of population or documented denominator	Religion-adherence rows from the source model
religion.unaffiliatedPct	optional number	percent	Estimated no-congregation/unaffiliated context
religionContext	optional object	commuting-zone context	Service-shed context used for sparse or small counties; not the same as a direct county count

Race and ancestry

percentOfTotal uses 0–100 percentage values, unlike the election margin proportion. An ancestry row may carry residual: true when it is calculated from real ACS cells as a residual category. A residual flag does not mean fabricated data; it means the row is derived from documented components rather than directly tabulated as one source cell.

Voter registration year

Field	Type	Unit	Meaning
year	integer	year	Snapshot year
total	number or null	registered voters	Universal total where reported
active	optional number or null	voters	Active registration where source distinguishes status
inactive	optional number or null	voters	Inactive registration where source distinguishes status
byParty.dem	optional number or null	voters	Democratic registration
byParty.rep	optional number or null	voters	Republican registration
byParty.unaffiliated	optional number or null	voters	No-party/independent registration
byParty.other	optional number or null	voters	Other registered parties
partial	optional boolean	flag	Not every constituent unit reported; the rollup understates the full geography

Party registration is absent in states that do not register voters by party. Absence must not be interpreted as zero support for a party.

Null, missing, and zero

• 0 is a reported or derived numeric zero.
• null means the field is part of the schema but unavailable for that record.
• an absent optional field means the module was not populated or does not apply to that tier.
• a suppression or estimate flag carries additional meaning and must be retained.

Provenance checklist

For every extracted measure retain the place identifier, geographic type, field path, source vintage, Akashic release/as-of metadata, and any resolution, partial, estimated, residual, or suppression flag.

The repository's runtime schema remains the final machine contract. This page is reviewed against lib/types.ts and should be updated whenever a public schema changes.