Official sources first Providers when needed Limits stated
Data sources
Data sources
Ballot Clarity uses official election sources first, then supporting civic-data systems when official material needs context. This page explains what each source class is used for and where its limits are.
Core source rules
- Publish official election logistics when official county and statewide resources are reviewed.
- Do not publish contest, candidate, or measure dossiers until Fulton-specific source records are verified.
- Keep route availability separate from verified local contest-package availability.
Ballot-content data providers
Provider ballot data is useful, but it is not the final ballot.
Connected provider records can help populate ballot previews, but a local guide is not considered verified until official state or county ballot tools and the review workflow confirm it.
Provider option Connected
Google Civic Information API
Official-source voter-information lookup, polling places, early voting, drop-off sites, and provider ballot previews where Voting Information Project data exists.
Capabilities, limits, and access
Capabilities
- election IDs
- polling places
- early vote sites
- drop-off locations
Limits
- Coverage is limited to supported elections and addresses.
- Provider ballot previews still need local review before Ballot Clarity treats them as a verified local guide.
Access status: Ballot Clarity can use this provider when its data is relevant.
Nonprofit provider Needs partner access
CTCL Ballot Information Project
Trusted national ballot backbone once CTCL grants direct Ballot Information Project access.
Capabilities, limits, and access
Capabilities
- address-and-election ballot lookup
- candidate records
- referenda
- OCD-ID geography linkage
Limits
- Direct API access is not public self-serve.
- Ballot Clarity needs a granted endpoint or data delivery before this connector can run.
Access status: Ballot Clarity is not currently using this provider for live ballot data.
Nonprofit provider Not connected
Ballotpedia API
Races, candidates, and ballot measures by location point or state/election date.
Capabilities, limits, and access
Capabilities
- elections by latitude and longitude
- elections by state
- races
- candidate lists
Limits
- Returned fields can depend on the purchased API package.
- Production browser-origin usage may require domain whitelisting by Ballotpedia.
- Ballot Clarity still needs official-source verification before publishing a reviewed local guide.
Access status: Ballot Clarity is not currently using this provider for live ballot data.
Provider option Needs partner access
BallotReady CivicEngine
Turnkey voter-guide style ballot matching, candidate profiles, issue content, and logistics if the licensing terms fit Ballot Clarity.
Capabilities, limits, and access
Capabilities
- GraphQL ballot data
- candidate profiles
- candidate issue content
- ballot measures
Limits
- Requires a partner account, endpoint, and pricing agreement.
- Republishing provider-authored profiles or issue content needs licensing review.
Access status: Ballot Clarity is not currently using this provider for live ballot data.
Nonprofit provider Not connected
Democracy Works Elections API
Election dates, deadlines, voting guidance, and Ballotpedia-sourced ballot data where Democracy Works coverage includes it.
Capabilities, limits, and access
Capabilities
- election discovery by address
- dates and deadlines
- voting guidance
- ballot measures with includeBallotData
Limits
- Ballot data is not the default response and must be requested with includeBallotData=true.
- Local ballot coverage can be limited by provider mapping constraints.
- Ballot data is sourced from Ballotpedia, so provenance should not be presented as independent official verification.
Access status: Ballot Clarity is not currently using this provider for live ballot data.
Source categories
What each source class is used for
Most readers only need the rule and the current use case. Expand a source class if you want provider details, limits, and links.
Address and district lookup
A live Ballot Clarity build should treat district assignment as its own subsystem, with versioned geography and explicit as-of timestamps.
Authoritative rule
District assignment should be grounded in official geography, not inferred from a vendor profile alone.
Live approach
Use Census geocoding plus versioned district boundaries, then cache address-to-jurisdiction matches with benchmark or vintage metadata.
Official source Planned live source
Census Geocoder with geoLookup
Baseline address normalization and geography lookup for a defensible district-assignment pipeline.
Coverage
United States, Puerto Rico, and U.S. island areas
Update pattern
Versioned by benchmark and vintage
Best use: Address-to-jurisdiction matching and cached district lookup.
- Keep benchmark and vintage in cache keys so district assignments remain auditable.
- Treat geocoding as a high-risk dependency and design a stale-cache fallback.
Official source Planned live source
TIGER/Line shapefiles
Versioned geometry layer for districts, places, and other jurisdiction boundaries.
Coverage
National district and administrative boundaries
Update pattern
Released by vintage year
Best use: Offline district joins, reproducible geography snapshots, and geospatial audits.
- Useful when the product needs to explain which district model was in force on a given date.
- Should stay separate from election-office content and polling-place feeds.
Provider option Reference pattern
Google Civic Divisions lookup
Useful as an OCD-ID bootstrap, but not a substitute for canonical district storage.
Coverage
Supported U.S. elections and OCD-ID lookup flows
Update pattern
Provider-controlled
Best use: Supplemental division lookup after the Representatives API sunset.
- The Google Civic Representatives API ended on April 30, 2025.
- District lookup should stay decoupled from any provider-specific official lookup endpoint.
Ballots, deadlines, and polling places
Election logistics change quickly, so Ballot Clarity relies on official election offices plus national providers for scale.
Authoritative rule
Election-office notices remain the final authority for deadlines, polling-place changes, and ballot-return instructions.
Live approach
Store official notices as the verification layer, then use a provider-normalized ballot API for address-to-ballot lookup and contest packaging.
Official source Planned live source
Official election office notices and VIP-style feeds
Primary authority for deadlines, polling locations, drop boxes, and final ballot instructions.
Access
Official notices or standardized feed publishing
Coverage
State and local election logistics
Update pattern
High-frequency during election windows
Best use: User-facing verification links, change logs, and last-mile corrections.
- Polling-place changes should degrade to cached data with a visible may-be-stale warning if an upstream feed fails.
- The HTML location hub should always link back to the election office before a user prints or travels.
Nonprofit provider Planned live source
National elections provider (Democracy Works-style)
Fastest path to national ballot and polling-place coverage without bespoke county-by-county scraping.
Coverage
Federal, state, county, municipal, and other local elections
Update pattern
Continuously refreshed by provider pipeline
Best use: Ballot packaging, election calendars, and personalized lookup at national scale.
- Provider data should not replace official links; it should normalize and distribute them.
- Keep provider-specific field mapping isolated behind an internal ballot service.
Provider option Reference pattern
Commercial ballot matching provider (BallotReady-style)
Useful when a faster turnkey ballot product matters more than owning the normalization layer internally.
Coverage
Personalized ballots, contests, measures, and voting logistics
Update pattern
Provider-controlled refresh
Best use: High-velocity partnerships or embedded ballot widgets.
- Treat vendor provenance and licensing as product decisions, not just engineering details.
- Still keep official election-office links visible on every logistics surface.
Candidate lists, filings, and ballot text
Candidate and measure surfaces should combine official filing lists with clearly labeled candidate-supplied and nonprofit-context layers.
Authoritative rule
Official filing lists and certified ballot text outrank campaign or nonprofit summaries.
Live approach
Store official candidate lists and ballot text as the base record, then layer questionnaires or explanatory summaries with explicit provenance labels.
Official source Planned live source
Official candidate filing lists and certified ballot text
Canonical ballot-status, office, and text layer for contests and measures.
Access
Official notices, PDFs, HTML pages, or exports
Coverage
Federal, state, and local election records where available
Update pattern
Election-window updates plus certification changes
Best use: On-ballot verification, official wording, and candidate roster checks.
- Local formats will vary widely, so connectors must tolerate PDFs, HTML tables, and manual corrections.
- Candidate status should surface an as-of timestamp and the source system used to verify it.
Nonprofit provider Reference pattern
Nonprofit questionnaires and civic records
Useful for comparable issue statements when official records alone do not explain a candidate's stated priorities.
Access
Questionnaire archive or civic data feed
Coverage
Selected races and issue areas
Update pattern
Per questionnaire cycle
Best use: Side-by-side compare tables and clearly labeled candidate-submitted answers.
- Candidate-submitted material should never be mistaken for verified official text.
- Missing responses should be shown explicitly instead of omitted.
Campaign finance and lobbying
Money and influence modules should come from independent federal pipelines so failures there cannot block ballot lookup.
Authoritative rule
Federal money and lobbying sections should resolve back to the official disclosure system, not a derivative summary alone.
Live approach
Ingest these domains separately from election lookup, then join them onto candidate pages through stable IDs and manual crosswalks where necessary.
Official source Planned live source
FEC OpenFEC API and bulk files
Authoritative federal finance layer for candidates, committees, filings, and contribution patterns.
Access
API and bulk files
Coverage
Federal campaign finance only
Update pattern
Nightly refresh with cached responses
Best use: Candidate funding overviews, committee context, and reproducible finance snapshots.
- Treat the FEC cache window as part of freshness logic rather than assuming continuous real time.
- Use bulk files for warehousing and API calls for interactive page queries.
Official source Planned live source
Senate LDA and LDA.gov disclosures
Authoritative federal lobbying layer for registrants, clients, and filed reports.
Access
API and bulk files
Coverage
Federal lobbying disclosures
Update pattern
Quarterly filings plus current-year reports
Best use: Lobbying context sections and independent influence pipelines.
- Keep the Senate LDA integration isolated so endpoint migrations do not affect ballot lookup.
- The older lda.senate.gov docs path is scheduled to retire after June 30, 2026.
Historical results and research archive
Historical datasets are useful for analysis and context, but they should stay out of the critical path for where-do-I-vote workflows.
Authoritative rule
Research and historical context should be clearly labeled as archival or analytical, not as a live logistics source.
Live approach
Store these datasets in a separate analytics layer so archival work does not interfere with election-day reliability.
Open data Research layer
OpenElections
Useful for historical results warehousing and state-by-state archive work.
Access
Bulk repository files
Coverage
Historical election results by state and year
Update pattern
Community-maintained
Best use: Election history, comparison context, and analytics backfills.
- Not a replacement for current polling-place or ballot lookup.
- Parser quality and completeness will vary by state and cycle.
Open data Research layer
MIT Election Data and Science Lab
High-value archive layer for benchmarking and public-interest analysis work.
Coverage
Research-grade election history and related datasets
Update pattern
Dataset-specific releases
Best use: Longitudinal research, modeling, and historical context pages.
- Keep these datasets behind an analytics boundary, not in the critical request path.
- Useful once Ballot Clarity adds post-election archive and results views.