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/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 national release catalog

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

Complete national ZIP

GET/api/v1/equipment-systems

Feature-gated equipment catalog summaries

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

One source-linked equipment dossier

Quick start

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.