API schema 1.0.0

Build against a public, documented county-data contract.

The v1 API uses canonical five-digit FIPS geography, explicit confidence labels, stable envelopes, pagination metadata, release identifiers, and CSV or ZIP bulk paths.

OpenAPI JSON Current manifest

Envelope: JSON responses return { data, meta }. Metadata includes generatedAt, source, schemaVersion, and releaseId. Live endpoints return releaseId: null; frozen manifests carry their dated ID. Collections also include total, limit, and offset. Errors use { data: null, error, meta } with the same schema metadata.

Core endpoints

Legacy unversioned endpoints remain available; new integrations should prefer v1.

GET/api/results?state=WI&year=2024&office=president&level=county

Normalized presidential result records by state and reporting grain

GET/api/sources?state=WI&year=2024

Source authority, provenance, confidence, and lifecycle status

GET/api/v1/flips

Paginated county comparisons and CSV export

GET/api/v1/counties/{fips}

One permanent county profile

GET/api/v1/jurisdictions

Paginated canonical county registry

GET/api/v1/jurisdictions/search

FIPS, county-name, and alias search

GET/api/v1/confidence

Shared confidence vocabulary

GET/api/v1/releases

Versioned public data release catalog

GET/api/v1/releases/{releaseId}/download

Product-specific immutable ZIP

GET/api/v1/equipment-systems

Feature-gated equipment catalog summaries

GET/api/v1/equipment-systems/{slug}

One source-linked equipment dossier

GET/api/district-compactness

Advisory 2024 district shape metrics and resolution guards

Quick start

Use the dataset catalog for documented presidential result downloads and state landing pages for crawlable result tables. Keep reporting grains separate and retain source and caveat fields. A live API retrieval timestamp is not a source publication date.

2020 to 2024 flips

curl "https://www.civicresultmaps.org/api/v1/flips?from=2020&to=2024&direction=blue_to_red&limit=100"

County profile

curl "https://www.civicresultmaps.org/api/v1/counties/40019"

Confidence vocabulary

Confidence describes the geography/source relationship, not whether a political outcome is credible.

exact

Exact reported geography

The published row maps directly to the canonical county or county-equivalent geography.

derived

Derived from official rows

The value is reproducibly aggregated, normalized, or calculated from official published rows.

partial

Partial coverage

An official row is available, but a field, jurisdiction, candidate total, or reconciliation item remains incomplete.

proxy

Contextual proxy

The value is contextual or supplemental and should not be treated as a silent replacement for an official certified total.

non_geographic

Non-geographic row

The reporting unit is statewide, UOCAVA, federal-only, or otherwise not a canonical county geography.

unavailable

Unavailable

No comparable canonical county row is available for this data point.

Pagination and bulk use

Interactive queries

Use limit and offset. Add view=compact for a national visualization payload; full JSON is capped at 1,000 rows. Filter server-side by year pair, direction, state, FIPS, or name.

Full-dataset workflows

Use a dated release ZIP instead of paging through live endpoints. Every archive includes caveats, a data dictionary, and the exact release manifest.