Skip to main content
Public ancestry contract

Ancestry API and release docs

This is the public site contract for the ancestry atlas. It is separate from the paid /api/v1 developer platform and exists to describe the JSON feeds that power ancestry atlas and dossier pages.

Contract version
V1
Indexed dossiers
39
Experimental atlas entries
75
Source window
ACS 2024 + modeled 2000-2024 politics
Contract policy

/api/ancestry remains the rows-only convenience feed. /api/ancestry/v1 is the stable versioned envelope for clients that need release summaries, contract metadata, and explicit docs linkage.

Interpretation rule

Politics fields describe modeled geographic patterns, not observed individual voting behavior. Footprint fields describe share of total population reporting the ancestry in ACS 2024.

Endpoints

All public ancestry responses carry a describedby link header pointing back to this page.

Rows feed
/api/ancestry

Backward-compatible convenience feed. Returns a filtered array of ancestry rows with release and index labels on each row.

GET /api/ancestry?year=2024&kind=fine&index=index
Stable envelope
/api/ancestry/v1

Versioned contract. Returns filters, release summary, available years, model version, docs URL, and the filtered row set.

GET /api/ancestry/v1?year=2024&kind=fine&index=index
Dossier payload
/api/ancestry/{slug}

Returns the public ancestry dossier shell for one ancestry, including national footprint, top geographies, related groups, methodology, and provenance.

GET /api/ancestry/irish
Geography rankings
/api/ancestry/{slug}/geographies

Returns public state and county rankings for one ancestry dossier.

GET /api/ancestry/irish/geographies

Response semantics

These fields carry the release and confidence meaning for the public ancestry product.

Core fields
  • release_status: release state from the canonical ancestry taxonomy.
  • index_status: whether a dossier is intended for search indexing or atlas-only exposure.
  • public_release: true only when the ancestry belongs to the indexed public release set.
  • confidence_tier: current modeled confidence label from the latest completed ancestry model run.
  • display_mode: whether the current output is a point estimate, range-only estimate, or experimental output mode.
Type shape
interface AncestryRow {
  ancestry_slug: string;
  display_name: string;
  election_year: number;
  dem_margin_pct: number | null;
  confidence_tier: 'HIGH' | 'MEDIUM' | 'LOW' | 'EXPLORATORY';
  display_mode: 'point_interval' | 'range_only' | 'experimental';
  release_status: 'default' | 'eligible' | 'experimental' | 'excluded';
  index_status: 'index' | 'noindex';
  public_release: boolean;
}

Release states

Release labels come from the canonical ancestry taxonomy and drive indexing policy.

ELIGIBLE

39 indexed fine ancestries in the current public release. These pages appear in sitemap and carry indexable metadata.

EXPERIMENTAL

75 public atlas entries remain visible but noindex until promotion.

DEFAULT

Family rollups used in the ancestry model and public summaries.

EXCLUDED

Taxonomy entries intentionally omitted from the public ancestry explorer and export artifact.

Scope and limits

What these endpoints are, and what they are not.

Included
  • ACS 2024 ancestry footprint and geography rankings.
  • Modeled presidential geography from the latest completed ancestry model run.
  • Explicit release, indexing, and confidence labels.
Excluded
  • Observed individual vote behavior or respondent-level survey claims.
  • Paid developer platform guarantees from the authenticated /api/v1 product.
  • Any ancestry slug that remains excluded from the canonical taxonomy.
Return to ancestry atlasOpen methodology